모든 설정

설정 색인

모델 및 응답

advisorModel

• 범위: Any file
• 유형: 문자열. 해당 모델 계열의 Claude Code 현재 기본 버전으로 해석되는 별칭 "fable", "opus", "sonnet" 중 하나 또는 "claude-opus-5-5"와 같은 전체 모델 ID
• 기본값: 설정되지 않음. 따라서 advisor가 꺼져 있습니다
• 세션별 재정의: 한 세션에 대해서는 --advisor가 이 키보다 우선합니다. CLAUDE_CODE_DISABLE_ADVISOR_TOOL은 advisor를 끄며, 이 키로 다시 켤 수 없습니다

{
  "advisorModel": "opus"
}

alwaysThinkingEnabled

• 범위: Any file
• 유형: Boolean
  • true: 효과 없음. 사고가 이미 켜져 있습니다
  • false: Claude Code가 모든 세션에서 확장 사고를 끕니다
• 기본값: 설정되지 않음. 따라서 지원하는 모델에서는 사고가 켜져 있습니다
• 세션별 재정의: 한 세션에 대해서는 MAX_THINKING_TOKENS가 이 키보다 우선합니다. 0은 false와 동일한 모델 및 공급자 제한 아래에서 사고를 끄고, 양수 값은 이 키가 false여도 사고를 켭니다. 적응형 추론 모델에서는 숫자 자체가 무시됩니다

{
  "alwaysThinkingEnabled": false
}

availableModels

• 범위: Any file. 조직 전체에 적용하려면 관리형 설정에 배포합니다.
• 유형: 모델 별칭 또는 ID의 배열
• 기본값: 설정되지 않음. 따라서 모든 모델을 사용할 수 있습니다

{
  "availableModels": ["sonnet", "haiku"]
}

availableModelsMatch

• 범위: Managed. Claude Code는 사용자, 프로젝트, 로컬 설정과 --settings에 있는 이 키를 경고와 함께 무시합니다
• 유형: 문자열. 다음 중 하나:
  • "prefix": 모델 ID 항목은 해당 버전과, 다른 세그먼트로 이를 확장하는 모든 모델 ID를 허용합니다
  • "exact": 모델 ID 항목은 명시한 버전만 허용하므로, "claude-opus-5"는 Opus 5를 허용하지만 claude-opus-5-5는 허용하지 않습니다. "claude-opus-4-5"와 같은 항목은 날짜가 포함된 Anthropic 모델 ID claude-opus-4-5-20251101도 허용합니다. "opus"와 같은 계열 별칭은 여전히 계열 전체를 허용하며, best, opusplan, default 항목은 무시됩니다
• 기본값: "prefix"

{
  "availableModels": ["claude-opus-5", "claude-sonnet-5"],
  "availableModelsMatch": "exact"
}

deniedModels

• 범위: Managed. Claude Code는 사용자, 프로젝트, 로컬 설정과 --settings에 있는 이 키를 경고와 함께 무시합니다
• 유형: 모델 별칭 또는 ID의 배열
  • "opus"와 같은 계열 별칭은 해당 계열의 모든 모델을 차단합니다
  • "claude-opus-5-5"와 같은 모델 ID는 날짜가 포함된 ID와 공급자별 ID를 포함하여 모든 표기의 해당 버전을 차단합니다
  • "claude-opus-5"처럼 마이너 버전이 없는 모델 ID는 Opus 5.5와 같은 이후 마이너 버전도 차단합니다. Opus 5만 차단하려면 "claude-opus-5-0"을 작성합니다
  • best, opusplan, default 항목은 무시됩니다
• 기본값: 설정되지 않음. 따라서 차단되는 모델이 없습니다

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

effortLevel

• 범위: Any file
• 유형: 문자열. 다음 중 하나:
  • "low": 가장 적은 추론. 지능에 민감하지 않은 짧고 범위가 정해진 지연 시간 민감 작업용
  • "medium": 어느 정도의 지능을 절충할 수 있는 비용 민감 작업에서 토큰 사용량을 줄입니다
  • "high": 토큰 사용량과 지능의 균형을 맞춥니다
  • "xhigh": 더 많은 토큰을 사용하여 더 깊이 추론합니다
• 기본값: 설정되지 않음
• 세션별 재정의: 한 세션에 대해서는 --effort가 이 키보다 우선하며, CLAUDE_CODE_EFFORT_LEVEL은 둘 다보다 우선합니다

{
  "effortLevel": "xhigh"
}

enforceAvailableModels

• 범위: Any file
• 유형: Boolean
  • true: Default가 availableModels 밖의 모델로 해석될 경우 Claude Code는 목록에서 처음으로 사용 가능한 모델로 해석합니다
  • false: 이 키는 Default가 해석되는 방식을 바꾸지 않습니다
• 기본값: false

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

fallbackModel

• 범위: Any file
• 유형: 모델 별칭 또는 ID의 배열. "default"는 기본 모델로 확장됩니다
• 기본값: 설정되지 않음. 따라서 실패한 요청을 다른 모델로 재시도하지 않습니다
• 세션별 재정의: 한 세션에 대해서는 --fallback-model이 이 키보다 우선합니다

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

fastMode

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 사용 가능한 세션에서 빠른 모드를 켭니다. Fable 5.2에서는 Fable 5.2를 사용하는 동안 /fast도 실행해야 합니다
  • false: 빠른 모드가 꺼진 상태로 유지됩니다
• 기본값: 설정되지 않음. 따라서 빠른 모드가 꺼져 있습니다
• 세션별 재정의: CLAUDE_CODE_DISABLE_FAST_MODE는 한 세션에 대해 빠른 모드를 끄며, 이 키로 다시 켤 수 없습니다

{
  "fastMode": true
}

fastModePerSessionOptIn

• 범위: Any file
• 유형: Boolean
  • true: 저장된 fastMode: true가 더 이상 세션 시작 시 빠른 모드를 켜지 않으므로 각 사용자가 원하는 세션마다 /fast를 실행합니다. 관리형 설정에서 이 키를 설정하지 않는 한 --settings로 전달된 fastMode: true는 해당 세션에 여전히 적용됩니다
  • false: 저장된 fastMode: true가 fastMode에 설명된 대로 동작합니다
• 기본값: false

{
  "fastModePerSessionOptIn": true
}

language

• 범위: Any file
• 유형: 문자열. "japanese", "spanish", "french"와 같은 모든 언어 이름. Claude Code는 검증하지 않습니다
• 기본값: 설정되지 않음. 이 경우 세션 제목은 대화 언어를 따릅니다

{
  "language": "japanese"
}

maxEffortLevel

• 범위: Any file. 조직 전체에 적용하려면 관리형 설정에 배포합니다. 여러 범위에서 상한을 설정하면 가장 낮은 값이 적용되므로, 한 범위에서 설정한 상한을 다른 범위에서 올릴 수 없습니다
• 유형: 문자열. "low", "medium", "high", "xhigh", "max" 중 하나. "max" 값은 상한을 설정하지 않습니다
• 기본값: 설정되지 않음. 따라서 상한이 적용되지 않습니다
• 모델별 상한: 모델의 modelSettings 항목에 maxEffortLevel을 추가합니다. 해당 항목은 사용자 설정이나 하나의 관리형 소스처럼 둘 다 설정한 설정 소스 내에서만 그 모델에 대해 이 키를 대체합니다. 해당 소스의 상한에서 모델을 제외하려면 그곳에 "max"를 설정합니다. Claude Code는 다른 소스의 상한은 여전히 적용합니다

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

model

• 범위: Any file
• 유형: 문자열. 모델 별칭 또는 전체 모델 ID
• 기본값: 설정되지 않음. 따라서 Claude Code는 계정의 기본 모델을 사용합니다
• 세션별 재정의: --model은 ANTHROPIC_MODEL보다 우선하며, 둘 다 한 세션에 대해서는 관리형 model을 포함하여 이 키보다 우선합니다. availableModels 목록은 여전히 선택에 적용됩니다

{
  "model": "claude-sonnet-5"
}

modelOverrides

• 범위: Any file
• 유형: 모델 ID를 공급자 모델 ID에 매핑하는 객체
• 기본값: 설정되지 않음

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

modelPicker

• 범위: User or managed. Claude Code는 관리형 설정, --settings, 사용자 설정에서 이 키를 읽고, 복제한 저장소가 선택기의 레이블을 바꿀 수 없도록 프로젝트 및 로컬 설정에서는 무시합니다. 이 세 가지 중 키를 설정한 가장 높은 소스가 라인업 전체를 제공하며, Claude Code는 두 소스의 라인업을 결합하지 않습니다.
• 유형: 행의 options 배열과 선택적 replaceBuiltInOptions Boolean을 가진 객체
• 기본값: 설정되지 않음. 따라서 선택기는 기본 제공 라인업을 표시합니다

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

modelPicker의 필드

• 제거됨: 폐기된 모델이나 조직에 액세스 권한이 없는 모델처럼 Claude Code가 제공할 수 없는 행
• 회색으로 표시됨: 아직 선택할 수 없는 행으로, 이유와 함께 표시됩니다
• 남은 행 없음: Claude Code는 평소처럼 허용 목록으로 필터링된 기본 제공 라인업을 유지합니다

modelPricing

• 범위: Managed. 서버 관리형 설정, MDM 정책, managed-settings.json 파일 또는 정책 헬퍼를 통해 키를 배포합니다. Claude Code는 사용자, 프로젝트, 로컬 설정, --settings, 그리고 Windows에서는 사용자가 쓸 수 있는 HKCU 레지스트리에 있는 이 키를 무시합니다. 서버 관리형 설정을 사용하면 각 세션은 해당 세션의 설정 가져오기가 설정을 확인할 때까지 정가로 비용을 보고합니다. Claude Code를 임베드하고 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정하는 호스트 애플리케이션은 SDK managedSettings 옵션을 통해 자체 요율표를 제공할 수 있으며, Claude Code는 어떤 관리형 소스도 이 키를 설정하지 않을 때만, 그리고 Claude Code v2.1.246 이상에서만 이를 사용합니다.
• 유형: 선택적 multiplier와 선택적 overrides 맵을 가진 객체
• 기본값: 설정되지 않음. 따라서 호스트 애플리케이션이 요율표를 제공하지 않는 한 Claude Code는 정가를 보고합니다

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

modelPricing의 필드

modelPricing 행이 적용되는 모델

• 기본 제공 모델의 ID: Claude Code 자체가 기본 제공 모델에 사용하는 키로, claude-sonnet-4-6과 같은 모델 자체 ID이든 Bedrock, Agent Platform, Foundry ID이든 해당됩니다. Claude Code는 해당 모델의 모든 날짜 스냅샷 ID와 공급자별 ID에 행을 적용합니다.
• 그 밖의 키: 게이트웨이 모델 별칭처럼 기본 제공 모델의 ID가 아닌 키입니다. Claude Code는 해당 ID 하나에만 행을 적용합니다. 모델 ID가 키 중 하나와 정확히 일치하면서 기본 제공 모델의 ID로 키가 지정된 행에도 해당하는 경우, Claude Code는 정확히 일치하는 항목을 사용합니다.
• Bedrock 애플리케이션 추론 프로필: Claude Code가 modelOverrides 맵이나 bedrock:GetInferenceProfile 조회를 통해 프로필을 라우팅 대상 모델로 확인하면, Claude Code는 해당 모델의 행을 프로필에 적용합니다.

modelSettings

• 범위: Any file
• 유형: 모델 이름을 다음 필드 중 일부를 가진 객체에 매핑하는 객체:
  • effortLevel: "low", "medium", "high", "xhigh" 중 하나
  • maxEffortLevel: 모델이 실행될 수 있는 가장 높은 effort 수준
  • autoCompactWindow: 100000에서 1000000 사이의 토큰 수 또는 모델에 맞게 조정된 윈도우를 의미하는 "auto". /autocompact가 여기에 저장합니다. 해당 모델에 대해서는 이 값이 같은 설정 파일의 최상위 autoCompactWindow보다 우선합니다. Claude Code v2.1.288 이상이 필요합니다
• 기본값: 설정되지 않음

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

outputStyle

• 범위: Any file
• 유형: 문자열. 기본 제공 또는 사용자 지정 출력 스타일의 이름
• 기본값: 설정되지 않음. 따라서 Claude Code는 기본 스타일을 사용합니다

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

• 범위: Any file
• 유형: 문자열. 다음 중 하나:
  • "5m": 캐시가 5분 동안 유지됩니다
  • "1h": 캐시가 1시간 동안 유지됩니다
• 기본값: 설정되지 않음. 따라서 각 메인 대화 요청은 기본 수명을 받습니다
• 세션별 재정의: FORCE_PROMPT_CACHING_5M이 다른 모든 것보다 우선하고, 그다음 CLAUDE_CODE_PROMPT_CACHE_TTL, 그다음 이 키, 마지막으로 ENABLE_PROMPT_CACHING_1H 순입니다

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

showThinkingSummaries

• 범위: Any file
• 유형: Boolean
  • true: Ctrl+O로 사고를 펼치면 전체 사고 요약이 표시됩니다
  • false: Anthropic API가 thinking 블록을 가리고 Claude Code는 접힌 스텁을 표시합니다
• 기본값: false

{
  "showThinkingSummaries": true
}

subagentPromptCacheTtl

• 범위: Any file
• 유형: 문자열. 다음 중 하나:
  • "5m": 캐시가 5분 동안 유지됩니다
  • "1h": 캐시가 1시간 동안 유지됩니다
• 기본값: 설정되지 않음. 따라서 이러한 각 요청은 기본 수명을 받습니다
• 세션별 재정의: FORCE_PROMPT_CACHING_5M이 다른 모든 것보다 우선하고, 그다음 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, 그다음 이 키, 그다음 모든 요청에 1시간 수명을 요청하는 ENABLE_PROMPT_CACHING_1H 순입니다. 서브에이전트 자체 frontmatter 값의 순위는 TTL 직접 선택을 참조하세요

{
  "subagentPromptCacheTtl": "1h"
}

switchModelsOnFlag

• 범위: Any file. /config에서 Switch models when a message is flagged로 표시되며, 옵션은 Switch automatically와 Ask each time입니다.
• 유형: Boolean
  • true: Claude Code가 폴백 모델로 전환하고 계속합니다
  • false: 대화형 세션에서는 Claude Code가 일시 중지하여 전환과 프롬프트 편집 중에서 선택할 수 있도록 합니다. -p 실행처럼 대화 상자를 표시할 수 없는 곳에서는 플래그가 지정된 요청이 오류로 종료됩니다
• 기본값: 설정되지 않음. Claude Code는 자동으로 전환하지만, 대화형 세션에서는 먼저 확인할 수 있습니다

{
  "switchModelsOnFlag": false
}

ultracode

• 범위: Any file
• 유형: Boolean
  • true: 동적 워크플로가 활성화되어 있고 모델이 xhigh를 지원하면 ultracode를 켠 상태로 세션이 시작됩니다
  • false: ultracode를 끈 상태로 세션이 시작됩니다
• 기본값: 설정되지 않음. 따라서 ultracode가 꺼져 있습니다
• 세션별 재정의: /effort ultracode는 이 키 없이 한 세션에 대해 ultracode를 켜고, /effort ultracode off는 이 키가 true일 때 한 세션에 대해 ultracode를 끕니다. --effort ultracode 플래그도 xhigh effort로 한 세션에 대해 ultracode를 켭니다

{
  "ultracode": true
}

권한 설정

allowManagedPermissionRulesOnly

• 저장소의 .claude/ 디렉터리
• claude.ai에서 동기화된 스킬을 포함한 ~/.claude/skills/ 및 ~/.claude/commands/ 디렉터리
• --add-dir 디렉터리
• ~/.claude/skills/ 또는 프로젝트의 .claude/skills/ 안에 있는 .claude-plugin 매니페스트로 선언된 플러그인
• 하나의 세션에만 로드되어 ID가 @inline으로 끝나는 플러그인(다음 조건을 모두 충족하는 경우)
  • 세션이 Claude Desktop 앱 자체가 Claude Code를 시작하는 Code 세션 또는 Cowork 세션이며, 클라우드 세션이 아닌 경우
  • 임베딩 호스트의 상위 설정만이 아니라 관리형 설정에서 이 키를 설정한 경우
  • 세션이 Claude Code v2.1.305 이상을 실행하는 경우

• 범위: Managed
• 타입: Boolean
  • true: 관리형 설정이 권한 규칙의 유일한 설정 소스가 됩니다
  • false: Claude Code가 관리형 규칙에 더해 사용자, 프로젝트, 로컬 및 --settings 파일의 권한 규칙을 적용합니다
• 기본값: 설정되지 않음. 따라서 Claude Code는 관리형 규칙에 더해 사용자, 프로젝트, 로컬 설정과 --settings의 권한 규칙을 적용합니다

{
  "allowManagedPermissionRulesOnly": true
}

autoMode

• 범위: User or managed
• 타입: 산문 규칙으로 구성된 environment, allow, soft_deny, hard_deny 배열과 classifyAllShell Boolean을 포함하는 객체
• 기본값: 설정되지 않음. 따라서 분류기는 기본 제공 규칙만 사용합니다

{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}

autoMode.classifyAllShell

• 범위: User or managed. autoMode를 읽는 모든 위치에서 읽습니다.
• 타입: Boolean
  • true: 자동 모드가 활성화된 동안 Claude Code는 모든 Bash 및 PowerShell 명령을 분류기로 보내고 셸 허용 규칙을 일시 중지합니다. 자동 모드 외부에서는 규칙이 계속 적용됩니다
  • false: 자동 모드는 Bash(*) 및 Bash(python *)처럼 임의의 코드를 실행할 수 있는 허용 규칙만 일시 중지합니다. 다른 허용 규칙과 일치하는 명령은 명령별 허용 도메인을 포함하지 않는 한 분류기를 건너뛰고, 그 외의 모든 셸 명령은 분류기를 거칩니다
• 기본값: false

{
  "autoMode": {
    "classifyAllShell": true
  }
}

disableAutoMode

• 범위: Any file. 사용자가 재정의할 수 없는 관리형 설정에서 가장 유용합니다. permissions 아래에서 permissions.disableAutoMode로도 허용됩니다.
• 타입: 문자열 "disable"
• 기본값: 설정되지 않음

{
  "disableAutoMode": "disable"
}

permissions

• 범위: Any file
• 타입: allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, blockWritesOutsideWorkingDirectories, defaultMode, denyInsteadOfPrompting, disableBypassPermissionsMode, disableAutoMode를 포함하는 객체
• 기본값: 설정되지 않음

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

useAutoModeDuringPlan

• 범위: User, local, or managed. 저장소는 사용자를 대신해 이를 끌 수 없습니다.
  • 이러한 파일 중 하나 또는 --settings에서 false를 설정하면 꺼집니다. 단, --setting-sources 같은 옵션으로 해당 사용자 또는 로컬 파일을 제외한 경우는 예외입니다. 제외된 파일을 무시하려면 Claude Code v2.1.314 이상이 필요합니다
• 타입: Boolean
  • true: 설정되지 않은 경우와 동일합니다. 자동 모드를 사용할 수 있을 때 분류기가 계획 중 셸 명령을 검토합니다
  • false: 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트가 표시됩니다
• 기본값: true

{
  "useAutoModeDuringPlan": false
}

permissions.allow

• 범위: Any file
• 타입: 권한 규칙 문자열 배열
• 기본값: 설정되지 않음
• 세션별 재정의: --allowedTools는 하나의 세션에 대한 허용 규칙을 추가하며, 모든 설정 파일의 거부 규칙은 여전히 해당 규칙이 지정하는 도구를 차단합니다

{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}

권한 규칙 구문

permissions.ask

• 범위: Any file
• 타입: 권한 규칙 문자열 배열
• 기본값: 설정되지 않음

{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

permissions.deny

• 범위: Any file
• 타입: 권한 규칙 문자열 배열
• 기본값: 설정되지 않음
• 세션별 재정의: --disallowedTools는 이 키와 함께 하나의 세션에 대한 거부 규칙을 추가합니다

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}

permissions.additionalDirectories

• 범위: Any file. 단, 프로젝트 및 로컬 항목이 부여하는 샌드박스 쓰기 접근에는 제한이 있습니다
• 타입: 디렉터리 경로 배열
• 기본값: 설정되지 않음
• 세션별 재정의: --add-dir 및 /add-dir은 이 키와 함께 하나의 세션에 대한 디렉터리를 추가합니다

{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}

permissions.blockReadsOutsideWorkingDirectories

• 어떤 모드에서도 자동 승인되지 않는 작업에서는 이러한 경로를 읽는 셸 명령이 언제 확인을 요청하는지 다룹니다
• 차단 상태에서의 샌드박스 명령에서는 샌드박스 명령이 읽을 수 있는 항목을 다룹니다

• 범위: Any file. 어느 파일에서든 true가 적용되므로, 저장소는 자체적으로 차단을 켤 수는 있지만 사용자의 차단을 해제할 수는 없습니다.
• 타입: Boolean
  • true: Claude의 파일 도구가 작업 디렉터리 외부의 읽기를 거부합니다
  • false: 설정되지 않은 경우와 동일합니다. 다른 파일이 true를 설정하면 차단은 계속 적용됩니다
• 기본값: 설정되지 않음. 따라서 작업 디렉터리 외부의 읽기는 권한 모드를 따릅니다

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}

차단 상태에서의 샌드박스 명령

• sandbox.filesystem.disabled를 통해 파일 시스템 격리가 꺼진 경우
• allowManagedReadPathsOnly가 설정된 경우
• Claude Code를 시작한 디렉터리의 경로에 *, ?, [ 같은 glob 문자가 포함된 경우

• ~/.gitconfig
• $XDG_CONFIG_HOME/git(기본값 ~/.config/git) 아래의 config, ignore, attributes 파일
• 전역 git 구성이 [include], [includeIf], core.excludesFile 또는 core.attributesFile을 통해 지정하는 파일

permissions.blockWritesOutsideWorkingDirectories

• 범위: Any file. 세션이 로드하는 어느 파일에서든 true가 적용되므로, 저장소는 자체적으로 차단을 켤 수는 있지만 사용자의 차단을 해제할 수는 없습니다. 클라우드 세션에서는 파일 도구가 그 자체로 경계 역할을 하는 컨테이너에서 실행되므로 Claude Code가 이 키를 적용하지 않을 수 있습니다.
• 타입: Boolean
  • true: 차단을 켭니다
  • false: 설정되지 않은 경우와 동일합니다. 다른 파일이 true를 설정하면 차단은 계속 적용됩니다
• 기본값: 설정되지 않음. 따라서 작업 디렉터리 외부의 쓰기는 권한 모드를 따릅니다. Claude Code가 관리형 설정의 permissions 객체를 읽을 수 없는 동안에도 차단이 켜집니다.

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}

쓰기 차단이 거부하는 항목과 계속 쓸 수 있는 항목

• Claude Code 설정 파일: 설정 파일로 차단을 해제할 수 있으므로 Claude Code는 작업 디렉터리 내부에서도 이러한 쓰기를 거부합니다. 설정 파일은 직접 편집하십시오.
• 저장소 설정에서만 추가한 디렉터리: additionalDirectories가 .claude/settings.json에만 나열하거나, git이 .claude/settings.local.json 파일을 추적되지 않는 파일로 보고하는 경우를 제외하고 해당 파일에만 나열한 디렉터리
• 서브에이전트의 워크트리: isolation: worktree 서브에이전트의 워크트리가 작업 디렉터리 외부에 있으면 해당 서브에이전트의 파일 편집이 거부됩니다
• 저장소가 선택한 디렉터리의 자동 메모리: 저장소 설정에서 autoMemoryDirectory가 지정하는 디렉터리

읽기 또는 쓰기 차단에서 디렉터리 하나 허용하기

permissions.defaultMode

• 범위: Any file. auto 및 bypassPermissions는 프로젝트 또는 로컬 설정에서는 적용되지 않으므로 대신 ~/.claude/settings.json에서 설정하십시오. v2.1.257 이전에는 bypassPermissions가 모든 파일에서 적용되었습니다. VS Code 확장이 시작하는 대화의 경우 Claude Code는 사용자, 관리형 및 --settings 값만 읽습니다.
• 타입: 다음 중 하나의 문자열
  • "default": Claude Code가 읽기만 묻지 않고 실행합니다
  • "acceptEdits": Claude Code가 파일 편집과 mkdir, mv 같은 일반적인 파일 시스템 명령도 묻지 않고 실행합니다
  • "plan": Claude Code가 읽고 계획하지만 사용자가 계획을 승인할 때까지 편집을 차단합니다
  • "auto": Claude Code가 일상적인 프롬프트 없이 실행합니다. 셸 명령 및 네트워크 요청 같은 작업이 실행되기 전에 백그라운드 분류기가 해당 작업이 사용자의 요청과 일치하는지 확인합니다
  • "dontAsk": Claude Code가 원래 확인을 요청할 모든 호출을 자동으로 거부합니다. 단, 설치한 mod는 여전히 해당 호출 중 일부를 승인할 수 있습니다. 작업 디렉터리 내부의 파일 읽기, 승인이 필요 없는 기타 작업, 사전 승인된 도구는 네트워크 경로에서의 읽기를 제외하고 계속 실행됩니다
  • "bypassPermissions": Claude Code가 모든 것을 묻지 않고 실행합니다
  • "manual": "default"의 별칭입니다
• 기본값: 설정되지 않음
• 세션별 재정의: --permission-mode와 bypassPermissions에 해당하는 --dangerously-skip-permissions는 하나의 세션에서 이 키보다 우선합니다

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

permissions.denyInsteadOfPrompting

• 범위: User or managed 및 --settings. 저장소는 사용자를 대신해 이를 설정할 수 없습니다.
• 타입: Boolean
  • true: Claude Code가 원래 확인을 요청할 호출을 거부합니다
  • false: 설정되지 않은 경우와 동일합니다. 이러한 소스 중 다른 소스가 true를 설정하면 호출은 계속 거부됩니다
• 기본값: 설정되지 않음. 따라서 승인이 필요한 호출은 확인을 요청합니다

{
  "permissions": {
    "defaultMode": "auto",
    "denyInsteadOfPrompting": true
  }
}

denyInsteadOfPrompting이 추가로 중지하는 항목

• 질문 및 플랜 도구: Claude Code는 AskUserQuestion, EnterPlanMode, ExitPlanMode를 제외하므로 플랜 모드의 세션은 스스로 플랜 모드를 벗어날 수 없습니다. 에이전트 팀의 팀원은 EnterPlanMode 및 ExitPlanMode를 유지합니다
• MCP elicitation: Elicitation 훅이 응답하지 않는 한 Claude Code는 elicitation 요청을 취소합니다
• 권한 호스트: Claude Code는 canUseTool 콜백 또는 --permission-prompt-tool에 묻지 않습니다. 코드에서 호출을 승인하려면 PermissionRequest 훅에서 응답하십시오. 어떤 확인 규칙도 적용되지 않는 auto 모드의 중요 경로 제거처럼 일부 호출은 훅에 묻기 전에 거부됩니다.
• 분류기 청구 알림: 청구되는 분류기 요청에 대한 알림이 대화 상자를 열게 되는 경우, Claude Code는 이를 표시하지 않고 해당 요청이 필요한 작업을 거부합니다

denyInsteadOfPrompting의 메시지

Permission for this tool use was denied. It requires approval, and this session has no approval surface

no approval surface in this session; permission request denied automatically

20 actions were refused and no work went ahead in between, so Claude stopped.

permissions.disableBypassPermissionsMode

• 범위: Any file. 일반적으로 조직 정책을 적용하기 위해 관리형 설정에서 설정합니다.
• 타입: 문자열 "disable"
• 기본값: 설정되지 않음
• 세션별 재정의: 이 키는 --dangerously-skip-permissions보다 우선하며, 키가 설정된 동안 Claude Code는 해당 플래그를 거부합니다

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

skipAutoPermissionPrompt

• 범위: User or managed. 저장소는 사용자를 대신해 이를 설정할 수 없습니다.
• 타입: Boolean
  • true: Claude Code가 알림을 건너뜁니다
  • false: 설정되지 않은 경우와 동일합니다. 이러한 파일 중 다른 파일이 true를 설정하지 않는 한 알림이 한 번 표시됩니다
• 기본값: 설정되지 않음. 따라서 알림이 한 번 표시됩니다

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

• 범위: User, local, or managed 및 --settings로 전달된 파일. 백그라운드 세션은 사용자 및 관리형 설정만 반영합니다. 신뢰할 수 없는 저장소는 사용자를 대신해 대화 상자를 건너뛸 수 없습니다.
• 타입: Boolean
  • true: 세션이 bypassPermissions 모드로 진입하기 전에 Claude Code가 확인 대화 상자를 건너뜁니다
  • false: 설정되지 않은 경우와 동일합니다. 이러한 파일 중 다른 파일이 true를 설정하지 않는 한 대화 상자가 표시됩니다
• 기본값: 설정되지 않음. 따라서 대화 상자가 표시됩니다

{
  "skipDangerousModePermissionPrompt": true
}

샌드박스 설정

sandbox

• 범위: Any file
• 유형: enabled, failIfUnavailable, autoAllowBashIfSandboxed, excludedCommands, allowUnsandboxedCommands, enableWeakerNestedSandbox, enableWeakerNetworkIsolation, allowAppleEvents, allowNestedUserNamespaces, bwrapPath, socatPath, ignoreViolations, ripgrep과 filesystem, network, credentials 객체를 포함하는 객체
• 기본값: 설정되지 않음. Claude Code는 샌드박스 없이 명령을 실행합니다.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

sandbox.enabled

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: Claude Code는 Bash 명령을 샌드박스합니다.
  • false: Bash 명령은 샌드박스 없이 실행됩니다.
• 기본값: false

{
  "sandbox": {
    "enabled": true
  }
}

sandbox.failIfUnavailable

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: sandbox.enabled가 true이지만 샌드박스를 시작할 수 없으면 Claude Code가 시작 시 오류와 함께 종료됩니다. 샌드박스가 이 검사를 통과한 후 초기화에 실패하면 세션은 계속 실행되고 Claude Code는 샌드박스 처리된 각 명령을 거부합니다
  • false: 샌드박스를 시작할 수 없으면 Claude Code가 샌드박스 없이 명령을 실행합니다
• 기본값: false

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

sandbox.autoAllowBashIfSandboxed

• 범위: Any file
• 유형: Boolean
  • true: Claude Code는 자동 허용 모드에서 설명하는 경우를 제외하고 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. CLAUDE_CODE_SUBPROCESS_ENV_SCRUB는 자동 허용을 끕니다.
  • false: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. /sandbox 모드 탭에서 이를 일반 권한 모드라고 부릅니다.
• 기본값: true

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}

sandbox.excludedCommands

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 명령 패턴의 배열
• 기본값: 설정되지 않음. 제외되는 명령이 없습니다.

{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}

• sudo, eval, 또는 xargs로 시작하는 명령
• 호출의 어디든 나타나는 cd, pushd, 또는 popd
• 명령 대체, 하위 셸, 또는 if 또는 for와 같은 제어 흐름 블록
• docker build . > build.log나 <<EOF heredoc 같은 리디렉션. 단, 2>&1처럼 파일 디스크립터를 복제하기만 하는 것은 제외
• 변수에서 오는 명령 이름
• 경로 인수가 절대 경로이거나, ~로 시작하거나, .. 세그먼트를 포함하는 git clone, git init, git worktree add, git worktree move, 또는 git bundle create

sandbox.allowUnsandboxedCommands

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: 샌드박스가 명령을 차단한 후 Claude는 dangerouslyDisableSandbox 매개변수를 사용하여 샌드박스 외부에서 명령을 재시도할 수 있습니다.
  • false: Claude Code는 해당 매개변수를 무시하므로, 샌드박스가 실행 중인 동안 Claude가 실행하는 명령은 excludedCommands 항목과 일치하지 않는 한 샌드박스됩니다.
• 기본값: true

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

sandbox.filesystem

• 범위: Any file
• 유형: allowWrite, denyWrite, denyRead, allowRead 배열을 포함하는 객체이며, allowManagedReadPathsOnly 및 disabled Boolean도 포함합니다.
• 기본값: 설정되지 않음. 기본 읽기 및 쓰기 경계가 적용됩니다.

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

샌드박스 경로 접두사

샌드박스 경로에서 와일드카드가 작동하는 위치

~/keys/*.pem              the entry
/home/alice/keys/*.pem    its full path
 ^^^^                     the first directory name, home

대괄호, 중괄호, 소괄호가 포함된 디렉터리 이름

app/
└── [slug]/
    └── page.tsx

• [slug] 같은 대괄호: macOS의 모든 목록과 Linux 및 WSL2의 denyRead, allowRead에서 ./app/[slug]의 대괄호는 패턴으로도 작동합니다. 그러면 이 항목은 app/s나 app/g처럼 app 아래에서 slug의 문자 하나로 이름 지어진 모든 경로와도 일치합니다. 이 항목이 allowRead에 있거나 macOS의 allowWrite에 있으면 샌드박스 처리된 명령이 그런 경로에도 접근할 수 있습니다. 접근해서는 안 되는 경로는 이름을 바꾸세요.
• [user-id]나 [post-id]처럼 하이픈 왼쪽 문자가 오른쪽 문자보다 뒤에 정렬되는 대괄호: ./app/[user-id]는 모든 플랫폼의 모든 목록에서 정확히 그 이름을 가진 디렉터리만 포괄합니다. v2.1.304 이전에는 denyRead 또는 allowRead에 이런 항목이 있으면 Linux와 WSL2에서 샌드박스 처리된 명령이 시작되지 않았습니다.
• 중괄호와 소괄호: 이들은 일반 문자이므로 ~/data/{keys,tokens}는 두 가지 대안이 아니라 {keys,tokens}라는 이름의 디렉터리 하나를 포괄합니다. ~/data/keys와 ~/data/tokens를 포괄하려면 각각을 별도 항목으로 추가하세요.

sandbox.filesystem.allowWrite

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 샌드박스 경로 접두사를 사용하는 경로 문자열의 배열
• 기본값: 설정되지 않음. 샌드박스된 명령은 작업 디렉터리, 사용자별 임시 디렉터리, --add-dir 또는 /add-dir로 추가한 디렉터리, permissions.additionalDirectories의 디렉터리에 쓸 수 있습니다.

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"]
    }
  }
}

sandbox.filesystem.denyWrite

• 범위: Any file
• 유형: 샌드박스 경로 접두사를 사용하는 경로 문자열의 배열
• 기본값: 설정되지 않음

{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}

sandbox.filesystem.denyRead

• 범위: Any file
• 유형: 샌드박스 경로 접두사를 사용하는 경로 문자열의 배열
• 기본값: 설정되지 않음. 샌드박스된 명령은 ~/.aws/credentials와 같은 자격 증명 파일을 포함한 기본 읽기 액세스를 유지합니다.

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

sandbox.filesystem.allowRead

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 샌드박스 경로 접두사를 사용하는 경로 문자열의 배열
• 기본값: 설정되지 않음

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

sandbox.filesystem.allowManagedReadPathsOnly

• 범위: Managed
• 유형: Boolean
  • true: Claude Code는 관리형 설정의 allowRead 항목만 인정합니다.
  • false: 다른 설정 파일의 allowRead 항목이 병합될 수 있습니다.
• 기본값: false

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["~/work"],
      "allowManagedReadPathsOnly": true
    }
  }
}

sandbox.filesystem.disabled

• 범위: User or managed. 관리형 설정이 sandbox.filesystem을 조금이라도 구성하거나 "mode": "deny"인 sandbox.credentials.files 항목을 나열하는 경우, 관리형 설정만 이 키를 설정할 수 있습니다.
• 유형: Boolean
  • true: Claude Code는 파일시스템 격리를 건너뛰고 네트워크 격리를 유지합니다.
  • false: 파일시스템 격리는 켜진 상태로 유지됩니다.
• 기본값: false. 파일시스템 격리는 켜진 상태로 유지됩니다.

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

sandbox.ignoreViolations

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 명령 부분 문자열을 위반 부분 문자열의 배열에 매핑하는 객체(일반적으로 경로)
• 기본값: 설정되지 않음. 모든 위반이 보고됩니다.

{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

sandbox.enableWeakerNestedSandbox

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: 내부 샌드박스는 새로운 /proc을 마운트하는 대신 컨테이너의 기존 /proc을 바인드 마운트합니다.
  • false: 샌드박스는 새로운 /proc을 마운트하며, 이는 권한 없는 Docker 컨테이너에서 작동하지 않습니다.
• 기본값: false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNestedSandbox": true
  }
}

sandbox.enableWeakerNetworkIsolation

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: macOS의 샌드박스된 명령은 com.apple.trustd.agent에 도달할 수 있습니다.
  • false: macOS의 샌드박스된 명령은 시스템 TLS 신뢰 서비스에 도달할 수 없습니다.
• 기본값: false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNetworkIsolation": true
  }
}

sandbox.allowAppleEvents

• 범위: User or managed
• 유형: Boolean
  • true: macOS의 샌드박스된 명령은 Apple Events를 보낼 수 있습니다.
  • false: macOS의 샌드박스된 명령은 Apple Events를 보낼 수 없으므로, open 및 osascript는 오류 -600으로 실패합니다.
• 기본값: false

{
  "sandbox": {
    "enabled": true,
    "allowAppleEvents": true
  }
}

sandbox.allowNestedUserNamespaces

• 범위: User or managed. true는 ~/.claude/settings.json, --settings로 전달된 JSON, 또는 관리형 설정에서 온 경우에만 유효합니다. Claude Code는 프로젝트의 .claude/settings.json 또는 .claude/settings.local.json에 있는 true를 무시합니다. CLAUDE_CODE_SUBPROCESS_ENV_SCRUB가 1로 설정된 세션에서는 Claude Code가 모든 소스의 true를 무시합니다. false는 설정 우선순위에 따라 어떤 파일에서든 유효합니다.
• 유형: Boolean
  • true: 샌드박스된 명령이 사용자 네임스페이스를 생성할 수 있습니다
  • false: 이 키가 추가로 허용하는 것이 없으며, 샌드박스의 기본값이 적용됩니다
• 기본값: false

{
  "sandbox": {
    "enabled": true,
    "allowNestedUserNamespaces": true
  }
}

sandbox.ripgrep

• 범위: User or managed
• 유형: ripgrep 바이너리의 경로인 command를 포함하는 객체이며, 선택적 args(앞에 붙일 인수의 배열)도 포함합니다.
• 기본값: 설정되지 않음. 샌드박스는 Claude Code와 동일한 ripgrep 바이너리를 사용합니다. 이는 USE_BUILTIN_RIPGREP을 0으로 설정하지 않으면 번들된 바이너리입니다.

{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}

sandbox.bwrapPath

• 범위: Managed. 사용자, 프로젝트, 로컬 파일이 샌드박스를 다른 바이너리로 지정하지 못하도록 Claude Code는 관리형 설정에서만 이 키를 읽습니다.
• 유형: 문자열, 절대 경로. Claude Code는 상대 경로를 버리고 PATH 조회로 돌아갑니다.
• 기본값: 설정되지 않음. Claude Code는 PATH에서 bwrap을 찾습니다.

{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap"
  }
}

sandbox.socatPath

• 범위: Managed
• 유형: 문자열, 절대 경로. Claude Code는 상대 경로를 버리고 PATH 조회로 돌아갑니다.
• 기본값: 설정되지 않음. Claude Code는 PATH에서 socat을 찾습니다.

{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}

sandbox.credentials

• 범위: Any file. Claude Code는 mask 항목, allowPlaintextInject, awsPairs, sigv4를 사용자 설정, 관리형 설정, --settings 플래그에서만 적용합니다.
• 유형: files, envVars, allowPlaintextInject, awsPairs, sigv4를 포함하는 객체
• 기본값: 설정되지 않음. 보호되는 자격 증명이 없습니다.

{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}

관리형 설정의 잘못된 자격 증명 항목

• 유효한 path 또는 name 및 mask 또는 deny의 mode를 여전히 가진 files 또는 envVars의 항목(예: extract 패턴에 캡처 그룹이 없는 항목)은 경고와 함께 mode: "deny"로 저하되므로, 자격 증명은 항목을 수정할 때까지 마스크되지 않고 차단된 상태로 유지됩니다. 저하된 files 항목은 명시적 deny 항목처럼 filesystem.disabled를 고정하며, 경고는 관리형 설정이 파일시스템 격리를 끄면 읽기 차단이 적용되지 않음을 알립니다.
• 알 수 없는 mode 또는 잘못된 path 또는 name을 가진 항목은 제거됩니다.
• 각 경우에 경고가 표시됩니다. 항목이 저하되든 제거되든 나머지 유효한 항목은 여전히 적용됩니다.

sandbox.credentials.files

• 범위: Any file. Claude Code는 프로젝트 .claude/settings.json과 로컬 .claude/settings.local.json의 mask 항목을 무시합니다.
• 유형: 각각 path 및 "deny" 또는 "mask"의 mode를 포함하는 객체의 배열이며, 선택적 파일용 마스크 필드도 포함합니다.
• 기본값: 설정되지 않음. 보호되는 자격 증명 파일이 없습니다.

{
  "sandbox": {
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

파일용 마스크 필드

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "maskDuplicates": true,
          "onExtractNoMatch": "deny",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

sandbox.credentials.envVars

• 범위: Any file. Claude Code는 프로젝트 .claude/settings.json과 로컬 .claude/settings.local.json의 mask 항목을 무시합니다.
• 유형: 각각 name 및 "deny" 또는 "mask"의 mode를 포함하는 객체의 배열이며, 선택적 환경 변수용 마스크 필드도 포함합니다.
• 기본값: 설정되지 않음. 보호되는 환경 변수가 없습니다.

{
  "sandbox": {
    "credentials": {
      "envVars": [
        { "name": "NPM_TOKEN", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

환경 변수용 마스크 필드

{
  "sandbox": {
    "credentials": {
      "envVars": [
        {
          "name": "DATABASE_URL",
          "mode": "mask",
          "extract": "://[^:]+:([^@]+)@",
          "onExtractNoMatch": "deny"
        },
        {
          "name": "SERVICE_JWT",
          "mode": "mask",
          "decode": "jwt",
          "maskClaims": ["api_key"]
        }
      ]
    }
  }
}