Claude Code 설정 키 전체 레퍼런스

한 줄 요약: Claude Code 공식 문서 "All settings"(settings reference). settings.json이 읽는 키 전부와 ~/.claude.json에 두는 global config 키를 한 문서에 모아, 키마다 놓일 수 있는 파일(Scope), 타입, 기본값, 한 세션 덮어쓰기(플래그·환경 변수), 필요한 최소 버전, 붙여 넣을 수 있는 예시를 적는다. 어느 파일에 둘지·우선순위는 Claude Code 설정 파일과 우선순위가 맡고, 이 문서는 "그 키 하나가 정확히 무엇을 하나"를 맡는다.

원본 정보#

• 제목: All settings
• 발행: Anthropic, Claude Code 공식 문서. 본문에 날짜 없음(원본 날짜 미상). 서버 Last-Modified 2026-10-20
• URL: https://code.claude.com/docs/en/settings-reference (새 창)
• 수집(fetch)일: 2026-10-21. 본문의 키 이름, 기본값, 버전 조건(v2.1.1xx~v2.1.3xx, Claude Desktop 버전)은 이 날짜 기준이다.
• 구성: 키 색인 표(키·설명·주제·Scope) → 주제별 항목 15개 절(모델, 권한, 샌드박스, 메모리·컨텍스트, 인터페이스, Git, 훅, 플러그인·스킬, MCP, 에이전트·세션, 원격·데스크톱, 인증, 업데이트, 도구, 개인정보, 기업·managed, global config).

핵심 주장#

1. 키마다 놓일 수 있는 파일이 정해져 있다. 색인의 Scope 열은 User(~/.claude/settings.json), Project(.claude/settings.json), Local(.claude/settings.local.json), Managed(조직 배포), 넷 다를 뜻하는 Any file, ~/.claude.json을 뜻하는 Global config로 적는다. 그 밖에 User or managed, User, local, or managed 같은 좁은 Scope가 있다. 좁은 Scope 키의 상당수는 항목에 "A repository can't turn it off for you"나 "A repository can't turn it on or off"처럼 저장소 파일이 할 수 없는 일을 직접 적는다. → Claude Code 설정 키 레퍼런스
2. disableAutoMode는 최상위 키이고, permissions 아래도 받는다. 색인이 최상위 키로 싣고, 항목 예시가 최상위 "disableAutoMode": "disable"이며, Scope 줄이 "Also accepted under permissions as permissions.disableAutoMode"라고 하고, permissions 객체의 타입 목록에도 disableAutoMode가 들어 있다. Scope는 Any file이며 원본은 "Most useful in managed settings, where users can't override it"이라고 한다. 반면 disableBypassPermissionsMode는 permissions 안의 키다. → Claude Code 관리자 권한 통제의 상충 해소
3. 보안 성격의 키 상당수는 "어느 파일의 제한 값이든 적용, 저장소는 켤 수만 있다" 패턴을 항목에 적는다. 예: permissions.blockReadsOutsideWorkingDirectories는 "A true in any file applies, so a repository can turn the block on for itself but can't lift yours", disableClaudeAiConnectors는 project false가 user·managed true를 덮지 못하고, isolatePeerMachines는 저장소가 켤 수는 있어도 끌 수 없으며, remoteControlAtStartup은 project·local의 true를 무시한다. 반대로 Scope를 좁혀 저장소 파일 값을 받지 않는 키도 있다. skipDangerousModePermissionPrompt와 useAutoModeDuringPlan은 User, local, or managed라 공유 .claude/settings.json 값을 받지 않고, sandbox.network.strictAllowlist·sandbox.network.tlsTerminate는 User or managed다. pluginConfigs는 project·local 항목을 무시하고, bashEditDiffEnabled는 저장소 파일의 true를 무시하되 false는 받는다. → Claude Code 설정 키 레퍼런스
4. 차단 키에는 한계가 항목 안에 함께 적혀 있다. permissions.deny의 Read·Edit 규칙은 내장 파일 도구, Claude Code가 알아보는 Bash 파일 명령(cat·head·tail·sed·tee), 리디렉션 대상에 적용되고, 파일 이름을 대지 않는 grep -r pattern .이나 임의의 하위 프로세스에는 적용되지 않으므로 OS 수준 강제는 샌드박스를 켜라고 한다. Bash(curl *) deny는 /usr/bin/curl이나 sh -c 'curl …'을 막지 않는다. sandbox.enabled는 샌드박스가 못 뜨면 failIfUnavailable이 없는 한 샌드박스 없이 명령을 돌린다. sandbox.excludedCommands는 "a convenience, not a security boundary"다. workflowSizeGuideline은 강제 상한이 아니라 조언이다. → Claude Code 관리자 권한 통제, 권한 모드
5. 조직 관리자용 키는 Scope Managed로 묶인다. 모델 잠금(deniedModels·availableModelsMatch, v2.1.283 이상), 정가 대신 계약 단가로 비용 표시(modelPricing, v2.1.242 이상), 제공자 제한(allowedProviders, v2.1.285 이상), 시작 버전 범위(requiredMinimumVersion·requiredMaximumVersion, v2.1.163 이상), 권한·훅·MCP·샌드박스 도메인을 managed 값으로만 제한하는 allowManaged*Only 계열, 마켓플레이스·커스터마이징 잠금(strictKnownMarketplaces, strictPluginOnlyCustomization), CLI 우회 플래그 거부(disableSideloadFlags, v2.1.193 이상), 원격 설정을 새로 받아야 시작(forceRemoteSettingsRefresh), 관리 출처 합치기(managedSourcesBehavior), 시작 때 정책을 계산하는 실행 파일(policyHelper). → managed settings

원본의 절차·예시 (2026-10-21 기준)#

• 자동 모드 제거: {"disableAutoMode": "disable"}. --permission-mode auto, 설정 파일, 내장 기본값 어느 쪽으로 자동 모드로 시작하려던 세션도 default로 시작한다.
• 권한 블록 예: allow Bash(npm run *), ask Bash(git push *), deny Read(./.env), defaultMode acceptEdits. 규칙은 deny → ask → allow 순으로 평가하고, 구체성과 상관없이 처음 맞는 규칙이 정한다.
• 샌드박스 강제: managed에 sandbox.enabled: true와 failIfUnavailable: true를 두면 모든 관리 기기가 샌드박스로 명령을 돌리거나 시작을 거부한다. allowUnsandboxedCommands: false는 strict sandbox mode다.
• 훅 잠금: allowManagedHooksOnly: true면 managed 훅, Agent SDK 훅, managed enabledPlugins로 강제 활성화한 플러그인의 훅만 돌고 user·project·local 훅, 다른 플러그인의 훅·mod, 에이전트 frontmatter 훅은 막힌다. 이때 /goal 명령은 돌지 않는다.
• 조직 CLAUDE.md를 파일 없이 넣기: managed claudeMd에 Markdown 문자열. 사용자·프로젝트의 claudeMdExcludes로 managed CLAUDE.md는 뺄 수 없다.
• 마켓플레이스 잠금: strictKnownMarketplaces에 빈 배열이면 공식 Anthropic 마켓플레이스까지 모든 출처를 막는 완전 잠금이다. 공식 마켓플레이스만 허용하는 예와, 허용과 사전 등록을 함께 하는 extraKnownMarketplaces 조합.

원본이 링크한 관련 문서#

Configure permissions(규칙 문법 전체, 작업 공간 신뢰 → Claude Code 권한 설정), Sandboxing(→ Claude Code 샌드박스), Configure auto mode(→ Claude Code 자동 모드 설정), Model configuration, Managed MCP, Server-managed settings, Admin setup, Environment variables, Plugins(마켓플레이스·mods), Workflows, Agent view, Remote Control, Cross-session messaging, Prompt caching, Debug your configuration, Example settings files.