설정 파일 (settings.json)

사용자, 프로젝트, Managed 레벨의 JSON 설정 파일로 Claude Code 동작 설정.

Claude Code는 여러 범위의 JSON 파일에서 설정을 읽습니다. 낮은 우선순위에서 높은 우선순위 순으로 병합됩니다.

설정 파일 위치

전역(사용자): ~/.claude/settings.json 모든 프로젝트에 걸쳐 실행하는 모든 Claude Code 세션에 적용됩니다. 선호 모델, 테마, 정리 정책 같은 개인 설정을 여기에 설정합니다.

프로젝트(공유): .claude/settings.json (프로젝트 루트) 소스 컨트롤에 체크인됩니다. 프로젝트 작업자 모두에게 적용되어야 하는 설정 — 권한 규칙, 훅 설정, MCP 서버, 환경 변수.

로컬(개인 프로젝트): .claude/settings.local.json (프로젝트 루트) 소스 컨트롤에 체크인되지 않습니다(자동으로 .gitignore에 추가됨). 특정 프로젝트 내의 개인 재정의.

Managed(엔터프라이즈): 플랫폼별 시스템 경로 MDM, 레지스트리(Windows), plist(macOS), 또는 Managed 설정 파일을 통해 관리자가 설정합니다. Managed 설정은 최고 우선순위를 가지며 사용자나 프로젝트가 재정의할 수 없습니다.

설정 우선순위

플러그인 기본값 → 사용자 설정 → 프로젝트 설정 → 로컬 설정 → Managed(정책) 설정

Managed(정책) 설정은 항상 최종 우선순위를 가집니다.

설정 열기

세션 내에서 /config를 실행해 설정 UI를 엽니다. 각 범위의 현재 활성 설정을 찾아볼 수 있습니다. JSON 파일을 직접 편집할 수도 있습니다 — Claude Code가 파일 변경을 감지하면 자동으로 설정을 다시 로드합니다.

설정 레퍼런스

`model`

타입: string | 범위: 모든 범위

Claude Code가 사용하는 기본 모델 재정의. 설정된 공급자가 지원하는 모든 모델 ID 허용.

{ "model": "claude-opus-4-5" }

`permissions`

타입: object | 범위: 모든 범위

Claude가 사용할 수 있는 도구와 모드를 제어합니다. 규칙 구문은 권한 시스템 참조.

필드	타입	설명
`allow`	`string[]`	Claude가 확인 없이 수행할 수 있는 작업 규칙
`deny`	`string[]`	Claude가 항상 차단되는 작업 규칙
`ask`	`string[]`	항상 확인을 요청하는 작업 규칙
`defaultMode`	`string`	기본 권한 모드: `"default"`, `"acceptEdits"`, `"plan"`, `"bypassPermissions"`
`disableBypassPermissionsMode`	`"disable"`	사용자가 bypass permissions 모드에 들어가는 것을 방지
`additionalDirectories`	`string[]`	Claude가 접근할 수 있는 추가 디렉토리

`hooks`

타입: object | 범위: 모든 범위

도구 실행 전후에 커스텀 셸 커맨드를 실행합니다. 지원 훅 이벤트: PreToolUse, PostToolUse, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, PreCompact, PostCompact.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
      }
    ]
  }
}

`cleanupPeriodDays`

타입: integer | 기본값: 30 | 범위: 모든 범위

채팅 트랜스크립트 보관 일수. 0으로 설정하면 세션 영속성이 완전히 비활성화됩니다.

`env`

타입: object | 범위: 모든 범위

모든 Claude Code 세션에 주입할 환경 변수. 값은 문자열로 변환됩니다.

{
  "env": {
    "NODE_ENV": "development",
    "MY_API_URL": "https://api.example.com"
  }
}

`availableModels`

타입: string[] | 범위: Managed만

사용자가 선택 가능한 모델의 엔터프라이즈 허용 목록. 패밀리 별칭("opus"는 모든 Opus 버전 허용), 버전 프리픽스, 또는 전체 모델 ID 허용.

`worktree`

타입: object | 범위: 모든 범위

--worktree 플래그 동작 설정.

필드	타입	설명
`symlinkDirectories`	`string[]`	worktree에 메인 저장소에서 심링크할 디렉토리 (예: `"node_modules"`)
`sparsePaths`	`string[]`	대규모 모노레포에서 빠른 worktree를 위한 sparse 체크아웃 경로

`attribution`

타입: object | 범위: 모든 범위

Claude가 커밋과 PR 설명에 추가하는 어트리뷰션 텍스트를 커스터마이징합니다.

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "pr": ""
  }
}

`language`

Claude 응답과 음성 받아쓰기에 선호되는 언어. { "language": "korean" }

`alwaysThinkingEnabled`

기본값: true — false로 설정해 확장 thinking 비활성화.

`effortLevel`

"low" | "medium" | "high" — thinking 예산을 지원하는 모델의 effort 레벨.

`autoMemoryEnabled`

범위: 사용자, 로컬 — 이 프로젝트의 자동 메모리 활성화 또는 비활성화.

`respectGitignore`

기본값: true — 파일 피커가 .gitignore 파일을 존중할지 여부.

`defaultShell`

"bash" | "powershell" — 입력 박스의 ! 커맨드용 기본 셸.

`apiKeyHelper`

범위: 사용자, Managed — API 키를 동적으로 검색하는 스크립트 경로. 스크립트는 stdout에 API 키만 출력하고 코드 0으로 종료해야 합니다.

Managed 설정 (엔터프라이즈)

관리자는 플랫폼 네이티브 메커니즘을 통해 모든 사용자에게 설정을 배포할 수 있습니다.

macOS: /Library/Preferences/에 plist 파일 배포 또는 MDM을 통해 com.anthropic.claudecode 타겟

Windows: HKLM\Software\Anthropic\Claude Code 레지스트리 키에 설정 작성

파일 기반: Managed 설정 파일을 플랫폼별 managed 경로에 배치. 드롭인 설정 조각에는 managed-settings.d/ 디렉토리 사용(알파벳 순으로 정렬 및 병합됨).

Managed 전용 잠금 설정

설정	설명
`allowManagedHooksOnly`	`true`로 설정 시 Managed 설정의 훅만 실행
`allowManagedPermissionRulesOnly`	`true`로 설정 시 Managed 설정의 권한 규칙만 존중
`allowManagedMcpServersOnly`	`true`로 설정 시 허용 MCP 서버 목록을 Managed 설정에서만 읽음
`strictPluginOnlyCustomization`	특정 커스터마이징 표면을 플러그인 전용 소스로 잠금

JSON 스키마

에디터 자동완성 및 유효성 검사를 위해 설정 파일에 $schema 추가:

{
  "$schema": "https://schemas.anthropic.com/claude-code/settings.json"
}