전체 설정 키 레퍼런스

전체 설정 키 레퍼런스 (All settings)

이 페이지는 Claude Code의 모든 설정 키를 주제별로 정리한 완전한 레퍼런스입니다. 각 키에는 설정할 수 있는 파일(스코프), 타입, 기본값, 예시가 나옵니다. 키를 찾으려면 Ctrl+F로 검색하거나 주제별 섹션을 탭으로 탐색합니다. /config는 이 페이지의 일부만 편집합니다.

출처: 공식문서

본문

스코프(설정 위치) 표기

각 키의 Scope(스코프) 열은 그 키를 설정할 수 있는 곳을 뜻합니다. User(~/.claude/settings.json), Project(.claude/settings.json), Local(.claude/settings.local.json), Managed(managed-settings.json), Global config(~/.claude.json), CLI flags, Environment variables 등이 조합으로 표시됩니다. 같은 키를 여러 곳에 두면 설정 우선순위에 따라 가장 높은 레벨의 값이 이깁니다. $schema로 json.schemastore.org의 claude-code-settings.json을 참조하면 에디터 자동완성·검증을 받을 수 있습니다.

모델·가격 (Model & pricing)

  • model — 세션 시작 기본 모델. 타입: string(예 "claude-sonnet-5"). Session start에 읽힘.
  • fallbackModel — 기본 모델 실패 시 대체 모델(rate limit 등). 순서가 의미 있는 사슬.
  • modelSettings / modelOverrides — 모델별 설정·오버라이드.
  • effortLevel — 기본 노력 수준(minimal·low·medium·high·xhigh).
  • availableModels — 사용 가능한 모델 목록(제한). enforceAvailableModels: true로 강제.
  • maxEffortLevel — 노력 수준 상한(관리). v2.1.267+.

권한 (Permissions)

  • permissions.allow / permissions.ask / permissions.deny — 권한 규칙 배열(예 "Bash(npm run test)", "Read(./.env)"). allow와 ask는 목록이 병합되고, 폴더 신뢰 후에 적용되며, deny·ask는 즉시 적용.
  • permissions.defaultMode — 기본 권한 모드(default·acceptEdits·plan·bypassPermissions·auto). 스코프 제약: auto·bypassPermissions는 프로젝트/로컬에선 안 먹힘.
  • permissions.additionalDirectories — 추가 허용 디렉토리.
  • disableBypassPermissionsMode — bypass 권한 모드를 끔(값 disable). 관리 배포용.
  • requireSpecificMode — 특정 권한 모드만 허용(관리).
  • allowManagedPermissionRulesOnly — 관리 권한 목록만 적용(관리).

샌드박스 (Sandboxing)

  • sandbox.enabled — 샌드박스 켜기(boolean).
  • sandbox.network.allowedDomains — 허용 도메인(registry.npmjs.org, *.example.com).
  • sandbox.network.allowManagedDomainsOnly — 관리 도메인만(관리).
  • sandbox.filesystem.allowWrite — 쓰기 허용 경로(/tmp/build).
  • sandbox.filesystem.denyRead — 읽기 거부 경로 — 샌드박스 명령이 읽지 못하게 Read deny 경로를 추가.
  • sandbox.failIfUnavailable — 샌드박스 불가 시 기동 거부(관리).
  • sandbox.allowUnsandboxedCommands — 비샌드박스 재시도 허용 여부(기본 true, 관리에서 false로).

메모리·컨텍스트 (Memory & context)

  • autoMemoryEnabled — 자동 메모리 켜기(boolean, 기본 true). CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 env로도.
  • autoMemoryDirectory — 자동 메모리 저장 위치.
  • claudeMdExcludes — CLAUDE.md 로드에서 제외할 경로 패턴(모노레포용).
  • cleanupPeriodDays — 세션 기록·로컬 데이터 보존 일수(예 20, 관리에서 7).

인터페이스 (Interface)

  • theme — 터미널 테마(dark·light·light-daltonized 등).
  • editorMode — 입력 에디터(default·vim).
  • statusLine — 상태줄 구성({ "type": "command", "command": "...", "padding": 2 }).
  • spinnerTipsEnabled — 스피너 아래 팁 표시(boolean).
  • preferredNotifChannel — 알림 채널(terminal_bell, iterm2, vscode_notification 등).
  • verbose — verbose 로그(boolean).
  • outputStyle — 출력 스타일.
  • modelPicker — 모델 픽커 행 목록 + replace 플래그. 병합 안 함. v2.1.242+.

동작 (Behaviors)

  • hooks — 훅 정의(PreToolUse, PostToolUse 등 이벤트별 matcher 배열).
  • env — 세션에 주입할 환경변수 객체. 관리 env는 스트릭트 적용.
  • apiKeyHelper — API 키를 동적으로 얻는 헬퍼 명령.
  • extraKnownMarketplaces — 추가 플러그인 마켓플레이스.
  • strictKnownMarketplaces — 허용 마켓플레이스만(관리).
  • enabledPlugins — 활성화할 플러그인({"code-formatter@acme-tools": true}).
  • plansDirectory — 플랜 파일 저장 위치(예 ./plans).
  • autoUpdatesChannel — 업데이트 채널(stable·latest).
  • disableClaudeAiConnectors — claude.ai 커넥터 비활성화(어느 스코프든 true 존중).
  • syncClaudeAiSkills — 클라우드 스킬 동기화(관리에서 off 가능).
  • allowedMcpServers·allowManagedMcpServersOnly — MCP 서버 URL 허용 목록(관리).

글로벌 설정 키 (Global config, ~/.claude.json)

/config가 쓰는 키 중 글로벌 설정은 ~/.claude.json에 저장됩니다. 스코프가 Global config로 표시된 키는 settings.json에는 못 두고 ~/.claude.json에만 둡니다(예 includeCoAuthoredBy, preferredNotifChannel 등 일부).

더 알아보기