Claude Code 설정 키 레퍼런스

Claude Code의 settings.json(Claude Code 설정 파일, 용어 사전) 키 중 에이전트 활용과 관리자 통제에 쓰는 것을 주제별 표로 모은 찾아보기 페이지다. 어느 파일에 둘지와 우선순위는 Claude Code 설정 파일, 조직 배포는 managed settings, 관리자 질문별 근거는 Claude Code 관리자 권한 통제에 있다.

이 페이지에 담은 범위#

원본 색인 표는 키 245개(global config 포함)를 싣는다. 이 페이지는 다음 기준으로 골랐다.

• 담았다: 권한·자동 모드, 샌드박스의 강제·잠금 키, 훅, 플러그인·스킬·마켓플레이스, MCP, 모델 선택·잠금, 메모리·컨텍스트(CLAUDE.md, 자동 메모리, 컴팩션, env, 스킬 목록 예산), 서브에이전트·세션, 그리고 조직 관리자용(Scope Managed) 키와 감사·데이터 보존에 닿는 키.
• 뺐다: 터미널 표시·입력 키(theme, tui, spinner 계열, voice, editorMode, timeFormat, statusLine 등), ~/.claude.json에만 두는 global config 키 12개, 데스크톱 앱 전용 키(Browser pane·iOS Simulator·SSH 세션·disableDesktopLocalSessions·worktree.location), 샌드박스 자격 증명 mask 세부 필드와 AWS 재서명·프록시·Unix 소켓 세부, 마켓플레이스 출처 매칭 세부 규칙, 클라우드 제공자 인증 helper(awsAuthRefresh 등)와 게이트웨이 로그인 키, 알림·원격 제어 표시 키, fast mode·advisor·modelPicker·modelOverrides·prompt cache 키. 없어졌거나 대체된 키는 마지막 절에 이름만 적었다.

Scope 읽는 법#

Any file 키 중에도 항목의 Scope 줄이 따로 제한을 붙인 것이 많다(예: "a repository can turn the block on for itself but can't lift yours"). 아래 표의 Scope 칸에 그 제한을 함께 적었다. Claude Code 설정 키 전체 레퍼런스

1. 권한·자동 모드#

규칙 문자열 자체의 문법(Tool(specifier), Bash 와일드카드, 경로 패턴 //·~/·/·./, 도구별 규칙)은 공식 권한 문서(2026-10-21) 기준으로 Claude Code 권한 규칙 문법에, 공유 파일의 allow·additionalDirectories가 신뢰 뒤 적용되는 규칙은 작업 공간 신뢰에 있다.

autoMode 두 줄 보충(공식 자동 모드 설정 문서, 2026-10-21 기준): 분류기는 autoMode를 ~/.claude/settings.json, managed settings, --settings 플래그·Agent SDK의 인라인 JSON에서 읽고, 프로젝트 .claude/settings.json·.claude/settings.local.json에서는 읽지 않는다(저장소가 allow 규칙을 주입하지 못하게). 범위별 항목은 합쳐지고 개발자는 managed 항목을 지우지 못하지만, 개발자의 allow가 조직의 soft_deny를 넘을 수 있어 "not a hard policy boundary"다. classifyAllShell의 기본(false)에서도 Monitor를 이름으로 대는 규칙은 정지되고, true여도 치명 경로 삭제는 예외다. 배열 항목은 자연어 문장이고, "$defaults"를 빼면 그 섹션의 내장 목록 전체가 사라진다. 형식·원본 예시·우선순위는 Claude Code 자동 모드 설정하기. Claude Code 자동 모드 설정

원본 예:

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

2. 샌드박스 (강제·잠금 키)#

managed가 enabled·failIfUnavailable 같은 Boolean을 두면 개발자 값을 덮고, 배열 키는 범위끼리 합쳐 개발자가 항목을 더할 수 있다. 원본 예: managed에 "sandbox": {"enabled": true, "failIfUnavailable": true}를 두면 모든 관리 기기가 샌드박스로 명령을 돌리거나 시작을 거부한다.

공식 Sandboxing 문서로 확인·보강 (2026-10-21 기준). 위 표의 키를 샌드박스 전용 문서가 같은 내용으로 확인하고, 다음을 더한다. 개념과 한계는 샌드박스, 설정 절차와 원문 예시는 Claude Code 샌드박스 설정하기. Claude Code 샌드박스

• 적용 대상: sandbox.enabled가 감싸는 것은 Bash만이 아니라 Bash·PowerShell·Monitor 명령과 그 하위 프로세스다. Read·Edit·WebFetch 같은 내장 도구, 훅, 로컬 MCP 서버, ! 셸 모드에 직접 친 명령(대부분의 세션)은 샌드박스 밖에서 돈다.
• sandbox.failIfUnavailable: 샌드박스 문서도 기본이 fail open(샌드박스 없이 실행)이라고 확인한다. Windows 네이티브에서는 샌드박스가 돌지 않으므로 이 키가 켜져 있으면 시작 때 종료한다.
• sandbox.autoAllowBashIfSandboxed: deny 규칙과 내용 지정 ask 규칙 외에도, 치명 경로를 겨냥한 rm·rmdir, Monitor 명령, 실행 프로그램이 바뀔 수 있는 명령(FOO=bar npm test, make CC=clang, eval "ls")은 자동 승인되지 않는다. 맨 Bash ask 규칙은 plan 모드에서는 건너뛰지 않는다. 명령에 맞는 allow 규칙은 그 명령의 샌드박스 밖 재시도도 승인한다.
• sandbox.excludedCommands: 패턴은 Bash(...) 규칙 문법이라 *로 끝내야 인자 있는 호출에 맞고, 호출 안의 모든 명령이 맞아야 하며, 명령 줄 텍스트만 맞춘다(스크립트 안의 호출, /usr/local/bin/docker는 안 맞음). 리디렉션·cd·$(...)가 있으면 호출 전체가 샌드박스에 남는다. 제외된 명령은 파일 제한도 네트워크 프록시도 없이 전체 권한으로 돌고 일반 권한 흐름을 탄다. 이 문서도 관리자 필수 샌드박스에서는 저장소 파일 항목만 무시한다고 확인한다(v2.1.285 이상, v2.1.282~v2.1.284는 같은 설정이 저장소 excludedCommands만 무시).
• sandbox.allowUnsandboxedCommands: false면 dangerouslyDisableSandbox 파라미터를 무시한다. user false는 관리자 필수를 만들지 않으므로 저장소의 다른 샌드박스 설정은 계속 적용된다. 재시도 승인 주체는 권한 모드가 정한다(bypassPermissions 묻지 않음, Manual·acceptEdits 확인 창, 자동 모드 분류기, dontAsk 거부).
• 관리자 필수 샌드박스에서 저장소 파일이 무시되는 설정(v2.1.285 이상. v2.1.282~v2.1.284는 excludedCommands만, Claude Code 샌드박스): excludedCommands, ignoreViolations, network.allowedDomains·allowUnixSockets·allowMachLookup·httpProxyPort·socksProxyPort의 모든 항목, filesystem.allowWrite·Edit(...) allow·additionalDirectories가 샌드박스 명령에 주는 쓰기, WebFetch(domain:...) allow가 더하는 호스트, 약화 키 4개의 true, 개발자가 true로 둔 enabled·failIfUnavailable의 false, managed·--settings·user가 읽기를 막은 경로나 그 아래를 가리키는(또는 그런 경로에 맞을 수 있는 glob) filesystem.allowRead 항목. 저장소의 deny 항목과 autoAllowBashIfSandboxed 값은 계속 적용된다.
• 문서가 더 다루는 키(표에 없는 것): filesystem.allowWrite·denyWrite·allowRead, network.deniedDomains, network.tlsTerminate(실험), network.httpProxyPort·socksProxyPort, network.allowLocalBinding, network.allowAllUnixSockets, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents(프로젝트 설정에서 켤 수 없음). 각 키의 조건은 Claude Code 샌드박스 설정하기.

3. 훅·자동화#

4. 플러그인·스킬·마켓플레이스#

5. MCP#

6. 모델 선택과 잠금#

7. 메모리·컨텍스트#

8. 서브에이전트·세션#

9. 조직 관리·감사·데이터#

없어졌거나 대체된 키 (2026-10-21 기준)#

taskOutputMaxChars(v2.1.277에서 제거), teammateDefaultModel(v2.1.234 제거), permissionExplainerEnabled(v2.1.257 제거), keybindingFlavor(v2.1.261부터 효과 없음), includeCoAuthoredBy(→ attribution), voiceEnabled(→ voice), disableArtifact(→ enableArtifact). Claude Code 설정 키 전체 레퍼런스

관련#

• 파일 위치·우선순위·예외 표: Claude Code 설정 파일, 바꾸고 확인하는 법: Claude Code 설정 바꾸기·확인·문제 해결
• 조직 배포와 출처 합치기: managed settings, Claude Code managed settings 배포·점검
• 권한 키를 고객 질문별로: Claude Code 관리자 권한 통제, 모드 개념: 권한 모드
• 키가 다루는 기능: 훅, MCP, 플러그인, 스킬, 서브에이전트, 자동 메모리(Auto memory), 장기 작업 컨텍스트 관리