설정 파일 및 우선순위

​

설정 파일 및 영향을 받는 사용자

​

각 설정 파일의 범위 비교

• ~/.claude/settings.json: 머신의 모든 프로젝트, 팀원의 것이나 클라우드 세션의 것은 제외
• acme-app/.claude/settings.json: 사용자의 acme-app/. 파일을 버전 제어에 커밋한 경우에만 팀원의 클론과 클라우드 세션에 도달합니다. 커밋하기 전까지는 다른 파일처럼 디스크의 파일이며 다른 사람은 이를 가지지 않습니다.
• acme-app/.claude/settings.local.json: 사용자의 acme-app/만. Claude Code는 파일을 처음 작성할 때 전역 git 제외에 추가하므로 커밋에서 제외됩니다. 수동으로 파일을 생성한 경우 .gitignore에 직접 추가합니다.
• 관리되는 설정, managed-settings.json 파일, MDM 정책, 또는 claude.ai 콘솔의 서버 관리 설정: 조직이 배포하는 모든 머신의 모든 프로젝트, 또는 조직 계정으로 로그인한 모든 머신. 서버 관리 설정만 클라우드 세션에 도달합니다.

​

설정 파일 찾기 또는 생성

• 관리됨: 조직이 배포합니다. 사용자가 생성하거나 편집하지 않습니다.
• 공유 프로젝트: Claude Code를 이미 사용하는 프로젝트에 커밋된 파일이 있을 수 있습니다. 없으면 프로젝트 폴더에 .claude/settings.json을 생성합니다.
• 사용자 및 프로젝트 로컬: 직접 생성하거나 Claude Code가 생성하도록 합니다. 테마와 같이 사용자 설정에 저장되는 /config 메뉴의 옵션을 처음 변경할 때 ~/.claude/settings.json을 작성하고, Bash 명령에 대해 “Yes, and don’t ask again”과 같은 권한 프롬프트에서 처음 승인을 할 때 .claude/settings.local.json을 작성합니다. Show tips를 포함한 몇 가지 /config 옵션은 사용자 파일 대신 .claude/settings.local.json에 저장됩니다.

​

팀과 설정 공유

​

저장소에서 개인 설정 제외

• Claude Code도 작성합니다. Claude가 Bash 명령을 실행할 권한을 요청하고 “Yes, and don’t ask again”을 선택하면, Claude Code는 해당 권한 승인을 allow 규칙으로 여기에 저장합니다.
• 수동으로 생성한 경우를 제외하고 직접 gitignore할 필요가 없습니다. Claude Code가 이미 무시하지 않는 git 저장소에서 파일을 처음 작성할 때, 전역 git 제외 파일에 **/.claude/settings.local.json을 추가하므로 모든 저장소에서 파일이 커밋에서 제외됩니다. 해당 파일은 전역 git 구성이 절대 경로 또는 ~ 접두사 경로로 설정할 때 core.excludesFile입니다. 그렇지 않으면 $XDG_CONFIG_HOME/git/ignore 또는 XDG_CONFIG_HOME이 설정되지 않을 때 ~/.config/git/ignore입니다. 수동으로 파일을 생성했고 Claude Code가 아직 작성하지 않았다면 .gitignore에 직접 추가합니다.
• 파일이 추적되지 않은 상태에서 허용 규칙은 신뢰를 기다리지 않습니다. 파일이 저장소의 것이 아니라 사용자의 것이므로, Claude Code는 커밋된 파일에 필요한 워크스페이스 신뢰 단계 없이 allow 규칙을 적용합니다. 파일이 git으로 추적되면 신뢰 단계도 적용됩니다. 로컬 설정 파일이 신뢰가 필요한 경우를 참조합니다.

​

Claude Code가 git 저장소에서 로컬 파일을 보관하는 위치

• 파일이 .claude/settings.json 대신 유지되는 경우: git 저장소 외부, 저장소 루트가 홈 디렉토리인 경우, Windows에서, 또는 저장소 루트나 .git 또는 .claude 항목이 사용자가 소유하지 않은 경우.
• 파일의 경로는 저장소 루트에 고정되지 않습니다: /로 시작하거나 상대 샌드박스 경로인 권한 규칙은 세션의 기본 작업 디렉토리에 고정됩니다.

​

조직이 적용하는 항목 확인

• 서버 관리 설정, Claude Code가 claude.ai 관리 콘솔 또는 자체 호스팅 Claude 앱 게이트웨이에서 가져옴
• MDM 또는 OS 수준 정책, 시스템 디렉토리의 managed-settings.json 파일
• Claude Desktop과 같은 임베딩 호스트, SDK managedSettings 옵션을 통해. 임베딩 호스트에서 정책 제어를 참조합니다.

​

설정 변경

​

/config 메뉴 사용

• 대부분의 옵션: ~/.claude/settings.json
• 팁 표시와 같은 몇 가지 옵션: .claude/settings.local.json
• 전역 구성 옵션: ~/.claude.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: JSON으로 키를 전달하거나 파일 경로로. Claude Code는 사용자, 프로젝트, 로컬 파일 위에 적용하고 관리되는 설정 아래에 적용합니다. 사용자 설정 파일이 설정할 수 있는 모든 키를 설정할 수 있습니다. Managed 또는 Global config 키는 설정할 수 없습니다.
• 해당 키에 대한 플래그: 일부 키에는 model에 대한 --model, effortLevel 및 modelSettings에 대한 --effort와 같은 자체 플래그가 있습니다.
• 환경 변수: model에 대해 ANTHROPIC_MODEL과 같이 claude를 실행하기 전에 키의 쌍을 이루는 변수를 내보냅니다.

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

​

편집이 적용되는 시기

• model: 세션 중에 전환하려면 /model을 사용합니다. 각 모델에는 자체 프롬프트 캐시가 있으므로 전환 후 첫 요청은 전체 대화를 캐시되지 않은 상태로 다시 읽습니다. 모델 전환을 참조하세요
• effortLevel 및 modelSettings: 세션 중에 변경하려면 /effort를 사용합니다

​

로드된 것 확인

​

손상된 설정 파일 수정

• 설정 오류: 사용자, 프로젝트 또는 로컬 파일에 유효하지 않은 JSON 또는 스키마가 거부하는 값이 있습니다. 대화형 세션 시작 시 Claude Code는 Claude의 도움으로 파일을 수정하거나, 종료하거나, 손상된 설정 없이 계속할 수 있는 대화를 표시합니다.
• 설정 경고: 개별 항목만 실패합니다. 예: 잘못된 형식의 권한 규칙 또는 알 수 없는 hook 이벤트 이름. Claude Code는 해당 값을 건너뛰고 파일의 나머지를 유지합니다.
• 관리되는 설정: Claude Code는 파일의 나머지를 적용합니다. 관리되는 설정의 유효하지 않은 항목은 삭제되는 것과 유효하지 않은 항목을 수정할 때까지 폴백하는 키를 설명합니다. 유효한 JSON이 아닌 관리되는 설정 문서는 관리되는 설정 문서를 파싱할 수 없음을 참조하세요.
• 구성 오류: ~/.claude.json을 파싱할 수 없습니다. Claude Code는 손상된 파일을 ~/.claude/backups/.claude.json.corrupted.<timestamp>에 복사하고 종료하고 직접 수정하거나 기본 구성으로 재설정할지 묻습니다. -p 실행은 오류를 인쇄하고 종료합니다. 이전 상태를 복구하려면 ~/.claude/backups/의 5개 가장 최근 .claude.json.backup.<timestamp> 파일 중 하나를 다시 복사합니다. Claude Code는 파일을 쓰기 전에 저장합니다.

​

설정 우선순위

1. 관리되는 설정: 조직이 배포하는 설정으로, managed-settings.json 파일, MDM 정책, 또는 claude.ai 콘솔의 서버 관리 설정입니다. 사용자가 설정한 것은 이를 재정의할 수 없습니다. --settings로 전달한 키는 동일한 관리되는 키를 재정의하지 않으며, --model과 같은 플래그는 조직이 허용하는 모델에서만 선택합니다. 관리되는 model은 각 세션이 시작되는 모델을 설정하며, /model로 전환할 수 있습니다. 잠금은 availableModels이며, 이는 /model, --model, 및 자신의 파일의 model 키를 제한합니다. 조직이 둘 이상의 관리되는 소스를 제공할 때, 관리되는 계층 내 우선순위의 규칙은 Claude Code가 각각에서 읽는 것을 나타냅니다.
2. 명령줄 인수: 터미널에서 claude를 시작할 때 전달하는 플래그로, 한 세션 동안 적용됩니다. 한 세션 동안 설정 변경을 참조하세요. Claude Code는 --settings <file-or-json>으로 전달한 JSON을 다른 수준과 동일한 규칙으로 설정 파일과 병합합니다. 여기서 설정한 키를 로컬, 프로젝트 또는 사용자 설정의 동일한 키보다 우선하며, 생략한 키에 대해서는 낮은 수준의 값을 유지합니다.
3. 프로젝트 로컬 설정 (.claude/settings.local.json): 이 프로젝트에 대한 개인 설정입니다.
4. 공유 프로젝트 설정 (.claude/settings.json): 팀이 소스 제어에 체크인하는 설정입니다.
5. 사용자 설정 (~/.claude/settings.json): 모든 프로젝트에 대한 개인 설정입니다.

​

목록은 재정의 대신 병합됩니다

• fallbackModel은 위치가 의미를 갖는 정렬된 체인이므로, Claude Code는 이를 정의하는 가장 높은 우선순위 파일의 전체 값을 사용합니다.
• modelPicker는 하나의 정렬된 행 목록과 교체 플래그를 보유하므로, Claude Code는 두 소스의 행을 병합하지 않습니다. 이를 정의하는 관리되는 설정, --settings, 및 사용자 설정 중 가장 높은 것의 전체 값을 사용하며, 프로젝트 및 로컬 설정의 키를 무시합니다. Claude Code v2.1.242 이상이 필요합니다.
• availableModels: Claude Code가 적용하는 관리되는 설정이 이를 정의할 때, Claude Code는 해당 목록을 그대로 적용하고 사용자, 프로젝트 또는 로컬 설정에서 추가하는 항목을 무시합니다. 단, Claude Code를 포함하는 앱이 자신의 모델 목록을 제공하는 경우는 제외합니다. 관리되는 설정 우선순위의 예외를 참조하세요. 관리되는 소스 전체에서 목록은 병합되지 않습니다. Claude Code가 관리되는 소스를 결합하는 방법은 어느 소스의 목록이 적용되는지 나타냅니다. 관리되지 않는 범위 전체에서 Claude Code는 일반적으로 배열을 병합합니다.
• modelSettings: Claude Code는 effortLevel과 함께 한 번에 하나의 모델로 이를 해결합니다. modelSettings 항목은 어느 파일의 값이 모델에 적용되는지 나타냅니다.

​

우선순위 예제

​

팀 설정이 개인 설정을 재정의합니다

​

조직 설정이 모든 것을 재정의합니다

​

명령줄이 한 세션 동안 파일을 재정의합니다

​

플래그 또는 환경 변수가 동일한 것을 설정합니다

​

적용되지 않는 설정 문제 해결

​

설정한 값이 무시됩니다

• 더 높은 수준이 이를 설정합니다. 다른 설정 파일, --settings 플래그, 또는 관리되는 소스가 키를 위에서 설정합니다. 스택은 어느 것인지 나타냅니다. 플래그 또는 환경 변수도 키별로 결정되는 키를 자체적으로 재정의할 수 있습니다. 설정 참조의 키 항목은 Claude Code가 어느 것을 사용하는지 나타내며, env 항목은 관리되는 env 값 대 셸 내보내기를 다룹니다.
• 보안 키가 엄격한 값을 유지합니다. 몇 가지 키의 경우 Claude Code는 모든 파일의 제한적인 값을 준수하므로, 프로젝트 true는 disableClaudeAiConnectors에 대해 켜진 상태로 유지됩니다. 관리되는 설정 우선순위의 예외를 참조하세요.
• 파일이 해당 값을 설정할 수 없습니다. permissions.defaultMode 값 auto와 bypassPermissions은 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 대신 사용자 또는 관리되는 설정에서 설정하거나, 한 세션 동안 --permission-mode를 전달합니다. v2.1.257 이전에는 bypassPermissions이 모든 파일에서 적용되었습니다. 설정 파일 내의 env 블록의 원격 분석 내보내기 변수도 프로젝트 또는 로컬 설정에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. Claude Code가 env에서 무시하는 변수는 변수와 해당 값을 나열합니다.
• 파일이 손상되었습니다. 잘못된 JSON 또는 거부된 값은 Claude Code가 파일 또는 항목을 건너뜁니다. 손상된 설정 파일 수정을 참조하세요.

​

Claude Code에서 만든 변경 사항이 새 세션에서 손실됩니다

​

관리되는 변경 사항이 도달하지 않았습니다

​

커밋된 키가 팀원에게 도달하지 않습니다

• Claude Code는 저장소 파일의 키를 무시합니다. 설정 인덱스의 범위 열에서 User, local, or managed, User or managed, Managed, 또는 Global config를 찾습니다. 이러한 키는 공유 파일에서 적용되지 않습니다. 저장소 파일은 여전히 키를 끌 수 있습니다. Global config 키는 ~/.claude.json에서만 적용됩니다. env 키 내에서, 원격 분석 내보내기 변수는 공유 파일에서 적용되지 않습니다. 몇 가지 끄기 값은 제외합니다. Claude Code가 env에서 무시하는 변수를 참조하세요.
• 키가 신뢰를 기다립니다. permissions.allow 규칙, permissions.additionalDirectories, extraKnownMarketplaces, 및 대부분의 env 값은 각 팀원이 폴더를 신뢰한 후에만 적용됩니다. 그때까지 그들은 여전히 프롬프트를 보고 파일이 선언하는 마켓플레이스에서 플러그인을 얻지 못합니다. deny와 ask 규칙은 즉시 적용됩니다.

​

권한 규칙이 예상과 다르게 결합됩니다

• 권한 프롬프트에서 “Yes, and don’t ask again”을 선택했지만 여전히 동일한 도구에 대해 프롬프트를 받습니다. 해당 선택은 allow 규칙을 로컬 파일에 저장했으며, 로컬 파일의 allow 규칙은 프로젝트 또는 관리되는 파일의 ask 규칙을 능가하지 않습니다. 권한 규칙이 결합되는 방법은 순서를 설명합니다. VS Code 확장에서 승인 카드는 프로젝트의 공유 파일을 포함한 대상 파일을 선택할 수 있으며, 이는 모든 사람을 위한 규칙을 변경합니다. CLI에서 Claude Code는 로컬 파일에만 씁니다.
• 조직의 허용 규칙이 여전히 사용자의 규칙과 함께 적용됩니다. 이는 예상된 것입니다. Claude Code는 조직이 allowManagedPermissionRulesOnly를 설정하지 않는 한 범위 전체에서 permissions.allow를 병합합니다.

​

관리되는 설정 우선순위의 예외

​

클라우드 세션의 설정

• 공유 프로젝트 설정 (.claude/settings.json): 한 저장소가 있는 세션에서 읽습니다. 파일이 복제본의 일부이고 세션이 그 안에서 시작되기 때문입니다. 해당 세션에 적용하려면 설정을 거기에 커밋합니다. 여러 저장소가 있는 세션은 복제본 위에서 시작되고 각 저장소의 .claude/settings.json에서 enabledPlugins 및 extraKnownMarketplaces 키만 읽으며, 권한 규칙, hooks, env 또는 기타 키는 읽지 않습니다. 이 두 키가 선언하는 마켓플레이스와 플러그인은 여전히 클라우드 세션에서 로드되지 않습니다.
• 사용자 및 프로젝트 로컬 설정 (~/.claude/settings.json 및 .claude/settings.local.json): 읽지 않습니다. 둘 다 머신에 유지되고 로컬 파일은 복제본에 없습니다.
• 관리되는 설정: 서버 관리 설정만 클라우드 세션에 도달합니다. 장치의 managed-settings.json 파일이나 MDM 프로필은 도달하지 않습니다. 자체 호스팅 환경도 실행기 이미지의 관리되는 설정 파일을 읽습니다. Claude Code가 관리되는 소스를 결합하는 방식은 해당 파일이 적용되는 시기를 설명합니다.
• /config: 브라우저에서 claude.ai/code에서 설정 값을 변경하는 대신 claude.ai 설정의 Claude Code 섹션을 엽니다. 클라우드 세션에 대해 설정을 변경하려면 환경에서 환경 변수를 설정하거나, 한 저장소가 있는 세션에서 해당 저장소의 .claude/settings.json에 키를 커밋합니다.

​

다음 단계

• 모든 설정: 모든 키, 설정 위치, 기본값, 예제
• 예제 설정 파일: 개인 파일, 팀 파일, 조직의 관리되는 파일
• 권한 구성: allow, ask, deny 규칙, Claude Code가 묻지 않고 실행하는 것
• 환경 변수: Claude Code가 읽는 변수 및 env 블록
• 구성 디버깅: 설정이 적용되지 않을 때
• Claude 디렉토리 참조: Claude Code가 읽는 모든 파일. subagents, MCP 서버, 플러그인, CLAUDE.md 포함