설정 파일과 우선순위

설정 파일과 우선순위 (Settings files and precedence)

Claude Code의 동작은 JSON 설정 파일 몇 개로 바꿀 수 있습니다. 어떤 파일에 키를 두느냐가 그 설정이 누구에게 적용되는지를 결정하고, 같은 키가 여러 곳에 있으면 우선순위가 높은 곳의 값이 이깁니다. 이 페이지는 스코프(범위)별 파일 선택법, /config·파일 편집·CLI로 값을 바꾸는 법, 그리고 /status로 적용 확인하는 법을 다룹니다.

출처: 공식문서

본문

설정 파일과 적용 대상

Claude Code는 네 개 파일에서 설정을 읽고, 조직은 claude.ai 콘솔로 관리 설정(managed settings)을 내려줄 수 있습니다. 각 소스는 스코프를 갖습니다.

스코프	파일	적용 대상	용도
User	`~/.claude/settings.json`	이 머신의 모든 프로젝트에서 나	테마·에디터 모드·기본 모델·내 권한 규칙
Shared project	`.claude/settings.json`	그 폴더에서 작업하는 모두 (git에 커밋해 공유)	팀 권한·훅·플러그인·프로젝트 환경변수
Project local	`.claude/settings.local.json`	이 프로젝트 한정, 나만 (git에서 제외)	한 프로젝트의 개인 오버라이드·테스트
Managed	`managed-settings.json` 등	조직이 배포한 모두 — 내가 못 바꿈	보안 정책·컴플라이언스

~/.claude는 홈 디렉토리의 .claude 폴더이고, 그냥 .claude는 프로젝트 안의 .claude 폴더입니다. Windows에서 ~/.claude는 %USERPROFILE%\.claude이고, 홈 파일 위치를 바꾸려면 CLAUDE_CONFIG_DIR을 설정하세요.

설정 파일 찾기/만들기: 설치가 설정 파일을 만들지는 않습니다. /config 메뉴에서 옵션(테마 등)을 처음 바꾸면 ~/.claude/settings.json이, 권한 프롬프트에서 "Yes, and don't ask again"을 고르면 .claude/settings.local.json이 자동 생성됩니다. 일부 옵션(Show tips 등)은 로컬 파일에 저장됩니다. 다섯 번째 파일 ~/.claude.json은 Claude Code가 스스로 쓰는 파일로, 로그인 세션·MCP 서버 설정·프로젝트별 상태(신뢰 결정)·글로벌 설정 키를 담습니다.

팀과 공유: .claude/settings.json을 커밋하면 모두가 같은 권한·훅·텔레메트리·플러그인을 받습니다. 동료마다 .claude/settings.local.json으로 개인 오버라이드를 만들 수 있어 개인 예외는 커밋이 필요 없습니다. 다만 일부는 각 동료가 폴더를 신뢰(trust)한 뒤, 일부 키는 저장소 파일에서 아예 적용되지 않습니다(Troubleshoot 참고).

개인 설정을 저장소에서 제외: 로컬 파일을 git에서 지키는 방법 — Claude Code가 처음 파일을 쓸 때 전역 git excludes(core.excludesFile, 또는 ~/.config/git/ignore)에 **/.claude/settings.local.json을 추가합니다. 손으로 만든 경우라면 .gitignore에 직접 추가하세요. 로컬 파일의 allow 규칙은 추적되지 않는 한 워크스페이스 신뢰 절차 없이 바로 적용됩니다.

설정 바꾸기

/config 메뉴: Config 탭에서 테마·에디터 모드·verbose 같은 개인 옵션을 바꿉니다. 대부분 ~/.claude/settings.json, 일부(Show tips)는 .claude/settings.local.json, 글로벌 설정 옵션은 ~/.claude.json에 저장됩니다. key=value 형태로 /config verbose=true처럼 한 옵션만 넘길 수도 있습니다.
파일 편집: 설정 파일은 엄격한 JSON입니다. // 주석이나 후행 쉼표는 구문 오류입니다. 예:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

세션 한 번만: --settings '{"model": "claude-opus-4-8"}'처럼 시작 시점에만 적용하고 파일은 건드리지 않습니다. 각 키마다 전용 플래그(--model, --effort)나 환경변수(ANTHROPIC_MODEL)가 있을 수 있습니다.
적용 시점: Claude Code는 설정 파일을 감시해 변경 시 재로드하므로 대부분 편집(permissions·hooks·apiKeyHelper 포함)이 재시작 없이 반영됩니다. 단 model·effortLevel·modelSettings는 세션 시작 시에만 읽으므로 /model, /effort로 바꾸세요. 각 설정 파일 변경마다 ConfigChange 훅이 실행됩니다.

적용 확인: /status를 실행하면 Setting sources 줄에 이 세션이 읽은 각 설정 파일이 나옵니다. 거부된 항목은 claude doctor로 확인하세요.

깨진 설정 파일 고치기: 잘못된 JSON이 있으면 세션 시작 시 — Settings Error(Claude의 도움으로 고치거나 계속 진행), Settings Warning(불량 항목만 건너뜀), Managed settings(관리 설정은 나머지 계속 강제), Configuration error(~/.claude.json 파싱 실패 — 백업 복원)로 표시됩니다.

설정 우선순위

같은 키가 여러 곳에 있으면 가장 높은 레벨의 값이 이깁니다. 높은 순서:

Managed settings — 조직이 배포한 것. 내가 설정한 어떤 것도 못 덮음. --settings로 넘긴 키도 같은 관리 키를 덮지 못하고, --model 같은 플래그도 조직이 허용한 모델 중에서만 고릅니다. 관리 model은 세션 시작 모델을 정하지만 /model로는 바꿀 수 있고, 진짜 잠금은 availableModels입니다.
명령줄 인자 — claude 시작 시 플래그, 한 세션용. --settings <file-or-json>는 로컬·프로젝트·유저의 같은 키보다 위입니다.
Project local (.claude/settings.local.json)
Shared project (.claude/settings.json)
User (~/.claude/settings.json)

환경변수는 이 스택의 레벨이 아닙니다. 쌍마다 정책이 다릅니다: ANTHROPIC_MODEL은 어떤 파일의 model 키보다 위지만, ANTHROPIC_DEFAULT_MODEL은 아무 파일도 model을 안 잡았을 때만 적용됩니다. 설정 파일 안의 env 블록은 일반 키라 위 레벨 규칙을 따릅니다.

목록은 병합: permissions.allow 같은 목록 키는 하나를 고르는 대신 합칩니다. 다만 fallbackModel(순서가 의미 있는 사슬 — 가장 높은 우선순위 파일의 전체 값을 사용)·modelPicker(병합 안 함)·availableModels(관리 설정이 정의하면 관리 값을 그대로 사용)·modelSettings(모델별 해석)는 별도 규칙을 따릅니다.

우선순위 예시(팁 표시 예): 팀 .claude/settings.json이 spinnerTipsEnabled: true면 유저 파일에 false를 넣어도 그 프로젝트에선 팁이 보입니다 → 로컬 파일에 false를 넣으면 되돌릴 수 있습니다. 조직 관리 설정이 true면 되돌릴 수 없습니다(Managed가 최상위). --settings로 켰다면 다음 세션부터 없어집니다.

적용 안 되는 설정 트러블슈팅

값이 무시될 때: 상위 레벨이 같은 키를 설정했거나, 파일이 그 값을 못 담거나(예 permissions.defaultMode의 auto·bypassPermissions는 프로젝트/로컬에서 안 먹힘 — 유저/관리 설정이나 --permission-mode로), 파일이 깨졌거나.
세션에서 바꾼 게 사라질 때: /model로 저장한 기본값은 ~/.claude/settings.json에 쓰는데, 그 파일을 쓸 수 없으면(다른 도구가 생성/읽기전용 링크) 다음 세션에 사라집니다.
커밋한 키가 동료에게 안 닿을 때: 설정 인덱스의 Scope 열에 User, local, or managed·User or managed·Managed·Global config로 표시된 키는 공유 파일에서 적용되지 않습니다(예외 autoContinueAtUsageLimit). 또 permissions.allow·additionalDirectories·extraKnownMarketplaces·대부분의 env 값은 각 동료가 폴더를 신뢰한 뒤에만 적용됩니다.

관리 설정 우선순위 예외 (보안 키)

몇몇 제한적 값은 걸린 스코프가 관리 설정을 못 덮는 위치여도 항상 존중됩니다:

disableClaudeAiConnectors: 어느 스코프든 true
enableArtifact: 어느 스코프든 false, 또는 어느 스코프든 disableArtifact: true
isolatePeerMachines: 어느 스코프든 true
remoteControlAtStartup: .claude/settings.json/.claude/settings.local.json의 false
crossSessionInbound: 프로젝트/로컬에서 accept < hold < refuse 사다리상 더 엄격한 값
useAutoModeDuringPlan: 관리·--settings·유저·로컬의 false
syncClaudeAiSkills: 관리·--settings·유저·로컬의 false
maxEffortLevel: 어느 스코프든(포함 --settings) 더 낮은 상한 — 가장 낮은 상한이 적용됩니다 (v2.1.267+)

클라우드 세션에서의 설정

Claude Code on the web 또는 claude --cloud의 클라우드 세션은 저장소의 새 클론 위에서 돌므로 — 공유 프로젝트 설정(.claude/settings.json)은 클론에 포함돼 읽히지만, 유저·로컬 설정은 읽히지 않고, 관리 설정 중 server-managed 설정만 도달합니다. 클라우드 세션 설정을 바꾸려면 환경에 환경변수를 설정하거나 저장소의 .claude/settings.json에 커밋하세요.

더 알아보기

전체 설정 키 레퍼런스 — 모든 키와 파일·기본값·예시
예제 설정 파일 — 개인·팀·조직 관리 파일
권한 구성 — allow·ask·deny 규칙
환경변수 — env 블록과 변수 우선순위
구성 디버깅 — 설정이 반영되지 않을 때