Claude Code 설정 바꾸기·확인·문제 해결

설정 하나를 바꾸고, 적용됐는지 확인하고, 안 먹으면 원인을 찾는 절차다. 어느 파일이 누구에게 적용되는지와 우선순위의 원리는 Claude Code 설정 파일에 있다.

준비물(필요한 것)#

1. 어느 파일에 둘지 고른다#

근거: Claude Code 설정 파일과 우선순위. 원본 예: 팀 파일이 "model": "claude-sonnet-5"인데 나는 Opus를 쓰고 싶으면 local 파일에 "model": "claude-opus-5-5"를 둔다. local이 shared project보다 위라 내 세션만 바뀐다(원본 당시 예시).

2. 바꾼다 (2026-10-21 기준)#

2-1. /config 메뉴#

Claude Code 안에서 /config(슬래시 명령, 용어 사전)를 실행하고 Config 탭을 연다. 테마, 편집기 모드, verbose 출력 같은 짧은 개인 옵션 목록이고 모든 키가 있는 것은 아니다. 고르면 Claude Code가 저장한다. Claude Code 설정 파일과 우선순위

• 대부분의 옵션: ~/.claude/settings.json
• Show tips 같은 몇 가지: .claude/settings.local.json
• global config 옵션: ~/.claude.json
• 메뉴 없이 하나만: /config verbose=true처럼 key=value

/config는 터미널 인터페이스의 기능이다. VS Code 채팅 패널과 데스크톱 앱은 이 메뉴를 열지 않으니 설정 파일이나 그 앱의 설정에서 바꾼다. Config 탭은 settings.json 내용을 보여 주는 화면이 아니다. Claude Code 설정 파일과 우선순위

2-2. 설정 파일 직접 편집#

원하는 범위의 파일을 열어 키를 더하거나 고친다. 설정 파일은 엄격한 JSON이라 // 주석이나 끝 쉼표가 있으면 문법 오류이고, 다음 시작 때 Settings Error로 보고된다. 원본 예: lint·test 명령은 묻지 않고 돌리고 .env 파일은 읽지 못하게 하기. Claude Code 설정 파일과 우선순위

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

• $schema 줄은 공개 JSON 스키마를 가리켜 VS Code·Cursor 등에서 자동완성과 검증을 준다. 스키마는 최신 CLI보다 늦을 수 있어, 새로 문서화된 키에 검증 경고가 떠도 설정이 잘못됐다는 뜻은 아니다. Claude Code 설정 파일과 우선순위
• deny 규칙의 범위와 한계(명령 규칙은 쓰인 그대로 맞춤 등)는 권한 모드에 있다.

2-3. 한 세션만#

파일을 바꾸지 않고 시험하려면 시작할 때 값을 준다. Claude Code 설정 파일과 우선순위

• --settings: 키를 JSON으로, 인라인이나 파일 경로로 준다. user·project·local 파일 위, managed 아래에 적용된다. user 설정 파일이 정할 수 있는 키는 다 정할 수 있지만 Managed·Global config 키는 못 정한다.
• 키 전용 플래그: --model(model), --effort(effortLevel·modelSettings) 등.
• 환경 변수: ANTHROPIC_MODEL(model) 등을 claude 실행 전에 export.

claude --settings '{"model": "claude-opus-5-5"}'

(원본 예시. 기본값을 바꾸지 않고 한 세션만 Opus로 시작.)

공식 CLI 문서가 더하는 조건 (2026-10-21 기준): --settings에 주는 파일은 2 MiB 이하의 일반 파일이어야 하고, 빠진 키는 파일 값을 유지한다. --setting-sources user,project처럼 로드할 출처를 고를 수 있다. 저장된 설정을 바꾸지 않는 한 세션용 플래그로 --effort(저장되지 않음), --autocompact, --fallback-model(세션을 넘어 유지하려면 fallbackModel 설정)이 있다. 플래그 전체는 Claude Code CLI 플래그. Claude Code CLI 레퍼런스

세션 안에서 쓰는 명령은 대개 저장한다: /config는 설정 파일에, /model은 새 세션의 기본값으로 쓴다. /model 선택 창에서 s를 누르면 user 기본값으로 저장하지 않고 모델만 바꾼다. Claude Code 설정 파일과 우선순위

3. 언제 적용되는지 안다 (2026-10-21 기준)#

• Claude Code는 설정 파일을 감시하다 바뀌면 다시 읽는다. permissions, hooks, apiKeyHelper 같은 자격 증명 헬퍼를 포함한 대부분의 편집은 재시작 없이 실행 중인 세션에 적용된다. 세션 시작 때 폴더가 있었다면 세션 중 새로 만든 설정 파일도 읽고, 프로젝트 .claude/ 폴더는 같은 세션에 만들어도 읽는다. Claude Code 설정 파일과 우선순위
• 다시 읽기는 user·project·local·managed 설정을 다룬다. 설정 파일 변경을 감지할 때마다 ConfigChange 훅이 돈다. MDM이나 claude.ai 콘솔로 오는 managed settings는 저장 시점이 아니라 정해진 주기로 세션에 닿고 ConfigChange도 돌지 않는다. → 훅 이벤트 레퍼런스, managed settings
• 시작 때 한 번만 읽는 키는 편집해도 실행 중인 세션에 닿지 않는다. 세션 중 가장 흔히 고치는 것: model(대신 /model로 바꾼다. 모델마다 프롬프트 캐시가 따로라 바꾼 뒤 첫 요청은 대화 전체를 캐시 없이 다시 읽는다. 무엇이 캐시를 깨는지는 프롬프트 캐싱), effortLevel·modelSettings(대신 /effort). requiredMinimumVersion 같은 관리자 키도 재시작을 기다린다. Claude Code 설정 파일과 우선순위

4. 됐는지 확인하는 법#

1. Claude Code 안에서 /status를 실행한다. Status 탭의 Setting sources 줄이 이번 세션에 로드한 설정 파일을 나열한다(예: User settings, Project local settings). managed settings가 적용 중이면 그 항목 괄호 안에 어떻게 기기에 왔는지가 나온다. Claude Code 설정 파일과 우선순위
2. 이 줄은 어느 파일을 읽었는지만 보여 주고, 어느 파일이 어느 키를 줬는지는 보여 주지 않는다. 거부된 항목은 claude doctor로 본다. project나 managed 설정이 정한 모델은 시작 헤더가 그 파일 이름을 밝힌다. Claude Code 설정 파일과 우선순위
3. 조직이 무엇을 강제하는지도 /status로 본다. Setting sources 줄이 나에게 적용되는 managed 출처를 밝힌다. 그 키들은 내 파일로 바꿀 수 없다. Claude Code 설정 파일과 우선순위

5. 증상별 점검 (2026-10-21 기준)#

설정 중 어느 것이 문제인지 모를 때 공식 CLI 문서는 claude --safe-mode로 사용자 정의(CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 출력 스타일, 자동 메모리 등)를 모두 끄고 시작해 보라고 한다. 인증·모델·내장 도구·권한은 정상으로 돌고, managed 정책은 계속 적용된다(정책 훅·상태 줄·파일 제안 명령은 돌고, managed 플러그인·스킬·CLAUDE.md와 정책 MCP 서버는 로드되지 않는다). 세션 없이 설치·설정 검증 오류만 보려면 claude doctor. Claude Code CLI 레퍼런스

시작 때 오류·경고가 뜬다#

근거: Claude Code 설정 파일과 우선순위. 계속 진행했다면 /status로 영향받은 파일을, claude doctor로 오류별 세부를 본다. -p 실행은 대화상자가 없다. managed settings 문서를 파싱할 수 없는 경우가 아니면 깨진 파일이나 값을 건너뛰고 계속하므로(~/.claude.json 파싱 실패는 오류를 출력하고 종료), -p 실행 뒤 설정이 무시된 것 같으면 claude doctor로 무엇이 버려졌는지 본다.

넣은 값이 무시된다#

원인은 넷 중 하나다. Claude Code 설정 파일과 우선순위

1. 더 높은 레벨이 같은 키를 정한다. 다른 설정 파일, --settings, managed 출처(Claude Code 설정 파일의 우선순위). 플래그나 환경 변수도 키마다 따로 덮을 수 있다.
2. 보안 키가 엄격한 값을 지킨다. 예: 어느 범위든 disableClaudeAiConnectors: true가 있으면 켜진 채로 남는다.
3. 그 파일이 그 값을 정할 수 없다. permissions.defaultMode의 auto·bypassPermissions는 project·local 파일에서 효과가 없다. user·managed에 두거나 한 세션만 --permission-mode를 쓴다(v2.1.257 전에는 bypassPermissions가 어느 파일에서든 효과가 있었다). env 블록의 텔레메트리 내보내기 변수도 몇몇 끄는 값을 빼면 project·local에서 효과가 없다. → Claude Code 권한 모드 고르기
4. 파일이 깨졌다. 위 표.

Claude Code 안에서 바꾼 것이 새 세션에서 사라진다#

/model로 정한 기본 모델처럼 새 세션용으로 저장하는 선택은 ~/.claude/settings.json에 쓴다. 다른 도구가 이 파일을 생성하거나 읽기 전용 사본에 링크해 쓸 수 없으면 그 세션에만 적용되고 다음 세션에 사라진다. 그 파일을 만드는 도구 쪽에서 키를 정하거나, 쓸 수 있는 파일로 바꾼다. 쓸 수 있는데도 사라지면 한 세션용 변경이었는지, 더 높은 레벨이 같은 키를 정하는지 본다. Claude Code 설정 파일과 우선순위

관리자가 바꾼 정책이 안 닿는다#

managed 출처는 전달 방식별 주기로 실행 중인 세션에 닿으므로 먼저 세션을 재시작한다. 그 뒤 /status가 관리자가 바꾼 출처와 다른 출처를 보여 주면 더 높은 관리 출처가 적용 중이다. Claude Code 설정 파일과 우선순위 → Claude Code managed settings 배포·점검

커밋한 키가 팀원에게 안 먹는다#

• 그 키가 저장소 파일에서 효과가 없는 키인지 본다(settings reference의 Scope 열이 User, local, or managed, User or managed, User, Managed, Global config). Claude Code 설정 파일과 우선순위 키별 Scope와 항목별 제한(예: blockReadsOutsideWorkingDirectories는 저장소가 켤 수만 있고, remoteControlAtStartup은 project·local의 true를 무시)은 Claude Code 설정 키 레퍼런스에서 찾는다(2026-10-21 기준). Claude Code 설정 키 전체 레퍼런스
• 신뢰를 기다리는 키인지 본다. permissions.allow, permissions.additionalDirectories, extraKnownMarketplaces, 대부분의 env 값은 팀원이 폴더를 신뢰해야 적용된다. deny·ask는 바로 적용된다. Claude Code 설정 파일과 우선순위 단 상위 폴더만 신뢰한 대화형 세션과 -p·SDK 실행에서는 저장소의 env 블록이 쓰인다(권한 문서 기준). Claude Code 권한 설정 문서별 설명은 작업 공간 신뢰에 나란히 두었다.

원본은 이 증상의 원인을 위 두 가지로 든다. 별도로, 공유 .claude/settings.json은 세션의 주 작업 디렉터리에서 읽으므로 "to use a file committed at the repository root, start Claude Code there"라고 한다. Claude Code 설정 파일과 우선순위 편집자 해석: 이 문장에 따르면 팀원이 저장소 루트가 아닌 하위 디렉터리에서 시작했는지도 확인해 볼 수 있다.

"다시 묻지 않기"를 골랐는데 계속 묻는다#

그 선택은 local 파일에 allow 규칙을 저장했고, local의 allow는 project나 managed 파일의 ask 규칙보다 앞서지 않는다. 조직의 permissions.allow가 내 규칙과 함께 적용되는 것은 정상이다(조직이 allowManagedPermissionRulesOnly를 켜면 합쳐지지 않는다). Claude Code 설정 파일과 우선순위 배포 문서는 이 키가 managed settings를 권한 규칙의 유일한 설정 출처로 만든다고 설명한다. Claude Code managed settings 배포 → Claude Code 관리자 권한 통제

더 넓은 점검(깨끗한 구성으로 시험하기 등)은 원본이 Debug your configuration 문서로 넘긴다.

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 팀에 Claude Code 설정을 처음 공유할 때, 팀원에게 "설정 파일이 왜 네 개냐"를 설명할 때, 동료가 "설정을 넣었는데 안 먹는다"고 할 때.
• 쓰지 않는다: 조직 정책 배포는 Claude Code managed settings 배포·점검, 권한 규칙 문법과 모드는 권한 모드·Claude Code 권한 모드 고르기, 훅 설정은 Claude Code 훅 설정 레시피를 본다. 키 하나의 기본값·Scope는 Claude Code 설정 키 레퍼런스(settings reference 2026-10-21 수집본 요약)와 공식 문서를 확인한다.