모든 설정

Claude Code settings.json의 모든 키에 대한 완전한 참조: 각 키의 위치, 유형 및 기본값, 붙여넣기 가능한 예제, 모든 키의 인덱스.

인덱스로 돌아가기

이 참조 페이지는 Claude Code가 설정 파일에서 읽는 각 키와 대신 ~/.claude.json에 유지하는 짧은 키 그룹을 나열합니다. 파일을 선택하거나 우선순위를 확인하려면 설정 파일 및 우선순위에서 시작하십시오.

설정 색인

아래의 각 키는 해당 항목으로 연결됩니다. 범위는 키를 넣을 수 있는 파일을 나타냅니다. 사용자는 ~/.claude/settings.json, 프로젝트는 .claude/settings.json, 로컬은 .claude/settings.local.json, 관리형은 조직이 배포하는 설정입니다. 모든 파일은 네 가지 모두를 의미하며, 전역 구성은 ~/.claude.json을 의미합니다.

모델 및 응답

Claude Code가 사용하는 모델과 응답 방식을 선택합니다. 이러한 설정이 /model 명령 및 환경 변수와 어떻게 상호 작용하는지는 모델 구성을 참조하세요.

advisorModel

Claude가 서버 측 advisor 도구를 호출할 때 응답할 모델을 선택합니다. advisor를 끄려면 이 키를 설정 해제합니다. advisor는 최소한 메인 모델과 동등한 성능을 갖춰야 합니다. 허용되는 조합과 허용되지 않는 모델을 선택했을 때 어떻게 되는지는 advisor 모델 선택을 참조하세요.

일반적으로 이 키를 직접 편집하지 않습니다. /advisor를 실행하면 현재 선택, advisor로 사용할 수 있는 모델, No advisor를 보여 주는 선택기가 열립니다. Claude Code는 선택한 항목을 ~/.claude/settings.json의 이 키에 저장합니다. Remote Control 클라이언트에서 선택하거나 원격 워커에 연결된 세션에서 선택하면 해당 선택은 그 세션에만 적용되며 이 키는 변경되지 않습니다.

계정에 사용량 크레딧 동의가 필요한 경우 먼저 /model fable을 실행하여 동의해야 합니다. 동의하기 전까지는 /advisor에서 Fable을 선택해도 아무것도 저장되지 않으며, Claude Code가 먼저 /model fable을 실행하라고 안내합니다.

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

{
  "advisorModel": "opus"
}

이 키는 Amazon Bedrock 및 Claude Platform on AWS처럼 advisor를 사용할 수 없는 공급자에서는 효과가 없습니다. "fable"에는 Fable 액세스가 필요합니다.

alwaysThinkingEnabled

이 값을 false로 설정하면 모든 세션에서 확장 사고를 끕니다. 사고는 기본적으로 켜져 있으므로 true는 아무것도 바꾸지 않습니다. 대부분 파일을 편집하는 대신 /config를 통해 설정합니다.

Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 모델처럼 항상 사고하는 모델에서는 false가 효과가 없습니다. 서드파티 공급자에서는 Claude Code가 사고를 끄는 대신 thinking 매개변수를 생략하므로 적응형 추론 모델은 여전히 사고할 수 있습니다. Anthropic API에서 사고를 끈 상태에서는, Opus 5처럼 해당 조합을 허용하지 않는 것으로 알려진 모델에 Claude Code가 더 높은 수준 대신 effort high를 보냅니다.

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

{
  "alwaysThinkingEnabled": false
}

availableModels

메인 세션, 서브에이전트, 스킬, advisor에 사용자가 선택할 수 있는 모델을 제한합니다. 관리형 목록은 /model, --model, 개발자 자신의 파일에 있는 model 키를 제한하며, 목록에 없는 모델은 선택할 수 없습니다. 기본 접두사 매칭에서는 이 키만으로 Default 옵션에 영향을 주지 않으므로, 그러려면 enforceAvailableModels와 함께 사용하세요.

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

이 예시는 Sonnet 및 Haiku 모델만 선택할 수 있도록 합니다:

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

"claude-opus-5"와 같은 모델 ID 항목은 Opus 5.5처럼 이를 확장하는 이후 버전도 허용합니다. 그러한 버전 중 하나를 차단하려면 deniedModels를 사용하세요. 각 모델 ID 항목이 명시한 버전만 허용하도록 하려면 availableModelsMatch를 사용하세요. 모델 선택 제한을 참조하세요.

availableModelsMatch

availableModels 항목이 모델 ID와 일치하는 방식을 선택합니다. 기본적으로 모델 ID 항목은 이를 확장하는 이후 버전도 허용하므로 "claude-opus-5"는 Opus 5.5를 허용합니다. "exact"를 사용하면 각 모델 ID 항목은 명시한 버전만 허용하므로, 해당 모델의 새 버전은 목록에 추가할 때까지 차단된 상태로 유지됩니다. Claude Code v2.1.283 이상이 필요합니다.

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

이 예시는 Opus 5와 Sonnet 5를 허용하고 둘 다 이후 릴리스는 허용하지 않습니다:

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

"exact"를 사용하면 목록에 모델이나 계열이 하나 이상 명시되어 있을 때마다 Default 옵션도 목록의 모델로 제한됩니다. 특정 모델 또는 버전 차단을 참조하세요.

deniedModels

availableModels 허용 목록의 유무와 관계없이, 그리고 해당 목록이 허용하더라도 특정 모델을 차단합니다. Claude Code는 차단된 모델을 /model 선택기에서 숨기며, availableModels가 적용되는 어디에서도 해당 모델을 선택할 수 없습니다. 특정 모델 또는 버전 차단에서 설명하듯이 Default 옵션을 사용하는 세션도 차단된 모델을 실행하지 않습니다. Claude Code v2.1.283 이상이 필요합니다.

• 범위: 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 항목은 무시됩니다
• 기본값: 설정되지 않음. 따라서 차단되는 모델이 없습니다

이 예시는 Opus 및 Sonnet 모델을 허용하고 Opus 5.5를 차단합니다:

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

특정 모델 또는 버전 차단을 참조하세요.

effortLevel

수준을 저장하지 않은 모델에 대한 기본 effort 수준을 설정합니다. 낮은 수준은 간단한 작업에서 더 빠르고 저렴하며, 높은 수준은 복잡한 문제에서 더 깊이 추론합니다.

로컬 머신의 대화형 세션에서 /effort low, medium, high, xhigh를 실행하면 Claude Code는 이 키에 쓰는 대신 활성 모델에 대한 수준을 modelSettings 아래에 저장합니다. v2.1.251 이전에는 /effort가 이 키에 썼습니다.

같은 설정 파일 내에서 Claude Code는 이 키보다 모델의 저장된 수준을 사용합니다. 파일 간 우선순위는 modelSettings에 설명되어 있습니다.

원격 워커에 연결된 세션, -p 실행, Agent SDK에서는 /effort가 해당 세션에만 적용됩니다. 해당 세션에만 적용되는 대화형 선택 항목은 effort 수준 조정에 나열되어 있습니다. /effort가 출력하는 메시지에서 어떤 방식으로 적용되었는지 알려 줍니다.

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

{
  "effortLevel": "xhigh"
}

사용자 설정 파일 ~/.claude/settings.json에서 이 키는 /effort가 모델별로 수준을 저장하기 전에 쓰던 이전 형식이며, Opus 5, Fable 5.1 및 이전 모델처럼 이전에 적용되던 곳에 계속 적용됩니다. Opus 5.5 및 그 이후에 출시된 모델은 이 키를 무시하고 수준을 저장하기 전까지 자체 기본값으로 시작하며, /effort는 해당 수준을 modelSettings 아래에 씁니다. 프로젝트, 로컬, 관리형 설정과 --settings에서는 이 키가 모든 모델에 적용됩니다.

enforceAvailableModels

/model 선택기에는 Default 옵션이 있으며, 이 옵션이 어떤 모델로 해석되는지는 default 모델 설정에 설명되어 있습니다. availableModels 허용 목록은 지정할 수 있는 모델을 제한하지만, 기본 접두사 매칭에서는 계정 유형의 기본값을 다시 매핑하지 않으므로 Default가 여전히 목록 밖의 모델로 해석될 수 있습니다. 이 키는 그 공백을 메웁니다. Claude Code v2.1.175 이상이 필요합니다.

조직에서 관리형 설정을 배포하는 경우 Claude Code는 관리형 소스에서만 이 키를 읽고 다른 파일의 이 키는 무시합니다.

시작 시 모델 검사에 이 키가 어떻게 적용되는지는 Amazon Bedrock 및 Google Cloud의 Agent Platform을 참조하세요.

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

이 예시는 지정 선택을 Sonnet 및 Haiku 모델로 제한하고 Default가 그중 처음으로 사용 가능한 모델로 해석되도록 합니다:

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

availableModels가 설정되지 않았거나 비어 있으면 이 키는 효과가 없습니다. Default 모델에 허용 목록 적용을 참조하세요. Claude Code v2.1.175 이상이 필요합니다.

fallbackModel

기본 모델이 과부하 상태이거나 사용할 수 없을 때 Claude Code가 순서대로 시도할 백업 모델을 지정합니다. Claude Code는 턴의 나머지 부분 동안 체인에서 다음으로 사용 가능한 모델로 전환하고 알림을 표시합니다. 체인이 없으면 Claude Code는 같은 모델을 재시도한 뒤 서버의 오류를 표시하며, 사용자가 직접 재시도하거나 모델을 전환해야 합니다.

전환하면 폴백 모델에서 프롬프트 캐시가 비어 있는 상태로 한 턴이 진행됩니다. 다음 메시지에서는 다시 기본 모델을 먼저 시도합니다.

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

이 예시는 기본 모델이 실패하면 Sonnet 5를 먼저 시도한 다음 Haiku 4.5를 시도합니다:

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

대부분의 배열 설정과 달리 이 키는 설정 파일 간에 병합되지 않습니다. 이 키를 정의한 우선순위가 가장 높은 파일이 체인 전체를 제공합니다. 프로젝트 파일에서 ["claude-sonnet-5"]를 설정하고 사용자 파일에서 ["claude-haiku-4-5"]를 설정하면 체인은 ["claude-sonnet-5"]뿐입니다. Claude Code는 목록에서 서로 다른 허용 모델을 최대 세 개까지 유지하고 나머지는 무시합니다. 폴백 모델 체인을 참조하세요.

fastMode

사용 가능한 세션에서 빠른 모드를 켭니다. 토큰당 비용이 더 높더라도 속도가 필요한 빠른 반복이나 실시간 디버깅 같은 대화형 작업에 적합합니다. 일반적으로 이 키를 직접 편집하지 않습니다. /fast를 실행하면 ~/.claude/settings.json에 fastMode: true가 기록되고, 다시 실행하여 빠른 모드를 끄면 키가 제거됩니다. 빠른 모드는 Opus 5.5, Opus 5, Opus 4.8에서만 실행됩니다. 다른 모델에서 켜면 Opus로 전환되며, 지원되지 않는 모델로 전환하면 꺼집니다. 빠른 모드가 켜진 상태에서 모델 전환을 참조하세요.

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

{
  "fastMode": true
}

fastModePerSessionOptIn

일반적으로 /fast를 실행하면 fastMode가 사용자 설정에 저장되므로 이후 모든 세션이 시작될 때 빠른 모드가 켜집니다. 이를 막으려면 이 키를 true로 설정합니다. 그러면 저장된 fastMode: true가 더 이상 세션 시작 시 빠른 모드를 켜지 않으며, 각 사용자는 빠른 모드를 원하는 세션마다 /fast를 실행해야 합니다. Claude Code는 파일의 fastMode 키를 그대로 두므로 이 키를 끄면 이전 동작이 복원됩니다.

Team 또는 Enterprise 플랜의 Owner는 서버 관리형 설정을 통해 조직 전체에 배포할 수 있습니다. 관리형 설정에서 이 키를 설정하면 대화형 터미널 세션 외부에서는 /fast on이 거부되고 조직에서 빠른 모드를 비활성화했다고 알립니다. 여기에는 비대화형 모드, VS Code 확장, 클라우드 세션이 포함됩니다.

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

{
  "fastModePerSessionOptIn": true
}

세션별 옵트인 요구를 참조하세요.

language

Claude가 기본적으로 영어가 아닌 언어로 응답하도록 합니다. 응답에 대한 고정된 목록은 없습니다. Claude Code는 이 값을 해당 언어로 항상 응답하라는 지시로 Claude에 그대로 전달하므로 Claude가 읽을 수 있는 모든 언어 이름이 작동합니다. Claude Code는 값을 확인하지 않으므로 철자가 틀린 이름은 오류를 발생시키지 않고 작성된 그대로 Claude에 전달됩니다. 같은 값이 음성 받아쓰기의 언어와 자동 생성되는 세션 제목의 언어도 설정하며, 음성 받아쓰기에는 지원되는 받아쓰기 언어의 고정 목록이 있습니다.

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

{
  "language": "japanese"
}

maxEffortLevel

세션이 사용할 수 있는 effort 수준의 상한을 정하고, 그보다 낮은 수준은 계속 사용할 수 있도록 합니다. 더 높은 수준은 상한에서 대신 실행되며, 여기에는 /effort, /model 선택기, --effort, CLAUDE_CODE_EFFORT_LEVEL, 스킬이나 서브에이전트의 effort frontmatter, 모델 자체 기본값에서 온 수준이 포함됩니다. Claude Code가 각 요청 전에 직접 상한을 적용하므로 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry를 포함한 모든 공급자에서 유지됩니다. Claude Code v2.1.267 이상이 필요합니다.

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

이 예시는 모든 모델의 상한을 medium으로 정하고 Sonnet 4.6은 제외합니다:

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

조직에서 모델에 대한 effort 제한도 설정한 경우 두 상한 중 낮은 값이 적용됩니다.

model

모든 새 세션이 사용할 모델을 설정하여 매번 /model로 모델을 선택하지 않아도 되도록 합니다. 여기에서 설정해도 세션 중간에 전환하는 것은 막지 않습니다. 관리자가 사용자 선택을 재정의하도록 조직 기본 모델을 설정한 경우, 사용자, 프로젝트, 로컬 설정에서 이 키를 설정하더라도 해당 모델이 사용됩니다.

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

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

여기의 값은 ANTHROPIC_DEFAULT_MODEL보다 우선하며, Claude Code는 다른 어떤 것도 모델을 선택하지 않을 때만 ANTHROPIC_DEFAULT_MODEL을 사용합니다.

modelOverrides

Anthropic 모델 ID를 Amazon Bedrock 추론 프로필 ARN과 같은 공급자별 모델 ID에 매핑합니다. 그러면 각 모델 선택기 항목은 공급자 API를 호출할 때 매핑된 값을 사용합니다. 관리자는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 추론 프로필, 버전 이름 또는 배포로 라우팅하는 데 이를 사용합니다.

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

이 예시는 Opus 4.6에 대한 모든 호출을 지정된 Bedrock 추론 프로필로 라우팅합니다:

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

버전별 모델 ID 재정의를 참조하세요.

modelPicker

/model 선택기가 제공하는 모델을 작성한 순서대로 원하는 레이블로 나열하여, 선택기가 기본 제공 라인업 뒤에 또는 그 대신 조직에서 실행하는 모델을 나열하도록 합니다. 각 행의 model은 그대로 사용되므로 --model이 허용하는 모든 것을 허용합니다. 즉 opus와 같은 별칭, Anthropic 모델 ID, 또는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, LLM 게이트웨이용 공급자 형식 ID를 사용할 수 있습니다. Claude Code v2.1.242 이상이 필요합니다.

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

이 예시는 기본 제공 라인업 뒤에 팀이 알아볼 수 있는 이름으로 두 개의 Bedrock 배포를 추가합니다:

{
  "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의 필드

이 키는 두 개의 필드를 받습니다. 하나는 행 자체에 대한 것이고, 다른 하나는 행이 기본 제공 라인업을 대체할지 또는 추가될지에 대한 것입니다.

options의 항목은 model 옆에 선택적 behavesAs 문자열도 가질 수 있으며, 이를 위해서는 v2.1.257 이상이 필요합니다. model이 현재 버전보다 새로운 항목에 claude-opus-4-8처럼 현재 Claude Code 버전이 이미 알고 있는 모델의 ID로 설정합니다. 그러면 Claude Code는 해당 모델을 알 수 없는 모델로 취급하는 대신 알려진 모델의 기능과 effort 기본값을 항목에 적용합니다. 항목의 레이블과 Claude Code가 요청에서 보내는 모델 ID는 변경되지 않습니다.

replaceBuiltInOptions를 켜면 Claude Code는 다른 모든 행을 숨깁니다. 여기에는 기본 제공 라인업, availableModels 항목에 대해 추가하는 행, 게이트웨이 검색이 찾은 모델, ANTHROPIC_CUSTOM_MODEL_OPTION이 포함됩니다. 끄면 Claude Code는 기본 제공 라인업이 이미 포함하는 나열된 모델을 건너뜁니다. 레이블은 선택기에 표시되는 내용만 바꾸며 Claude Code가 실행하는 모델은 바꾸지 않습니다.

availableModels 허용 목록은 이 행들에도 여전히 적용됩니다. 나열된 모델을 허용 목록에 추가하기 전에 병합 동작을 읽어 보세요. 특정 모델 ID는 해당 계열의 와일드카드 항목을 좁힙니다. Claude Code는 선택기를 표시하기 전에 각 행을 세션과 대조하여 확인하기도 합니다:

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

Claude Code는 구문 분석할 수 없는 행을 제거하고 나머지는 유지합니다. 손상된 설정 파일 수정을 참조하세요.

modelPricing

정가 대신 조직에서 지불하는 요율로 지출을 보고합니다. 조직에 계약 요율이 있을 때 설정하면 개발자에게 표시되는 금액이 청구서와 일치합니다. Claude Code는 /usage, 상태줄, Agent SDK의 total_cost_usd, --max-budget-usd 제한, OpenTelemetry 비용 지표 및 이벤트에 요율을 적용합니다. 요율은 직접 제공해야 합니다. Claude Code는 계약이나 Claude Console에서 요율을 읽지 않습니다. Claude Code v2.1.242 이상이 필요합니다.

• 범위: 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는 정가를 보고합니다

일률적인 할인이나 인상에는 multiplier만, 모델별 요율에는 overrides만 설정하거나 둘 다 설정합니다.

이 예시는 Sonnet 4.6의 계약 요율을 설정한 다음 Sonnet 행을 포함한 모든 금액을 15% 줄입니다:

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

모든 금액을 인상하려면 multiplier를 1보다 크게, 최대 10까지 설정합니다. 인상에는 Claude Code v2.1.271 이상이 필요합니다. 이전 버전은 1보다 큰 multiplier를 경고와 함께 무시하고 설정의 나머지 부분은 유지합니다.

요율이 적용되었는지 확인하는 방법을 포함한 단계는 계약 요율로 지출 보고를 참조하세요.

modelPricing의 필드

Claude Code는 빠른 모드 추가 요금이나 미국 전용 추론 요율을 더하지 않고 작성한 그대로 행의 요율을 사용합니다. multiplier도 설정하면 Claude Code는 행의 요율 위에 이를 적용합니다. Claude Code는 구문 분석할 수 없는 요율이 있는 행이나 구문 분석할 수 없는 multiplier를 제거하고 나머지는 유지합니다. 손상된 설정 파일 수정을 참조하세요.

modelPricing 행이 적용되는 모델

Claude Code는 행의 키를 기준으로 행이 적용되는 모델을 결정합니다:

• 기본 제공 모델의 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

사용하는 각 모델에 대한 effort 수준을 저장합니다. Claude Code v2.1.251 이상이 필요합니다.

로컬 머신의 대화형 세션에서 /effort 또는 /model 선택기의 effort 슬라이더로 low, medium, high, xhigh를 기본값으로 저장하면 Claude Code는 사용 중인 모델 아래 여기에 해당 수준을 기록하므로, 이 키를 직접 편집할 일은 거의 없습니다. VS Code 확장의 모델 선택기에서 이러한 수준 중 하나를 선택하면 Claude Code는 같은 방식으로 여기에 저장합니다. /effort가 해당 세션에만 적용되는 세션은 effortLevel 항목에 나열되어 있습니다.

저장한 수준을 변경하거나 제거하려면 키를 직접 편집합니다.

여기의 모델별 effortLevel은 같은 설정 파일의 최상위 effortLevel보다 우선합니다. 파일 간에는 Claude Code가 각 모델을 개별적으로 해석합니다. 해당 모델에 대한 effortLevel 또는 해당 모델에 적용되는 최상위 effortLevel을 설정한 우선순위가 가장 높은 설정 파일이 결정하므로, 관리형 설정의 effortLevel은 사용자 설정에 저장한 수준보다 우선합니다. 실행 시 --effort처럼 저장된 수준을 재정의할 수 있는 다른 항목은 effort 수준 조정에 나열되어 있습니다.

한 모델의 수준을 설정하는 대신 effort 상한을 정하려면 해당 모델의 항목에 maxEffortLevel 필드를 추가합니다. 이 필드에는 Claude Code v2.1.267 이상이 필요합니다.

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

Claude Code는 각 항목을 claude-opus-5-5와 같은 모델의 표준 이름 아래에 기록하며, 해당 모델의 별칭, 날짜 접미사가 붙은 ID, [1m] ID, 인식되는 공급자별 ID를 같은 항목에 매칭합니다.

이 예시는 다른 모델은 각자의 저장된 수준이나 기본 수준을 사용하는 동안 Opus 5.5를 high로 유지합니다:

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

사용 중인 모델에 대해 저장된 수준을 지우려면 /effort auto를 실행합니다. Claude Code는 다른 항목과 최상위 effortLevel은 그대로 둡니다.

outputStyle

이름으로 출력 스타일을 선택합니다. 출력 스타일은 Claude의 역할, 어조, 출력 형식을 바꾸는 저장된 지침 세트로, 기본 제공 Explanatory 및 Learning 스타일이나 직접 작성한 스타일이 이에 해당합니다.

세션 중에 이 키를 변경하면 Claude는 다음 메시지부터 새 스타일을 사용합니다. 해당 메시지의 프롬프트 캐싱 비용은 출력 스타일 변경을 참조하세요. v2.1.251 이전에는 /clear를 실행하거나 새 세션을 시작한 후에야 편집 내용이 적용되었습니다.

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

이 예시는 작업 사이에 교육적인 인사이트를 추가하는 기본 제공 Explanatory 스타일을 선택합니다:

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

프롬프트 캐시가 메인 대화를 유지하는 기간을 선택합니다. 이 키는 대화형, -p, Agent SDK 턴과 Claude Code가 이와 함께 인라인으로 실행하는 헬퍼에 적용됩니다. 1시간 수명은 더 긴 휴식 동안에도 캐시를 유지하며, API는 5분 수명보다 각 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다.

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

이 예시는 메인 대화를 1시간 수명으로 유지하고 서브에이전트는 5분으로 둡니다:

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

각 수명의 비용은 캐시 수명을 참조하세요.

showThinkingSummaries

대화형 세션에서 Claude의 확장 사고 요약을 확인합니다. Ctrl+O로 사고를 펼칠 때 전체 요약을 보려면 설정합니다. 설정하지 않았거나 false이면 Anthropic API가 thinking 블록을 편집하여 가리고 Claude Code는 접힌 스텁을 표시합니다.

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

{
  "showThinkingSummaries": true
}

가리기는 표시되는 내용만 바꾸며 모델이 생성하는 내용은 바꾸지 않습니다. 사고 비용을 줄이려면 대신 예산을 낮추거나 사고를 비활성화하세요.

subagentPromptCacheTtl

프롬프트 캐시가 Claude Code가 메인 대화 외부에서 보내는 요청을 유지하는 기간을 선택합니다. 이 키는 서브에이전트, 워크플로, 그리고 압축 및 세션 제목과 같은 Claude Code 자체의 백그라운드 및 헬퍼 요청에 적용됩니다. 1시간 수명은 더 긴 휴식 동안에도 캐시를 유지하며, API는 5분 수명보다 각 캐시 쓰기에 더 높은 요율을 청구합니다. Claude Code v2.1.242 이상이 필요합니다.

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

이 예시는 서브에이전트와 메인 대화 외부의 다른 요청에 1시간 수명을 부여합니다:

{
  "subagentPromptCacheTtl": "1h"
}

이 키는 promptCacheTtl이 다루지 않는 요청을 다루므로, Claude Code가 보내는 모든 요청의 수명을 선택하려면 둘 다 설정하세요. 서브에이전트의 캐시가 메인 대화의 캐시와 어떻게 다른지는 서브에이전트와 캐시를 참조하세요.

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

ultracode를 켠 상태로 세션을 시작합니다. 켜면 Claude는 요청을 기다리지 않고 실질적인 각 작업에 대해 워크플로를 계획합니다. Claude는 동적 워크플로가 활성화되어 있고 모델이 xhigh effort를 지원할 때만 워크플로를 계획합니다. 이 키는 세션의 effort 수준을 바꾸지 않습니다. ultracode는 세션이 사용하는 수준에서 실행됩니다. Claude Code는 이 키를 읽기만 하고 쓰지는 않습니다. /effort ultracode는 현재 세션에 대해서만 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
}

세션의 effort 수준은 effortLevel, modelSettings 및 기타 effort 소스에서 결정되며, maxEffortLevel과 같은 effort 상한은 ultracode를 끄지 않고 해당 수준을 낮춥니다. 이 동작과 /effort ultracode off 형식에는 Claude Code v2.1.284 이상이 필요합니다. v2.1.284 이전에는 ultracode: true가 세션을 xhigh effort로 실행했으며, xhigh 미만의 effort 상한이 있으면 ultracode가 꺼진 상태로 유지되었습니다. Agent SDK apply_flag_settings 제어 요청도 이 키를 허용합니다.

권한 설정

Claude가 묻지 않고 수행할 수 있는 작업, 세션이 시작되는 권한 모드, 자동 모드 분류기가 허용하는 항목을 결정합니다. 규칙 구문과 권한 모델은 권한 구성을 참조하십시오.

allowManagedPermissionRulesOnly

관리형 설정을 권한 규칙의 유일한 설정 소스로 만듭니다. 그러면 Claude Code는 사용자, 프로젝트, 로컬 및 --settings 파일의 allow, ask, deny 규칙을 무시하고, --allowedTools를 무시하며, 권한 프롬프트에서 항상 허용 선택지를 숨기고, 새 규칙 저장을 중단합니다.

임베딩 호스트의 상위 설정이 적용되는 경우 Claude Code는 이를 관리형 계층의 일부로 취급합니다. 해당 설정의 allow 규칙과 additionalDirectories는 제외하고, deny 및 ask 규칙은 유지하되 패턴이 !로 시작하는 Read 및 Edit 규칙은 제외합니다. 이 키의 설정 여부와 관계없이 호스트는 ! 규칙으로 관리형 규칙에서 경로를 제외할 수 없습니다.

--disallowedTools 규칙과 현재 세션의 deny 및 ask 규칙은 Claude Code가 세션 도중 설정을 다시 로드한 후에도 계속 적용됩니다. 이러한 규칙은 제한만 하므로 관리형 규칙이 부여하는 범위를 넓힐 수 없습니다. v2.1.257 이전에는 Claude Code가 첫 설정 재로드 시 이러한 명령줄 및 세션 규칙을 제외했습니다.

--disallowedTools 또는 세션 규칙의 ! 패턴이 제외할 수 있는 범위는 Read 및 Edit 규칙을 참조하십시오.

이 키를 설정하면 Claude Code v2.1.282 이상은 다음 소스의 스킬 및 .claude/commands/ 파일에 있는 allowed-tools frontmatter도 무시합니다.

• 저장소의 .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 이상을 실행하는 경우

관리형 설정의 스킬과 번들 스킬은 allowed-tools를 유지합니다. 해당 Desktop 세션 외부의 @inline 플러그인도 anthropic-skills라는 이름의 플러그인을 제외하고 이를 유지합니다. 스킬의 disallowed-tools는 계속 적용됩니다. Claude Code가 이 필드를 무시할 때 개발자에게 표시되는 내용은 관리형 권한 규칙만 적용되는 경우를 참조하십시오.

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

{
  "allowManagedPermissionRulesOnly": true
}

이 키는 MCP 서버 허용 목록을 잠그지 않습니다. 이를 위해서는 allowManagedMcpServersOnly를 설정하십시오. 관리형 전용 설정을 참조하십시오.

autoMode

자동 모드 분류기가 차단하고 허용하는 항목에 자체 규칙을 추가합니다. 이를 사용해 조직이 신뢰하는 저장소, 버킷, 도메인을 분류기에 알려 일상적인 내부 작업을 더 이상 차단하지 않도록 합니다. 분류기에는 기본 제공 허용 및 거부 규칙이 포함되어 있습니다. 배열에 리터럴 문자열 "$defaults"를 포함하면 해당 위치에 기본 제공 규칙을 유지하고 그 주변에 자체 규칙을 추가할 수 있습니다. 이를 생략하면 기본 제공 규칙이 자체 규칙으로 대체됩니다.

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

이 예시는 "$defaults"를 통해 기본 제공 soft_deny 규칙을 유지하고, terraform apply를 차단하는 규칙을 하나 더 추가합니다.

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

이러한 파일 중 둘 이상이 같은 배열을 설정하면 Claude Code는 항목을 연결합니다. 규칙 형식과 각 배열이 적용되는 방식은 자동 모드 구성을 참조하십시오.

autoMode.classifyAllShell

자동 모드가 활성화된 동안 모든 Bash 및 PowerShell 명령을 자동 모드 분류기로 보냅니다. 기본적으로 자동 모드는 임의의 코드를 실행할 수 있는 허용 규칙만 일시 중지합니다. 즉, Bash(*) 같은 도구 전체 및 와일드카드 규칙과 Bash(python *) 같은 인터프리터 또는 셸 래퍼 접두사입니다. Bash(npm test)처럼 다른 허용 규칙과 일치하는 명령은 명령별 허용 도메인을 포함하지 않는 한 분류기를 건너뜁니다. 분류기를 건너뛰면 규칙의 접두사가 예상하지 못한 파괴적인 인수가 감지되지 않고 통과할 수 있습니다. 이 키를 설정하면 세션 동안 모든 셸 허용 규칙이 일시 중지되어 분류기가 모든 명령을 검토합니다. Claude Code v2.1.193 이상이 필요합니다.

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

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

모든 셸 명령을 분류기로 라우팅을 참조하십시오.

disableAutoMode

Shift+Tab 순환에서 자동 모드를 제거합니다. --permission-mode auto, 설정 파일 또는 기본 제공 기본값 등으로 인해 원래 자동 모드로 시작될 세션은 대신 default로 시작합니다. 관리자는 조직의 개발자가 자동 모드를 사용하지 못하도록 관리형 설정에서 이를 설정합니다.

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

{
  "disableAutoMode": "disable"
}

permissions

Claude가 묻지 않고 사용할 수 있는 도구, 항상 확인을 요청하는 도구, 차단되는 도구를 제어하고, 세션이 시작되는 권한 모드를 설정합니다. 아래의 모든 permissions.* 키는 이 객체 아래에 중첩됩니다.

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

이 예시는 npm run 명령을 묻지 않고 승인하고, git push 전에 확인을 요청하며, .env 읽기를 차단하고, 세션을 acceptEdits로 시작합니다.

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

세 가지 규칙 배열은 하나의 구문을 공유합니다. permissions.allow 아래의 권한 규칙 구문을 참조하십시오. 여러 파일의 권한 규칙이 결합되는 방식은 범위 간 권한 규칙 병합 방식을, 일반적인 설정 키가 결합되는 방식은 설정 가이드의 설정 우선순위를 참조하십시오.

useAutoModeDuringPlan

Claude Code가 플랜 모드에서 자동 모드 분류기를 사용해 셸 명령을 검토할지 여부를 선택합니다. 기본값 true에서는 자동 모드를 사용할 수 있을 때 계획 중 분류기가 각 명령을 검토하며, 중요 경로 제거를 제외하고는 프롬프트가 표시되지 않습니다. 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트를 받으려면 false로 설정하십시오. /config에는 Use auto mode during plan으로 표시됩니다.

• 범위: User, local, or managed. 저장소는 사용자를 대신해 이를 끌 수 없습니다.
• 타입: Boolean
  • true: 설정되지 않은 경우와 동일합니다. 자동 모드를 사용할 수 있을 때 분류기가 계획 중 각 셸 명령을 검토하며, 중요 경로 제거를 제외하고는 확인을 요청하지 않습니다. 이러한 파일 중 하나라도 false를 설정하면 꺼집니다
  • false: 기본 제공 읽기 전용 집합 외의 모든 명령에 대해 권한 프롬프트가 표시됩니다
• 기본값: true

{
  "useAutoModeDuringPlan": false
}

permissions.allow

Claude Code가 묻지 않고 승인하는 도구 사용을 나열합니다. MCP 규칙에서 *는 mcp__github__get_*처럼 mcp__<server>__ 접두사 뒤의 도구 이름에만 사용할 수 있으며, 서버 이름에는 사용할 수 없습니다.

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

이 예시는 git diff를 승인하고 Claude Code가 묻지 않고 .zshrc를 읽을 수 있게 합니다.

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

Claude Code는 사용자가 해당 폴더의 워크스페이스 신뢰 대화 상자를 수락한 후에만 프로젝트의 .claude/settings.json에 있는 allow 규칙을 적용합니다.

권한 규칙 구문

권한 규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다. Claude Code는 deny 규칙을 먼저 평가한 다음 ask, 그다음 allow를 평가하며, 각 규칙의 구체성과 관계없이 처음 일치하는 규칙이 결정합니다. 권한 규칙 평가 순서를 참조하십시오.

각 행은 하나의 규칙 형태와 일치하는 대상을 보여 줍니다.

와일드카드 동작, Read, Edit, WebFetch, MCP, Agent 규칙의 도구별 패턴, Bash 패턴의 보안 제한 사항을 포함한 전체 규칙 구문은 권한 규칙 구문을 참조하십시오.

permissions.ask

acceptEdits 또는 bypassPermissions처럼 원래는 승인할 권한 모드에서도 확인을 요청하는 도구 사용을 나열합니다. dontAsk 모드에서는 Claude Code가 확인을 요청하는 대신 일치하는 도구 사용을 거부합니다.

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

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

permissions.deny

Claude Code가 차단하는 도구 사용을 나열합니다. API 키, 시크릿 또는 환경 값이 담긴 파일에 사용하십시오. Claude Code는 일치하는 파일을 파일 검색 및 검색 결과에서 제외하고, 해당 파일 읽기를 거부하며, 일치하는 경로에서 Edit 및 Write 도구를 차단합니다.

Read 및 Edit 거부 규칙은 Claude의 기본 제공 파일 도구, cat, head, tail, sed, tee처럼 Claude Code가 Bash에서 인식하는 파일 명령, 그리고 > file 및 < file 같은 Bash 리디렉션의 대상에 적용됩니다. grep -r pattern .처럼 파일 이름을 지정하지 않고 파일을 읽는 명령이나 임의의 하위 프로세스에는 적용되지 않으므로, OS 수준의 적용을 위해서는 샌드박스를 활성화하십시오.

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

이 예시는 .env 파일, secrets 디렉터리, 자격 증명 파일 읽기를 거부하고 curl 명령을 차단합니다.

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

도구 이름에는 glob 패턴을 사용할 수 있으므로 "*"는 모든 도구를, "mcp__*"는 모든 MCP 도구를 거부합니다. Claude Code는 Claude가 사용할 수 있는 다른 도구가 하나라도 남아 있는 한 EndConversation 도구에 대한 거부 규칙을 무시합니다. Bash 거부 규칙은 Claude가 작성한 그대로의 명령과 일치하므로 Bash(curl *)는 /usr/bin/curl 또는 sh -c 'curl …'을 막지 못합니다. Bash 규칙이 일치하지 않는 항목을 참조하십시오. 이 키는 deprecated된 ignorePatterns 구성을 대체합니다.

permissions.additionalDirectories

시작한 디렉터리 외부의 디렉터리를 추가 작업 디렉터리로 지정해 Claude에 파일 접근 권한을 부여합니다. 대부분의 .claude/ 구성은 이러한 디렉터리에서 검색되지 않습니다.

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

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

allow 규칙과 마찬가지로 프로젝트의 .claude/settings.json에 있는 항목은 사용자가 해당 폴더의 워크스페이스 신뢰 대화 상자를 수락한 후에만 적용됩니다.

permissions.blockReadsOutsideWorkingDirectories

bypassPermissions를 포함한 모든 권한 모드에서 Claude의 파일 도구가 작업 디렉터리 외부의 읽기를 거부하도록 합니다. Claude Code는 해당 경로에 대한 Read, Grep, Glob, LSP 호출을 거부하고, /add-dir로 디렉터리를 추가하도록 사용자에게 요청하라고 Claude에 알립니다. ~/.claude/ 아래의 스킬, 플러그인, 규칙, 에이전트, 명령, CLAUDE.md 메모리 파일처럼 Claude Code 자체에 필요한 파일은 계속 읽을 수 있습니다. Claude Code v2.1.257 이상이 필요합니다.

Claude Code는 셸 명령을 같은 방식으로 거부하지 않습니다.

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

디렉터리를 두 번 이상 변경하거나 서브셸을 실행하는 명령처럼 셸 파서가 추적할 수 없는 Bash 명령은 자동 모드 및 bypassPermissions 모드에서도 확인을 요청합니다. 이 프롬프트는 명령이 작업 디렉터리 외부의 경로를 지정하지 않는 경우에도 표시됩니다. 명령이 샌드박스에서 실행되고 샌드박스가 차단을 적용하는 경우에는 이 프롬프트가 적용되지 않습니다.

작업 디렉터리 외부에서 처음 읽기 전에 자동 모드가 표시하는 프롬프트에서 이러한 읽기를 차단하도록 선택하면 Claude Code도 여기에 true를 기록합니다.

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

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

--add-dir, /add-dir 또는 사용자나 관리형 설정의 additionalDirectories로 추가한 디렉터리는 차단 시 작업 디렉터리로 간주됩니다. 저장소 설정에서만 추가된 디렉터리는 간주되지 않습니다. 즉, .claude/settings.json에 있는 디렉터리와, git이 .claude/settings.local.json 파일을 추적되지 않는 파일로 보고하는 경우를 제외한 해당 파일의 디렉터리는 간주되지 않습니다. git 저장소가 아닌 디렉터리이거나 git이 해당 파일을 추적하는 경우 Claude Code는 .claude/settings.local.json을 저장소 설정으로 취급하므로, 계속 읽을 수 있게 하려는 디렉터리는 대신 사용자 설정에 넣으십시오.

autoMemoryDirectory가 프로젝트의 .claude/settings.json 또는 저장소에서 제공된 것으로 취급되는 .claude/settings.local.json에서 오는 경우, Claude Code는 해당 디렉터리에서 자동 메모리를 로드하지 않으며 해당 디렉터리에 저장하지도 않습니다.

차단을 해제하려면 이 키를 설정한 모든 설정 파일에서 키를 제거한 다음 새 세션을 시작하십시오.

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

샌드박싱이 켜져 있으면 차단이 샌드박스 명령에도 적용됩니다. Claude Code는 샌드박스 명령에 대해 홈 디렉터리와 사용자 파일을 보관하는 다른 루트(/Users, /home, /root, /Volumes, /mnt, /media, /run/media, /srv)에 대한 읽기 접근을 거부합니다. 그런 다음 작업 디렉터리, 세션에서 Claude Code가 생성하는 워크트리, 세션 임시 디렉터리, 스킬 및 플러그인처럼 명령에 필요한 ~/.claude의 일부를 다시 엽니다. 차단이 적용되는 동안 저장소 설정의 allowRead 및 allowWrite 항목은 간주되지 않습니다.

Claude Code가 세션 도중 진입한 워크트리를 포함하여 세션의 작업 디렉터리가 연결된 git worktree인 경우, 저장소의 공통 .git 디렉터리는 샌드박스 명령이 계속 읽고 쓸 수 있으므로 git이 해당 위치에서 계속 작동합니다.

다음 경우에는 차단이 샌드박스 명령에 적용되지 않지만 Claude의 파일 도구는 계속 차단을 적용합니다.

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

차단 상태에서 Claude Code는 git이 사용자의 ID와 설정을 유지하도록 전역 git 구성 파일을 샌드박스 명령에 다시 엽니다.

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

Claude Code는 각 파일을 개별적으로 판단합니다. 파일이 직접 또는 심볼릭 링크를 통해 샌드박스 명령이 쓸 수 있는 위치에 있으면 Claude Code는 해당 파일이 지정하는 파일을 다시 열지 않습니다.

Linux 및 WSL2에서는 심볼릭 링크인 구성 파일이 자체 경로에서 읽을 수 없는 상태로 남을 수 있으며, 이 경우 git은 해당 파일 없이 실행됩니다. ~/.git-credentials 및 $XDG_CONFIG_HOME/git/credentials는 계속 차단됩니다.

다시 열린 파일에 http.extraHeader 토큰 같은 시크릿이 있으면 해당 경로를 sandbox.filesystem.denyRead에 추가하십시오. 파일을 포함하는 denyRead 항목은 항상 이 재열기보다 우선합니다.

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"
  }
}

권한 규칙은 모든 모드 위에 적용됩니다. deny 규칙은 bypassPermissions를 포함한 모든 모드에서 차단합니다. 권한 모드를 참조하십시오. 클라우드 세션에서 Claude Code는 이 키의 값 중 acceptEdits, plan, default, auto만 따릅니다. VS Code 확장이 시작하는 대화의 경우 확장이 시작 권한 모드로 읽는 설정을 참조하십시오.

permissions.disableBypassPermissionsMode

누구도 bypassPermissions 모드로 진입하지 못하게 합니다. 그러면 Claude Code는 --dangerously-skip-permissions 플래그를 거부하고, 에이전트 정의의 permissionMode: bypassPermissions를 무시하므로 서브에이전트는 상위 세션의 권한 모드로 실행됩니다.

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

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

v2.1.223 이전에는 Claude Code가 bypass가 비활성화된 상태에서도 frontmatter 권한 모드를 적용했습니다.

skipAutoPermissionPrompt

기본 제공 기본값이 세션을 자동 모드로 시작할 때가 아니라, 사용자 자신의 설정이나 모드 선택기 등을 통해 사용자가 직접 처음 자동 모드로 진입할 때 Claude Code가 표시하는 자동 모드 설명 일회성 알림을 건너뜁니다. Claude Code는 해당 알림을 한 번 표시한 후 표시했다는 사실을 기록하므로, 이 키는 알림이 아직 표시되지 않은 경우에만 의미가 있습니다.

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

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

--dangerously-skip-permissions 또는 defaultMode: "bypassPermissions"로 인해 세션이 bypassPermissions 모드로 진입하기 전에 Claude Code가 표시하는 확인 대화 상자를 건너뜁니다. 해당 대화 상자를 한 번 수락하면 Claude Code가 사용자 설정의 이 키에 true를 기록합니다.

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

{
  "skipDangerousModePermissionPrompt": true
}

샌드박스 설정

Claude가 실행하는 명령을 파일시스템, 네트워크, 자격 증명으로부터 격리합니다. 샌드박싱 작동 방식 및 플랫폼 요구사항은 샌드박싱을 참조하십시오.

sandbox

샌드박싱을 사용하여 Claude가 실행하는 Bash 명령을 파일시스템 및 네트워크로부터 격리합니다. enabled로 샌드박스를 켜고, filesystem, network, credentials 하위 객체로 샌드박스된 명령이 접근할 수 있는 범위를 좁히거나 넓힙니다. 샌드박스는 macOS, Linux, WSL2에서 실행됩니다.

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

다음은 샌드박스를 켜고, 샌드박스된 명령에 대한 권한 프롬프트를 건너뛰고, docker를 샌드박스 외부에서 실행하고, 두 개의 추가 쓰기 경로를 열고, AWS 자격 증명 파일을 숨기고, GitHub 및 npm을 미리 허용합니다:

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

관리형 설정이 enabled 또는 failIfUnavailable과 같은 Boolean 키를 설정하면, 해당 값은 개발자가 설정한 모든 것을 재정의합니다. Claude Code는 세션이 로드하는 설정 범위 전체에서 배열 키를 병합하므로, 개발자는 항목을 추가할 수 있습니다. 관리형 전용 잠금은 개발자가 정책을 확대하지 못하도록 유지를 참조하십시오. 조직에 샌드박스를 요구하려면 관리형 설정으로 샌드박싱 적용을 참조하십시오.

sandbox.enabled

Bash 명령에 대해 샌드박싱을 켭니다. /sandbox 패널에서 모드를 선택하면, Claude Code는 현재 프로젝트의 .claude/settings.local.json에 이 키를 씁니다. 모든 프로젝트를 샌드박스하려면 ~/.claude/settings.json에 설정하십시오.

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

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

Linux 및 WSL2에서 샌드박스는 bubblewrap 및 socat이 필요합니다. Linux 및 WSL2 설정을 참조하십시오. 샌드박스를 시작할 수 없을 때, failIfUnavailable도 설정하지 않았다면 Claude Code는 명령을 샌드박스 없이 실행합니다.

sandbox.failIfUnavailable

sandbox.enabled가 true이지만 의존성이 누락되었거나 플랫폼이 지원되지 않아 샌드박스를 시작할 수 없을 때 Claude Code가 시작 시 오류로 종료되도록 합니다. 이 키가 없으면 Claude Code는 명령을 샌드박스 없이 실행합니다. 샌드박싱을 보안 관문으로 요구하는 관리형 배포에서 이 설정을 사용할 수 있습니다.

샌드박스가 지원하지 않는 플랫폼에서는 이 키가 켜져 있으면 Claude Code가 시작되지 않습니다. 관리형 설정으로 샌드박싱 적용을 참조하십시오.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: sandbox.enabled가 true이지만 샌드박스를 시작할 수 없을 때 Claude Code는 시작 시 오류로 종료됩니다.
  • false: 샌드박스를 시작할 수 없을 때 Claude Code는 명령을 샌드박스 없이 실행합니다.
• 기본값: false

다음은 모든 관리 대상 머신이 명령을 샌드박스하거나 시작을 거부하도록 합니다:

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

관리형 설정으로 샌드박싱 적용을 참조하십시오.

sandbox.autoAllowBashIfSandboxed

Claude Code가 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행하도록 합니다. 샌드박스에서 실행할 수 없는 명령은 여전히 일반 권한 흐름을 거치며, deny 규칙 및 Bash(git push *)와 같은 콘텐츠 범위 ask 규칙은 여전히 적용됩니다. 단순 Bash ask 규칙은 샌드박스된 명령에 대해 건너뜁니다. 이를 false로 설정하여 샌드박스된 명령도 일반 권한 흐름을 거치도록 하면, /sandbox 모드 탭에서 이를 일반 권한 모드라고 부릅니다.

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

다음은 샌드박스를 켜고 샌드박스된 명령을 일반 권한 흐름을 거치도록 합니다:

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

자동 허용 모드가 여전히 확인을 요청하는 경우와 플랜 모드에서의 동작은 자동 허용 모드를 참조하십시오.

sandbox.excludedCommands

Claude Code가 샌드박스 외부에서 실행하는 명령(예: 샌드박스에서 작동하지 않는 도구)을 지정합니다. 각 항목은 Bash(...) 권한 규칙의 콘텐츠와 동일한 구문을 사용합니다: 정확한 명령, docker *와 같은 접두사, 또는 와일드카드 패턴입니다. 와일드카드가 없는 패턴은 정확히 일치하는 경우에만 해당하므로, docker는 인수가 없는 docker에만 일치합니다.

항목은 Bash 호출에 포함된 모든 명령을 포함할 때만 해당 호출을 샌드박스 외부로 꺼내며, 일부 호출 형태는 그렇더라도 샌드박스된 상태로 유지됩니다. docker * 항목만으로는 npm ci && docker build .를 샌드박스 외부로 꺼내지 않습니다.

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

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

Claude Code는 Bash 호출이 다음과 같은 형태 중 하나를 가질 때 해당 호출을 샌드박스된 상태로 유지합니다(이 외에도 있습니다):

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

예를 들어, cd build && docker compose up은 docker * 항목 아래에서 샌드박스된 상태로 유지되며, cd 항목을 추가해도 변경되지 않습니다. git * 항목 아래에서 git clone <url> vendor/lib는 샌드박스 외부에서 실행되지만, git clone <url> ~/tools는 샌드박스된 상태로 유지됩니다. 클론은 대상 경로가 가리키는 곳이 어디든 실행 파일일 수도 있는 파일 트리 전체를 씁니다.

제외된 명령은 여전히 일반 권한 흐름을 거칩니다. 제외는 편의 기능이지 보안 경계가 아닙니다. 도구가 특정 위치에만 쓰기를 필요로 할 때는 filesystem.allowWrite를 사용하면 샌드박스된 상태를 유지할 수 있습니다.

샌드박스가 관리자 필수가 아닌 한, 세션이 로드하는 설정 범위의 항목은 하나의 목록으로 결합됩니다. 관리자 필수인 동안에는 Claude Code가 .claude/settings.json 및 .claude/settings.local.json의 항목을 무시하므로, 복제된 저장소가 명령을 샌드박스 외부로 꺼낼 수 없습니다. 관리형 설정, --settings, ~/.claude/settings.json의 항목은 여전히 적용되며, 이 목록에 대한 관리형 전용 잠금은 없습니다.

sandbox.allowUnsandboxedCommands

샌드박스가 명령을 차단한 후 Claude가 dangerouslyDisableSandbox 매개변수를 사용하여 샌드박스 외부에서 명령을 재시도하도록 합니다. false이면 Claude Code는 해당 매개변수를 무시합니다. 그러면 샌드박스가 실행 중인 동안 Claude가 실행하는 명령은 excludedCommands 항목과 일치하지 않는 한 샌드박스됩니다. /sandbox 재정의 탭은 해당 상태를 엄격한 샌드박스 모드로 표시합니다. 관리형 설정의 false는 해당 설정이 적용되는 개발자에 대해 엄격한 샌드박스 모드를 켭니다.

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

다음은 관리형 설정이 적용되는 모든 사람에 대해 엄격한 샌드박스 모드를 적용합니다:

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

관리형 설정 또는 --settings의 false는 샌드박스를 관리자 필수로도 만듭니다. 사용자 설정의 false는 프로젝트의 true보다 우선하지만 샌드박스를 관리자 필수로 만들지는 않습니다. 프로젝트 값보다 우선하려면 Claude Code v2.1.285 이상이 필요합니다.

샌드박스 없는 재시도를 누가 승인하는지는 권한 모드와 허용 규칙에 따라 다릅니다. 샌드박스 없는 재시도 탈출 해치를 참조하십시오.

! 셸 모드 프롬프트에서 직접 입력한 명령이 언제 샌드박스에서 실행되는지 확인하려면 엄격한 샌드박스 모드를 참조하십시오.

sandbox.filesystem

샌드박스된 명령이 읽고 쓸 수 있는 경로를 제어합니다. 기본적으로 작업 디렉터리, 사용자별 임시 디렉터리, --add-dir, /add-dir 또는 permissions.additionalDirectories로 추가한 디렉터리에 쓸 수 있으며, 자격 증명 파일을 포함한 파일시스템의 나머지 부분을 읽을 수 있습니다. 네 개의 경로 목록으로 범위를 좁히거나 넓히거나, disabled로 파일시스템 계층을 끕니다. 파일시스템 격리에서 기본 경계를 참조하십시오.

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

다음은 샌드박스된 명령이 빌드 디렉터리 및 kubeconfig에 쓸 수 있도록 하고 AWS 자격 증명 파일을 숨깁니다:

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

Claude Code는 OS 샌드박스 경계에서 이러한 목록을 적용하므로, kubectl, terraform, npm과 같이 샌드박스된 명령이 시작하는 모든 하위 프로세스에 적용됩니다. Claude Code는 권한 규칙을 동일한 목록에 추가합니다: Edit 허용 및 거부 규칙을 allowWrite 및 denyWrite에, Read 거부 규칙을 denyRead에, WebFetch(domain:...) 허용 및 거부 규칙을 network 도메인 목록에 추가합니다.

잠금이 적용되지 않는 한, Claude Code는 세션이 로드하는 설정 파일 전체에서 이러한 목록을 병합합니다. allowManagedReadPathsOnly는 allowRead를 관리형 설정의 항목으로만 제한하며, allowManagedDomainsOnly는 허용된 도메인에 대해 동일하게 수행합니다. 저장소 잠금은 저장소 설정 파일의 항목을 제외합니다.

샌드박싱 구성은 --setting-sources로 제외하는 소스를 다룹니다. 세션 중에 목록을 편집하면, Claude Code는 실행 중인 세션에 변경사항을 적용합니다.

샌드박스 경로 접두사

allowWrite, denyWrite, denyRead, allowRead, credentials.files의 경로는 접두사로 확인됩니다:

절대 경로의 //path 접두사도 작동합니다. 프로젝트 상대 확인을 기대하면서 단일 슬래시 /path를 사용하는 경우, ./path로 전환하십시오. 이 구문은 절대 경로에 //path를 사용하고 프로젝트 상대 경로에 /path를 사용하는 Read 및 Edit 권한 규칙과 다릅니다. 샌드박스 파일시스템 경로는 표준 규칙을 사용하므로 /tmp/build는 절대 경로입니다.

Claude Code는 디렉터리 경로에서 후행 슬래시를 제거하므로, ~/.aws 및 ~/.aws/는 동일한 디렉터리와 일치합니다. v2.1.224 이전에는 Claude Code가 후행 슬래시를 샌드박스에 전달했으며, Claude는 여전히 후행 슬래시로 작성된 denyRead 또는 denyWrite 항목 아래의 경로를 읽거나 쓸 수 있었습니다.

Claude Code는 또한 후행 /**를 제거하므로, ~/build/** 및 ~/build는 동일한 디렉터리를 다룹니다. *와 같은 와일드카드가 작동하는지 여부는 항목이 있는 목록과 플랫폼에 따라 다릅니다:

• allowWrite 및 denyWrite: macOS에서는 와일드카드가 작동합니다. Linux 및 WSL2에서는 샌드박스가 구체적인 경로를 마운트하므로, Claude Code는 후행 /**가 제거된 후 *, ? 또는 [를 포함하는 항목을 건너뛰며, 해당 항목은 효과가 없습니다. Claude Code는 Edit 권한 규칙의 경로를 이러한 목록에 추가하므로, 동일한 제한이 적용되며, /sandbox의 구성 탭은 와일드카드를 포함하는 Edit 및 Read 권한 규칙에 대해 경고합니다.
• denyRead 및 allowRead: 모든 플랫폼에서 와일드카드가 작동합니다. Linux 및 WSL2에서는 Claude Code가 읽기 항목을 일치하는 구체적인 경로로 확장하며, 쓰기 목록에 대해서는 이를 수행하지 않습니다.

중괄호는 이름에서 일반 문자로 일치하므로, ~/data/{keys,tokens}는 두 가지 대안이 아니라 이름이 문자 그대로 {keys,tokens}인 디렉터리를 다룹니다. ~/data/keys와 ~/data/tokens를 다루려면 각각을 별도의 항목으로 추가하십시오.

sandbox.filesystem.allowWrite

작업 디렉터리, 사용자별 임시 디렉터리, --add-dir, /add-dir 또는 permissions.additionalDirectories로 추가한 디렉터리 외에 샌드박스된 명령이 쓸 수 있는 경로를 추가합니다. kubectl 또는 빌드 도구와 같은 하위 프로세스가 프로젝트 외부에 쓰기를 필요로 할 때 사용하십시오.

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

다음은 빌드가 /tmp/build 아래에 쓸 수 있도록 하고 kubectl이 kubeconfig를 업데이트하도록 합니다:

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

Claude Code는 세션이 로드하는 설정 범위 전체에서 allowWrite 항목과 Edit(...) 허용 권한 규칙의 경로를 병합하며, permissions.blockReadsOutsideWorkingDirectories가 켜져 있는 동안 저장소 설정의 항목을 제외합니다. 저장소 잠금도 저장소의 항목을 제외할 수 있습니다. allowWrite 항목은 보호된 경로를 해제할 수 없습니다.

sandbox.filesystem.denyWrite

샌드박스된 명령이 특정 경로(다른 방식으로 쓰기 가능한 디렉터리 내의 경로 포함)에 쓰는 것을 차단합니다.

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

다음은 샌드박스된 명령이 시스템 구성을 변경하거나 바이너리를 설치하는 것을 방지합니다:

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

Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하고 Edit(...) 거부 권한 규칙의 경로를 추가합니다.

sandbox.filesystem.denyRead

샌드박스된 명령이 특정 경로(예: 기본 읽기 정책이 노출할 자격 증명 파일)를 읽는 것을 차단합니다. 자격 증명 파일을 보호하고 샌드박스 프록시를 통해 사용 가능하게 유지하려면 대신 sandbox.credentials를 참조하십시오.

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

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

Claude Code는 세션이 로드하는 모든 설정 범위에서 항목을 병합하고 Read(...) 거부 권한 규칙의 경로를 추가합니다. filesystem.disabled가 true이면, Claude Code는 이러한 항목을 적용하지 않습니다.

sandbox.filesystem.allowRead

denyRead가 차단하는 영역 내의 특정 경로에 대해 읽기를 다시 열어서 작업 공간 전용 읽기 액세스를 구축합니다. 정확한 또는 와일드카드 denyRead 항목은 더 광범위한 allowRead 내에서 차단된 상태로 유지되며, 겹침 표에서 보여줍니다. 와일드카드 denyRead 항목(예: ~/**/.env)이 디렉터리와 일치할 때, Claude Code는 해당 내용의 읽기도 차단합니다. v2.1.236 이전의 macOS에서는 Claude Code가 더 광범위한 allowRead 항목이 적용되는 곳에서 와일드카드 denyRead 항목이 일치하는 경로를 다시 열었으며, 일치하는 디렉터리의 내용을 읽을 수 있게 남겨두었습니다.

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

다음은 프로젝트 자체를 제외한 홈 디렉터리의 읽기를 차단합니다:

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

Claude Code는 프로젝트 설정에서 . 항목을 프로젝트 루트로, 사용자 설정에서 ~/.claude로 확인합니다. Claude Code는 allowManagedReadPathsOnly가 설정되지 않으면 세션이 로드하는 설정 파일 전체에서 항목을 병합하며, permissions.blockReadsOutsideWorkingDirectories가 켜져 있는 동안 저장소 설정의 항목을 제외합니다. 저장소 잠금도 저장소의 항목을 제외할 수 있습니다.

sandbox.filesystem.allowManagedReadPathsOnly

관리형 설정에서 오는 allowRead 항목만 인정하므로, 개발자가 조직이 차단한 경로에 대한 읽기 액세스를 다시 열 수 없습니다. Claude Code는 여전히 세션이 로드하는 모든 설정 범위에서 denyRead 항목을 병합합니다.

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

다음은 홈 디렉터리의 읽기를 차단하고, ~/work를 다시 열고, 개발자가 다른 것을 다시 열지 못하도록 합니다:

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

개발자가 정책을 확대하지 못하도록 유지를 참조하십시오.

sandbox.filesystem.disabled

네트워크 격리를 유지하면서 파일시스템 격리를 건너뜁니다. 샌드박스된 명령은 호스트 파일시스템에 대한 무제한 읽기 및 쓰기 액세스를 얻으며, 해당 네트워크 송신은 network.allowedDomains로 제한됩니다. 명령이 쓰는 것이 아니라 연결하는 위치를 제어하기 위해 샌드박스할 때 사용하십시오. Claude Code v2.1.216 이상이 필요합니다.

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

다음은 파일시스템을 열고 네트워크 송신을 GitHub 및 npm으로 제한합니다:

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

계층이 꺼지면, Claude Code는 denyRead 또는 credentials.files deny 항목을 적용하지 않으며, credentials.envVars 항목 및 적용된 mask 항목은 계속 작동합니다. autoAllowBashIfSandboxed는 여전히 기본값이 true이므로, 계속 확인을 요청하게 하려면 false로 설정하십시오. 파일시스템 격리 비활성화에서 이를 설정할 수 있는 전체 소스 목록과 격리가 꺼졌을 때 변경되는 사항을 참조하십시오. Claude Code v2.1.216 이상이 필요합니다.

sandbox.ignoreViolations

명령이 시작 시 /etc/hosts를 확인하는 도구와 같이 프로브되고 거부될 것으로 예상되는 경로에 대한 샌드박스 위반 보고를 침묵시키므로, 해당 거부가 위반으로 표시되거나 Claude가 보는 것에 나타나지 않습니다. 샌드박스는 여전히 액세스를 차단합니다. 보고만 억제됩니다. 키는 명령과 일치하는 부분 문자열이며, *는 모든 명령과 일치하고, 값은 해당 명령에 대해 무시할 위반의 부분 문자열(예: 파일시스템 경로)입니다.

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

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

sandbox.enableWeakerNestedSandbox

Linux 샌드박스를 권한 없는 Docker 컨테이너 내부에서 실행하며, bubblewrap이 새로운 /proc을 마운트할 수 없습니다. 대신 내부 샌드박스는 컨테이너의 기존 /proc을 바인드 마운트하며, 이는 새로운 마운트가 숨길 프로세스 정보를 노출합니다. 이는 보안을 감소시킵니다. 외부 컨테이너가 이미 필요한 격리를 제공할 때만 사용하십시오.

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

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

Linux 및 WSL2만 해당합니다. Bubblewrap이 컨테이너 내부에서 시작되지 않음을 참조하십시오.

sandbox.enableWeakerNetworkIsolation

샌드박스된 명령이 macOS에서 시스템 TLS 신뢰 서비스 com.apple.trustd.agent에 도달하도록 합니다. gh, gcloud, terraform과 같은 Go 기반 도구는 network.httpProxyPort를 MITM 프록시 및 사용자 정의 CA와 함께 사용할 때 TLS 인증서를 확인하기 위해 필요합니다. 이는 신뢰 서비스를 통한 잠재적 데이터 유출 경로를 열어서 보안을 감소시킵니다.

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

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

MITM 프록시를 사용하지 않으면, 대신 실패하는 도구를 excludedCommands에 나열하십시오. Go 기반 CLI가 macOS에서 TLS 검증에 실패함을 참조하십시오.

sandbox.allowAppleEvents

샌드박스된 명령이 macOS에서 Apple Events를 보내도록 합니다. open, osascript, URL을 브라우저에서 여는 도구에 필요하며, 없으면 오류 -600으로 실패합니다. 이는 코드 실행 격리를 제거합니다: 샌드박스된 명령은 사용자 프롬프트 없이 다른 애플리케이션을 샌드박스 없이 시작할 수 있으며, Terminal과 같은 실행 중인 애플리케이션에 AppleScript 명령을 보낼 수 있습니다. 이는 앱별 macOS 자동화 동의 프롬프트(TCC)를 따릅니다.

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

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

격리를 유지하면서 그러한 도구 중 하나를 실행하려면, 대신 excludedCommands에 추가하십시오. macOS의 Apple Events를 참조하십시오.

sandbox.allowNestedUserNamespaces

Linux와 WSL2에서 샌드박스된 명령이 사용자 네임스페이스를 생성할 수 있도록 합니다. Chromium과 Electron 자체 샌드박스, 중첩된 bubblewrap, unshare에 필요합니다. 이 키를 true로 설정하면 보안 경계가 꺼집니다. 샌드박스된 명령의 코드가 샌드박스 외부에서 실행될 수 있습니다. 루트리스 Podman이나 Buildah의 경우, 샌드박스가 다른 방식으로도 이들을 막기 때문에 대신 excludedCommands를 사용하십시오. Claude Code v2.1.305 이상이 필요합니다.

• 범위: 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
  }
}

이 키가 켜져 있으면 보호된 경로와 credentials.files 항목을 포함한 샌드박스의 어떤 제한에도 악의적인 명령을 막는 역할을 기대하지 마십시오. 자동 허용 모드에서는 그러한 명령이 권한 프롬프트 없이 실행될 수 있습니다. 조직에 보안 팀이 있다면 이 키를 켜기 전에 확인하십시오.

사용 중인 도구에 대한 해결 방법은 Linux의 샌드박스 안에서 Chromium 또는 루트리스 Podman이 실패하는 경우를 참조하십시오.

sandbox.ripgrep

Claude Code가 사용하는 ripgrep 바이너리 대신 자신의 ripgrep 바이너리를 샌드박스에 지정합니다. 예를 들어 플랫폼이 다르게 빌드된 rg를 필요로 할 때입니다.

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

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

sandbox.bwrapPath

샌드박스를 PATH 외부에 설치된 bubblewrap 바이너리(예: 에어갭 호스트의 벤더된 복사본)에 지정합니다. Claude Code는 시작 시 의존성 확인과 각 샌드박스된 명령을 래핑할 때 모두 이 경로를 사용합니다.

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

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

Linux 및 WSL2만 해당합니다.

sandbox.socatPath

샌드박스 네트워크 프록시를 PATH 외부에 설치된 socat 바이너리에 지정합니다.

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

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

Linux 및 WSL2만 해당합니다.

sandbox.credentials

샌드박스된 명령으로부터 보호할 자격 증명 파일 및 환경 변수를 선언합니다. 각 항목은 파일 path 또는 변수 name 및 mode를 지정합니다: deny는 자격 증명을 샌드박스 내부에 숨기고, mask는 샌드박스된 명령에 자리 표시자를 표시하면서 샌드박스 프록시가 아웃바운드 요청에서 실제 값을 대체합니다. Claude Code는 나열한 항목만 보호합니다. 기본 제공 자격 증명 거부 목록은 없습니다.

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

다음은 AWS 자격 증명 파일을 숨기고 샌드박스된 명령에서 GITHUB_TOKEN을 제거합니다:

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

deny 파일 보호는 파일시스템 계층의 일부이므로, 파일시스템 격리를 비활성화할 때 적용되지 않습니다. 환경 변수 보호는 여전히 적용됩니다.

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

관리형 sandbox.credentials 항목이 검증에 실패하면, Claude Code는 가능한 곳에서 자격 증명을 계속 보호합니다:

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

v2.1.191 이상에 적용됩니다. v2.1.221 이전에는 모든 잘못된 항목이 제거되었습니다. 필드별 처리를 포함하는 다른 관리형 키는 관리형 설정의 잘못된 항목을 참조하십시오.

sandbox.credentials.files

자격 증명 파일 또는 디렉터리를 샌드박스된 명령으로부터 보호합니다. "mode": "deny"를 사용하면, Claude Code는 샌드박스 내부에서 해당 경로의 읽기를 차단하며, 이는 sandbox.filesystem.denyRead와 동일한 읽기 차단입니다. "mode": "mask"를 사용하면, Linux 및 WSL2의 샌드박스된 명령은 파일의 센티널 복사본을 읽고, 샌드박스 프록시는 해당 항목의 injectHosts에 대한 아웃바운드 요청에서 실제 값을 대체합니다. macOS에서는 대신 파일을 샌드박스 내부에서 읽을 수 없습니다. "mode": "mask"는 Claude Code v2.1.221 이상이 필요합니다.

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

다음은 AWS 자격 증명 파일을 숨기고 gh 호스트 파일을 마스크하며, api.github.com에 대한 요청에서만 실제 값을 대체합니다:

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

경로는 sandbox.filesystem.* 설정과 동일한 접두사를 사용하며, Claude Code는 세션이 로드하는 모든 설정 범위에서 배열을 병합합니다. 자격 증명 보호는 --setting-sources로 제외하는 소스에서 여전히 적용되는 것을 다룹니다. mask 항목은 Claude Code v2.1.221 이상이 필요합니다.

mask 대체는 샌드박스 프록시를 통해서만 실행되므로, sandbox.network.tlsTerminate 또는 일반 HTTP 테스트 네트워크의 경우 allowPlaintextInject를 설정하십시오. mask는 단일 파일에 적용되므로, 각 자격 증명 파일을 개별적으로 나열하십시오. Claude Code는 deny 항목의 mask 필드를 수용하지만 무시합니다. 자격 증명 마스크는 어떤 설정 소스가 인정되는지를 다루고, 자격 증명 파일 마스크는 항목이 deny로 돌아가는 시기를 다룹니다.

파일용 마스크 필드

mask 항목은 이러한 선택적 필드를 수용합니다. extract 또는 decode 없이는 Claude Code가 전체 파일 콘텐츠를 하나의 센티널로 대체합니다. 파일시스템 격리가 켜진 macOS에서는 Claude Code가 extract 또는 decode가 실행되기 전에 mask 항목을 deny로 적용합니다. 자격 증명 파일 마스크를 참조하십시오.

다음은 gh 호스트 파일의 oauth_token 값만 마스크하고, 파일에 있는 해당 값의 다른 모든 복사본을 대체하고, 패턴이 아무것도 일치하지 않으면 파일을 읽을 수 없게 만들고, 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

환경 변수를 샌드박스된 명령으로부터 보호합니다. "mode": "deny"를 사용하면, Claude Code는 샌드박스된 명령의 환경에서 변수를 제거합니다. "mode": "mask"를 사용하면, 샌드박스된 명령은 세션별 센티널 값을 보고, 샌드박스 프록시는 해당 항목의 injectHosts에 대한 아웃바운드 요청에서 실제 값을 대체하므로, gh 및 npm과 같은 도구는 실제 자격 증명을 보유하지 않고도 계속 인증합니다.

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

다음은 샌드박스된 명령에서 NPM_TOKEN을 제거하고 GITHUB_TOKEN을 마스크하며, api.github.com에 대한 요청에서만 실제 값을 대체합니다:

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

name은 문자 또는 밑줄로 시작해야 하며 문자, 숫자, 밑줄만 포함해야 합니다. Claude Code는 세션이 로드하는 모든 설정 범위에서 배열을 병합하고, 동일한 변수가 두 모드로 나타날 때 deny를 적용합니다. 자격 증명 보호는 --setting-sources로 제외하는 소스에서 여전히 적용되는 것을 다룹니다.

mask 대체는 샌드박스 프록시를 통해서만 실행되므로, sandbox.network.tlsTerminate 또는 일반 HTTP 테스트 네트워크의 경우 allowPlaintextInject를 설정하십시오. 자격 증명 마스크를 참조하십시오. Claude Code는 deny 항목의 mask 필드를 수용하지만 무시합니다.

환경 변수용 마스크 필드

mask 항목은 이러한 선택적 필드를 수용합니다. extract 또는 decode 없이는 Claude Code가 전체 값을 하나의 센티널로 대체합니다. extract와 decode는 동일한 항목에서 함께 사용할 수 없습니다.

다음은 DATABASE_URL 내부의 비밀번호만 마스크하고, 패턴이 아무것도 일치하지 않으면 변수를 설정 해제하고, SERVICE_JWT의 JWT를 마스크하면서 api_key를 제외한 모든 클레임을 읽을 수 있게 유지합니다:

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

sandbox.credentials.allowPlaintextInject

TLS 종료 HTTPS뿐만 아니라 일반 HTTP 요청에서도 mask 대체를 허용합니다. 일반 HTTP에서는 업스트림 신원이 검증되지 않으며 자격 증명이 평문으로 전송되므로, 신뢰할 수 있는 테스트 네트워크 외부에서는 이를 끈 상태로 두십시오.

• 범위: User or managed
• 유형: Boolean
  • true: Claude Code는 TLS 종료 HTTPS뿐만 아니라 일반 HTTP 요청에서도 mask 대체를 허용합니다.
  • false: Claude Code는 TLS 종료 HTTPS에서만 mask 대체를 허용합니다.
• 기본값: false

{
  "sandbox": {
    "credentials": {
      "allowPlaintextInject": true
    }
  }
}

sandbox.credentials.awsPairs

자격 증명이 비표준 이름의 변수에 있을 때, SigV4 재서명을 위해 하나의 AWS 자격 증명을 구성하는 마스크된 환경 변수를 그룹화합니다. Claude Code는 전체 값을 마스크할 때 기존 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN 트리오를 자동으로 연결하므로, 다른 이름에 대해서만 이 키가 필요합니다. Claude Code v2.1.224 이상이 필요합니다.

• 범위: User or managed
• 유형: 각각 accessKeyIdVar, secretAccessKeyVar, 선택적 sessionTokenVar를 포함하는 객체의 배열이며, sandbox.credentials.envVars 항목을 지정합니다.
• 기본값: 설정되지 않음. 기존 트리오만 쌍을 이룹니다.

다음은 세 개의 사용자 정의 이름 변수를 재서명을 위한 하나의 AWS 자격 증명으로 연결합니다:

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

각 명명된 변수는 extract 또는 decode가 없는 sandbox.credentials.envVars의 전체 값 mask 항목이어야 하며, 모든 쌍에서 하나의 슬롯만 채울 수 있습니다. 다음 규칙도 적용됩니다:

• 프록시는 액세스 키 ID 항목의 injectHosts에 나열된 호스트에 대한 요청을 재서명합니다.
• sessionTokenVar가 설정되면, 프록시는 재서명된 요청에서 실제 토큰을 x-amz-security-token으로 전송합니다.
• 쌍에 기존 변수 중 하나라도 지정하면 자동 쌍 연결이 대체됩니다.

sandbox.credentials.sigv4

샌드박스 프록시가 재서명할 수 없는 AWS 요청 형식으로 수행할 작업을 선택합니다: streaming은 aws-chunked 스트리밍 업로드, presigned는 사전 서명된 URL, sigv4a는 SigV4A 비대칭 서명입니다. 이는 마스크된 쌍의 자리 표시자 액세스 키 ID로 서명된 요청에만 적용됩니다. Claude Code v2.1.224 이상이 필요합니다.

• 범위: User or managed
• 유형: streaming, presigned, sigv4a를 포함하는 객체이며, 각각 다음 중 하나입니다:
  • "deny": 프록시가 요청을 실패시킵니다.
  • "passthrough": 프록시는 마스크된 자리 표시자로 서명된 요청을 전달하므로, 도구는 AWS의 자체 거부를 받습니다.
• 기본값: 설정되지 않음. 모든 형식이 "deny"입니다.

다음은 스트리밍 업로드를 프록시에서 실패시키는 대신 전달합니다:

{
  "sandbox": {
    "credentials": {
      "sigv4": {
        "streaming": "passthrough"
      }
    }
  }
}

deny를 사용하면, 프록시가 요청을 실패시킵니다. passthrough를 사용하면, 프록시는 마스크된 자리 표시자에서 계산된 서명으로 요청을 전달하므로, AWS가 거부하고 호출 도구는 프록시 오류 대신 AWS의 자체 응답을 받습니다.

sandbox.network

샌드박스된 명령이 도달할 수 있는 호스트, 포트, 소켓을 제어합니다. 샌드박스는 아웃바운드 트래픽을 이러한 목록을 적용하는 프록시를 통해 라우팅합니다. 네트워크 격리에서 프록시가 결정하는 방식 및 확인을 요청하는 시기를 참조하십시오.

• 범위: Any file. strictAllowlist, allowManagedDomainsOnly, tlsTerminate는 각 항목에 설명된 대로 더 적은 소스에서 읽습니다.
• 유형: 아래 하위 키를 포함하는 객체
• 기본값: 설정되지 않음. 미리 허용된 도메인이 없으며, 권한 모드가 각 새 호스트에 대해 일어나는 일을 결정합니다.

다음은 GitHub 및 npm을 미리 허용하고, uploads.github.com을 차단하고, 명령이 localhost에 바인드되도록 합니다:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

Claude Code는 배열 하위 키를 설정 범위 전체에서 병합하므로, 저장소 잠금이 적용되지 않는 한 프로젝트는 사용자 목록에 도메인을 추가할 수 있습니다. WebFetch(domain:...) 허용 및 거부 권한 규칙은 동일한 허용 및 거부 목록에 추가됩니다.

sandbox.network.allowUnixSockets

macOS에서 샌드박스된 명령이 연결할 수 있는 Unix 소켓 경로를 나열합니다. Claude Code는 seccomp 필터가 소켓 경로를 검사할 수 없는 Linux 및 WSL2에서 이 목록을 무시합니다. 해당 플랫폼에서는 대신 allowAllUnixSockets를 사용하십시오.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 각각 소켓 경로인 문자열의 배열
• 기본값: 설정되지 않음. macOS 샌드박스는 모든 Unix 소켓을 차단합니다.

{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}

소켓 경로는 광범위한 액세스를 부여할 수 있습니다: 예를 들어 /var/run/docker.sock을 허용하면, 샌드박스된 명령이 Docker 데몬을 제어할 수 있습니다. 보안 제한을 참조하십시오.

sandbox.network.allowAllUnixSockets

샌드박스된 명령이 모든 Unix 소켓에 연결하도록 합니다. Linux 및 WSL2에서 샌드박스의 seccomp 필터는 socket(AF_UNIX, ...) 호출을 차단하므로, 이는 해당 플랫폼에서 Unix 소켓을 허용하는 유일한 방법입니다. 필터가 누락된 경우(/sandbox가 의존성 탭에서 보고함) 샌드박스는 Unix 소켓 호출을 차단하지 않습니다. Linux 및 WSL2 설정에서 필터가 어디에서 오는지 참조하십시오.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: 샌드박스 처리된 명령이 모든 Unix 소켓에 연결할 수 있습니다. Linux와 WSL2에서는 AF_VSOCK 주소 패밀리인 VM 소켓에도 연결할 수 있습니다
  • false: 샌드박스가 Unix 소켓 연결을 차단합니다. macOS에서는 allowUnixSockets의 경로를 제외하고, Linux와 WSL2에서는 seccomp 필터가 있는 경우 이를 통해 차단합니다
• 기본값: false

{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}

WSL2에서 true는 또한 cmd.exe 및 powershell.exe와 같은 Windows 바이너리를 시작하는 interop 소켓을 다시 엽니다.

sandbox.network.allowLocalBinding

macOS의 샌드박스된 명령이 네트워크 포트에서 수신 대기(예: 개발 서버 시작)하고 localhost의 모든 포트에 연결하도록 합니다. 루프백이 아닌 주소에서 수신 대기하는 명령은 다른 머신의 연결을 수락합니다. 이 키는 각 샌드박스된 명령이 자체 루프백 인터페이스를 가지는 Linux 및 WSL2에서는 효과가 없습니다. Linux 또는 WSL2에서 호스트의 서버에 도달하려면 명령이 localhost의 서버에 도달하지 못함을 참조하십시오.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: Boolean
  • true: macOS의 샌드박스된 명령은 모든 로컬 주소에서 수신 대기하고 localhost의 모든 포트에 연결할 수 있습니다.
  • false: macOS의 샌드박스된 명령은 포트에서 수신 대기하거나 localhost의 서버에 직접 연결할 수 없습니다.
• 기본값: false

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

sandbox.network.allowMachLookup

macOS 샌드박스가 조회할 수 있는 추가 XPC 및 Mach 서비스 이름을 나열합니다. iOS 시뮬레이터 또는 Playwright와 같이 XPC를 통해 통신하는 도구는 여기에 서비스를 나열해야 합니다.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음
• 유형: 각각 서비스 이름인 문자열의 배열. 단일 후행 *는 접두사와 일치하고, "*" 단독으로는 모든 서비스와 일치합니다.
• 기본값: 설정되지 않음

다음은 com.apple.coresimulator. 접두사 아래의 모든 서비스를 허용합니다:

{
  "sandbox": {
    "network": {
      "allowMachLookup": ["com.apple.coresimulator.*"]
    }
  }
}

sandbox.network.allowedDomains

샌드박스된 명령의 아웃바운드 트래픽에 대해 도메인을 미리 허용하므로, 샌드박스가 해당 도메인에 대해 확인을 요청하지 않습니다. *.example.com과 같은 와일드카드는 하위 도메인과 일치하며, 선택적 :port 접미사는 항목을 하나의 포트로 제한합니다. 포트 없는 항목은 모든 포트와 일치합니다.

• 범위: Any file, 프로젝트 및 로컬 설정에 대한 제한 있음. allowManagedDomainsOnly가 설정된 경우 관리형 설정만 해당합니다.
• 유형: 각각 도메인, 와일드카드 패턴, 또는 IP 리터럴이며, 선택적 :port 접미사를 포함하는 문자열의 배열
• 기본값: 설정되지 않음. 권한 모드가 각 새 호스트에 대해 일어나는 일을 결정합니다.

다음은 모든 포트의 GitHub, 모든 npm 하위 도메인, 포트 443에서만 하나의 API 호스트를 미리 허용합니다:

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"]
    }
  }
}

IPv6 리터럴은 괄호로 묶어 작성하며, 선택적으로 포트를 포함합니다: "[::1]"은 모든 포트를 허용하고 "[::1]:443"은 하나의 포트를 허용합니다. 괄호로 묶인 형식은 Claude Code v2.1.229 이상이 필요합니다. 도메인 목록의 IPv6 주소를 참조하십시오.

sandbox.network.deniedDomains

샌드박스된 명령의 아웃바운드 트래픽에 대해 도메인을 차단하며, allowedDomains와 동일한 와일드카드, 포트, IPv6 구문을 사용합니다. 거부된 도메인은 allowedDomains 항목도 일치하더라도 차단된 상태로 유지됩니다.

• 범위: Any file
• 유형: 각각 도메인, 와일드카드 패턴, 또는 IP 리터럴이며, 선택적 :port 접미사를 포함하는 문자열의 배열
• 기본값: 설정되지 않음

{
  "sandbox": {
    "network": {
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}

Claude Code는 allowManagedDomainsOnly가 설정되어도 세션이 로드하는 모든 설정 소스에서 이 목록을 병합하므로, 개발자는 항상 거부 목록을 강화할 수 있습니다. IPv6 리터럴은 도메인 목록의 IPv6 주소를 참조하십시오.

정규화된 도메인 이름을 표시하는 후행 점으로 작성된 항목(예: example.com.)은 example.com과 동일한 연결을 차단합니다.

sandbox.network.strictAllowlist

승인을 요청하는 대신 허용 목록 외부의 호스트에 대한 샌드박스된 명령의 액세스를 거부합니다. 허용 목록은 allowedDomains와 WebFetch(domain:...) 허용 규칙의 도메인을 합친 것이거나, allowManagedDomainsOnly가 설정되면 관리형 설정 항목만입니다. 관리자 필수 샌드박스 없이 적용되는 잠금은 저장소의 항목을 다룹니다. Claude Code v2.1.219 이상이 필요합니다.

• 범위: User or managed. 저장소는 이 설정을 켜거나 끌 수 없습니다.
• 유형: Boolean
  • true: Claude Code는 허용 목록 외부의 호스트에 대한 샌드박스된 명령의 액세스를 거부합니다.
  • false: 다른 신뢰할 수 있는 설정 파일이 true를 설정하지 않는 한, Claude Code는 허용 목록 외부의 호스트를 즉시 거부하는 대신 권한 모드에 따라 결정합니다: 자동 모드에서는 명령의 명령별 허용된 도메인에 대해 호스트를 확인하고, dontAsk 모드에서는 거부하고, bypassPermissions 모드 및 우회가 가능한 대화형 터미널 플랜 모드 세션에서는 허용하며, 그 외에는 사용자에게 묻습니다.
• 기본값: false

{
  "sandbox": {
    "network": {
      "strictAllowlist": true
    }
  }
}

Claude Code는 샌드박스된 명령에만 이를 적용합니다. WebFetch와 같은 프로세스 내 도구는 여전히 권한 규칙을 따릅니다. 인정된 소스 중 하나라도 true로 설정하면, 이는 켜진 상태로 유지됩니다. 네트워크 격리를 참조하십시오. Claude Code v2.1.219 이상이 필요합니다.

sandbox.network.allowManagedDomainsOnly

네트워크 허용 목록을 관리형 설정이 정의하는 것으로 잠급니다. 그러면 Claude Code는 관리형 설정의 allowedDomains 및 WebFetch(domain:...) 허용 규칙만 인정하고, 사용자, 프로젝트, 로컬, --settings 설정의 도메인을 무시하고, 허용되지 않은 도메인을 확인을 요청하는 대신 자동으로 차단합니다.

• 범위: Managed
• 유형: Boolean
  • true: Claude Code는 관리형 설정의 allowedDomains 및 WebFetch(domain:...) 허용 규칙만 인정하고 허용되지 않은 도메인을 확인을 요청하는 대신 차단합니다.
  • false: 다른 설정 파일의 도메인이 허용 목록에 병합될 수 있습니다.
• 기본값: false

다음은 허용 목록을 GitHub 및 npm으로 잠그고 개발자가 추가하는 도메인을 무시합니다:

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

키가 true인 동안 샌드박스는 관리자 필수이며, 관리형 설정만 프록시 포트를 설정할 수 있습니다.

거부된 도메인은 여전히 세션이 로드하는 모든 소스에서 병합됩니다. 개발자가 정책을 확대하지 못하도록 유지를 참조하십시오.

sandbox.network.httpProxyPort

Claude Code가 실행하는 프록시 대신 자체 HTTP 프록시를 샌드박스에 지정합니다. 조직은 HTTPS 트래픽을 검사하거나, 자체 필터링 규칙을 적용하거나, 요청을 로그에 기록하기 위해 이를 수행합니다. 해당 프록시가 필터링을 맡으며, Claude Code는 그곳으로 전송되는 트래픽에 도메인 목록과 네트워크 확인 요청을 더 이상 적용하지 않습니다. 설정되지 않으면, Claude Code는 HTTP 트래픽에 대해 자체 프록시를 시작합니다.

• 범위: Any file. 단, 다른 샌드박스 설정이 포트를 설정할 수 있는 파일을 제한하는 경우는 예외입니다
• 유형: 숫자, 로컬 TCP 포트
• 기본값: 설정되지 않음. Claude Code는 자체 프록시를 실행합니다.

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080
    }
  }
}

프록시가 SOCKS 트래픽도 전달해야 하면 socksProxyPort도 설정하십시오. 둘 중 하나만 설정되면, Claude Code는 여전히 다른 프로토콜에 대해 자체 프록시를 실행합니다. 사용자 정의 프록시 구성을 참조하십시오.

sandbox.network.socksProxyPort

Claude Code가 실행하는 프록시 대신 자체 SOCKS5 프록시를 샌드박스에 지정합니다. 해당 프록시가 필터링을 맡으며, Claude Code는 그곳으로 전송되는 트래픽에 도메인 목록과 네트워크 확인 요청을 더 이상 적용하지 않습니다. 설정되지 않으면, Claude Code는 SOCKS 트래픽에 대해 자체 프록시를 시작합니다.

• 범위: Any file. 단, 다른 샌드박스 설정이 포트를 설정할 수 있는 파일을 제한하는 경우는 예외입니다
• 유형: 숫자, 로컬 TCP 포트
• 기본값: 설정되지 않음. Claude Code는 자체 프록시를 실행합니다.

{
  "sandbox": {
    "network": {
      "socksProxyPort": 8081
    }
  }
}

사용자 정의 프록시 구성을 참조하십시오.

sandbox.network.tlsTerminate

샌드박스 프록시가 TLS를 종료하도록 하여 HTTPS 요청의 콘텐츠를 읽을 수 있게 합니다. 이는 실험적 기능이며, mask 자격 증명 대체에 필요합니다. 세션용 임시 인증 기관을 생성하려면 {}를 설정하고, 자체 인증 기관을 사용하려면 caCertPath 및 caKeyPath를 설정하십시오.

• 범위: User or managed. 저장소에서는 이 설정을 활성화하거나 인증 기관을 제공할 수 없습니다.
• 유형: 선택적 caCertPath 및 caKeyPath 문자열(각각 파일 경로)을 포함하는 객체
• 기본값: 설정되지 않음. 프록시는 TLS를 종료하거나 검사하지 않습니다.

{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}

둘 이상의 인정된 소스가 이를 설정하면, Claude Code는 가장 높은 우선순위 소스의 값을 사용합니다: 관리형 설정, 그 다음 --settings 플래그, 그 다음 사용자 설정입니다.

메모리 및 컨텍스트

Claude Code가 컨텍스트에 로드하는 내용, 압축 방식, 메모리 및 계획 저장 위치를 제어합니다. 컨텍스트 관리 및 메모리를 참조하십시오.

autoCompactEnabled

컨텍스트가 한계에 가까워질 때 Claude Code가 대화를 자동으로 압축하도록 합니다. /config에 자동 압축으로 표시되며, 여기서 토글하면 이 키가 사용자 설정에 기록됩니다.

• 범위: 모든 파일
• 유형: 부울
  • true: 컨텍스트가 한계에 가까워질 때 Claude Code가 대화를 자동으로 압축합니다
  • false: Claude Code가 자동으로 압축하지 않습니다
• 기본값: true
• 세션별 재정의: DISABLE_AUTO_COMPACT는 한 세션 동안 자동 압축을 끕니다. 둘 중 하나가 끄면 다른 하나는 다시 켤 수 없습니다

{
  "autoCompactEnabled": false
}

자동 압축이 꺼져 있는 동안에도 수동 /compact 명령은 계속 작동합니다. 자동 압축을 끄면 유휴 압축도 함께 꺼집니다.

autoCompactWindow

Claude Code가 자동으로 압축하기 전에 컨텍스트 윈도우가 얼마나 찬지 설정합니다.

• 범위: 모든 파일
• 유형: 토큰 수, 100000에서 1000000 사이. Claude Code는 값을 모델의 컨텍스트 윈도우로 제한합니다. 모델 개요에 각 모델의 윈도우가 나열되어 있습니다
• 기본값: 설정되지 않음. Claude Code가 모델에 맞게 조정된 윈도우를 선택합니다
• 세션별 재정의: --autocompact는 한 세션 동안 이 키보다 우선하며, CLAUDE_CODE_AUTO_COMPACT_WINDOW는 둘 다보다 우선합니다. 단, Claude Code가 변수의 값을 무시하는 경우는 예외입니다

{
  "autoCompactWindow": 500000
}

/autocompact 명령은 현재 모델의 윈도우를 modelSettings 아래에 저장하며, 이 값은 해당 모델에 대해 같은 파일의 이 키보다 우선합니다. 자동 압축 윈도우 설정에서 명령, 플래그, 변수 및 설정이 어떻게 상호작용하는지 설명합니다.

autoMemoryDirectory

자동 메모리를 프로젝트별 기본값 대신 선택한 디렉토리에 저장합니다.

• 범위: 모든 파일
• 유형: 문자열, 절대 경로 또는 ~/ 접두사가 있는 디렉토리 경로
• 기본값: 설정되지 않음. Claude Code는 ~/.claude/projects/<project>/memory/를 사용합니다

{
  "autoMemoryDirectory": "~/my-memory-dir"
}

프로젝트 또는 로컬 설정에서 Claude Code는 훅과 동일한 워크스페이스 신뢰 규칙에 따라 이 키를 준수합니다. 복제된 저장소가 이러한 파일을 제공할 수 있기 때문입니다.

autoMemoryEnabled

자동 메모리를 켜거나 끕니다. false일 때 Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다. 세션 중에 /memory로 토글할 수도 있으며, 이는 이 키를 사용자 설정에 기록합니다.

• 범위: 모든 파일
• 유형: 부울
  • true: 설정되지 않은 것과 동일합니다. 자동 메모리는 --bare, 안전 모드 또는 CLAUDE_CODE_DISABLE_AUTO_MEMORY와 같이 이 키보다 우선하는 것이 세션을 끄지 않는 한 켜져 있습니다
  • false: Claude는 자동 메모리 디렉토리에서 읽거나 쓰지 않습니다
• 기본값: true
• 세션별 재정의: CLAUDE_CODE_DISABLE_AUTO_MEMORY는 한 세션 동안 이 키보다 어느 방향이든 우선합니다

{
  "autoMemoryEnabled": false
}

bashOutputMaxChars

성공한 Bash 또는 PowerShell 명령의 출력 중 Claude가 인라인으로 받는 문자 수를 설정합니다. 출력이 한계를 초과하면 Claude Code는 출력을 파일에 저장하고 Claude는 짧은 미리보기와 파일의 경로를 받습니다. 자세한 빌드 또는 전체 테스트 스위트 로그와 같은 명령 출력이 기본값을 자주 초과하고 Claude가 파일을 열지 않고 읽기를 원할 때 한계를 높입니다. Claude Code v2.1.261 이상이 필요합니다.

• 범위: 모든 파일
• 유형: 문자 수, 양의 정수. Claude Code는 값을 4000에서 128000 범위로 제한합니다
• 기본값: 설정되지 않음. Claude는 최대 30,000자를 인라인으로 받습니다

{
  "bashOutputMaxChars": 100000
}

이 키를 설정하면 Claude Code는 BASH_MAX_OUTPUT_LENGTH 환경 변수를 무시합니다.

claudeMd

CLAUDE.md 스타일 지침을 별도 파일을 배포하지 않고 조직 관리 메모리로 주입합니다. Claude Code는 텍스트를 사용자 및 프로젝트 CLAUDE.md 파일보다 먼저 관리되는 메모리 항목으로 로드합니다.

• 범위: 관리됨
• 유형: 문자열, CLAUDE.md 파일의 텍스트. 파일처럼 작성하되 Markdown을 포함하고 줄 바꿈을 \n으로 표기합니다
• 기본값: 설정되지 않음

이 예제는 두 가지 규칙을 짧은 Markdown 목록으로 배포합니다:

{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}

조직 전체 CLAUDE.md 배포를 참조하십시오.

claudeMdExcludes

Claude Code가 메모리를 로드할 때 특정 CLAUDE.md 파일을 건너뜁니다. 큰 모노레포에서 이를 사용하여 작업과 관련이 없는 다른 팀의 CLAUDE.md 파일을 건너뜁니다. 대규모 코드베이스 가이드의 관련 없는 CLAUDE.md 파일 제외에서 해당 경우를 설명합니다. 패턴은 절대 파일 경로와 일치합니다.

• 범위: 모든 파일
• 유형: 문자열 배열, 각각 glob 패턴 또는 절대 경로
• 기본값: 설정되지 않음. Claude Code는 찾은 모든 CLAUDE.md를 로드합니다

{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}

제외는 사용자, 프로젝트 및 로컬 메모리 파일에만 적용됩니다. 관리되는 정책 CLAUDE.md 파일은 제외할 수 없습니다.

env

모든 세션 및 Claude Code가 시작하는 서브프로세스에 대한 환경 변수를 설정합니다. 환경 변수 참조의 대부분의 변수를 여기에 넣을 수 있으며, 이것이 모든 세션에 적용하거나 팀에 배포하는 방법입니다. 프로젝트 및 로컬 설정은 일부 변수를 설정할 수 없습니다.

• 범위: 모든 파일
• 유형: 변수 이름을 문자열 값으로 매핑하는 객체
• 기본값: 설정되지 않음

이 예제는 자동 압축을 끄고 API 요청을 프록시를 통해 라우팅합니다:

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

env 값이 셸과 상호작용하는 방식

• 여기의 값은 셸에서 내보낸 동일한 변수를 덮어쓰며, 둘 이상의 설정 파일이 변수를 설정할 때 가장 높은 우선순위가 적용됩니다. Claude Code가 env에서 무시하는 변수는 프로젝트 및 로컬 설정의 예외를 나열합니다.
• Claude Desktop 앱 또는 자체 호스팅 환경 러너가 세션을 시작할 때, 빌드하는 시작 환경이 대신 우선합니다. Claude Code는 시작 환경이 이미 설정한 변수에 대해 설정 파일의 env 값을 무시합니다. 디버그 로그는 무시된 각 변수의 이름을 지정합니다.
• 셸 내보내기를 취소하려면 변수를 ""로 설정합니다. Claude Code는 공 값을 공급자 선택에 대해 설정되지 않은 것으로 취급하며, 서브프로세스는 공 값을 상속합니다.
• NO_COLOR 및 FORCE_COLOR는 여기에서 설정하면 서브프로세스에만 도달합니다. Claude Code 자체 인터페이스 색상을 변경하려면 claude를 시작하기 전에 셸에서 설정합니다.
• 여기의 값은 설정 파일의 일반 텍스트이며 Claude Code가 시작하는 모든 서브프로세스에 도달합니다. 회전하는 OTLP 베어러 토큰의 경우 otelHeadersHelper를 사용합니다. API 자격 증명의 경우 apiKeyHelper를 사용합니다.

Claude Code가 env 값을 적용하는 시기

• 사용자 설정, --settings 및 관리되는 설정에서: 시작 시 및 저장된 변경이 병합된 env를 변경할 때 실행 중인 세션에서.
• 프로젝트 및 로컬 설정에서: 워크스페이스를 신뢰한 후 또는 신뢰 대화를 표시하지 않는 -p 모드에서 시작할 때, 저장된 변경이 병합된 env를 변경할 때 다시.
• Claude Code가 모델 선택, 타임아웃 및 한계, 기능 토글과 같은 안전한 것으로 분류하는 변수: 프로젝트 및 로컬 설정이 설정할 수 없는 변수를 제외하고 모든 설정 파일에서 시작할 때.
• v2.1.246 이상에서 /cd로 세션을 이동한 후: 새 디렉토리의 프로젝트 및 로컬 env 값, 이전 디렉토리의 위에.

Claude Code가 env에서 무시하는 변수

• 프로젝트 및 로컬 설정은 체크아웃된 저장소가 제어하지 않아야 하는 변수를 설정할 수 없습니다. 대신 셸, 사용자 설정 또는 관리형 설정에서 설정합니다. Claude Code는 텔레메트리를 끄는 몇 가지 값을 제외하고 각각을 삭제하며, claude --debug로 볼 수 있는 경고를 기록합니다. 여기에는 다음이 포함됩니다:

  • Claude Code가 자신의 파일을 저장하거나 쓰는 위치를 선택하는 변수: CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR 및 HOME, TMPDIR, TMP, TEMP 및 XDG_* 계열과 같은 운영 체제 디렉토리 변수.

  • Claude Code가 시작하는 프로세스의 프로그램과 시스템 전체 구성을 선택하는 Windows 변수, 예: SystemRoot, ComSpec, ProgramData, LOCALAPPDATA, PATHEXT, PSModulePath 및 ProgramFiles 계열.

  • 세션 콘텐츠를 내보내는 변수: OTEL_LOG_RAW_API_BODIES 및 자세한 베타 추적 쌍 ENABLE_BETA_TRACING_DETAILED 및 BETA_TRACING_ENDPOINT.

  • OpenTelemetry 내보내기 변수는 텔레메트리를 켜거나, 어디로 갈지 선택하거나, 어떤 콘텐츠를 캡처할지 선택합니다:

    • CLAUDE_CODE_ENABLE_TELEMETRY, 향상된 텔레메트리 베타 쌍 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 및 ENABLE_ENHANCED_TELEMETRY_BETA
    • 내보내기 선택기 OTEL_LOGS_EXPORTER, OTEL_METRICS_EXPORTER 및 OTEL_TRACES_EXPORTER
    • 콘텐츠 변수 OTEL_LOG_USER_PROMPTS, OTEL_LOG_ASSISTANT_RESPONSES, OTEL_LOG_TOOL_CONTENT 및 OTEL_LOG_TOOL_DETAILS
    • OTEL_EXPORTER_OTLP_* 변수는 이름이 _ENDPOINT, _HEADERS, _PROTOCOL, _CERTIFICATE, _CLIENT_KEY 또는 _INSECURE로 끝나며, 일반 및 신호별 형식으로 OTEL_EXPORTER_OTLP_ENDPOINT 및 OTEL_EXPORTER_OTLP_METRICS_HEADERS와 같습니다
    • OTEL_EXPORTER_PROMETHEUS_HOST 및 OTEL_EXPORTER_PROMETHEUS_PORT

    이 값들만 프로젝트 및 로컬 설정에서 계속 적용됩니다. 왜냐하면 그들은 뭔가를 끄기 때문입니다: 세 개의 내보내기 선택기에 대해 none, 그리고 OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_CONTENT 및 OTEL_LOG_TOOL_DETAILS에 대해 0과 같은 끄기 값. 이러한 값은 사용자 설정의 동일한 변수를 재정의하지만 Claude Code를 시작하는 환경, --settings 파일 또는 관리되는 설정이 설정하는 것은 재정의하지 않습니다.

    프로젝트 또는 로컬 설정 파일이 이 그룹의 변수를 설정할 때 로컬 대화형 세션은 시작 시 공지를 표시합니다. /status 또는 claude doctor를 실행하여 Claude Code가 무시한 변수와 원격 측정을 끈 변수를 확인합니다. 둘 다 이름을 나열하며 값은 나열하지 않습니다. -p를 사용한 비대화형 실행 또는 Agent SDK 세션은 공지를 표시하지 않으므로 업그레이드 후 수집기가 여전히 데이터를 받는지 확인합니다. 그렇지 않으면 사용자 설정, 관리되는 설정, 작업의 환경 또는 --settings로 전달하는 파일에서 변수를 설정합니다.

    프로젝트 및 로컬 설정에서 이 그룹을 무시하려면 Claude Code v2.1.282 이상이 필요합니다.

  • Claude Code가 시작하거나 동기화하는 방식을 변경하는 변수, 예: CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR 및 CLAUDE_CODE_PLUGIN_SEED_DIR.

  • 화면 낭독기 모드 변수 CLAUDE_AX_SCREEN_READER 및 CLAUDE_AX_STARTUP_QUIET_MS와 같이 이름이 CLAUDE_AX_로 시작하는 기타 변수.

  • 응답하지 않은 대화 상자의 타이머를 설정하는 CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS.

  • 첨부 파일 처리를 끄는 CLAUDE_CODE_DISABLE_ATTACHMENTS.

  • Claude Code가 파일 및 디렉토리의 @ 멘션을 확장하지 않도록 하는 CLAUDE_CODE_DISABLE_FILE_MENTIONS.

  v2.1.251 이전에는 프로젝트 및 로컬 설정이 Claude Code가 파일을 쓰는 위치를 선택하거나 세션 콘텐츠를 내보내는 이 목록의 변수를 설정할 수도 있었습니다. HOME 및 XDG_CONFIG_HOME 제외. v2.1.290 이전에는 대화 상자 타이머 변수와 CLAUDE_CODE_DISABLE_ATTACHMENTS도 설정할 수 있었습니다.

• Claude Code의 호스팅 환경이 소유하는 ID 변수, 예: CLAUDE_CODE_REMOTE 및 CLAUDE_CODE_ACCOUNT_UUID는 모든 파일에서 무시됩니다.

• CLAUDE_CODE_MESSAGING_SOCKET 및 CLAUDE_CODE_MESSAGING_TOKEN는 Claude Code가 자체 내보내는 것이므로 모든 파일에서 무시됩니다. 소켓 변수를 무시하려면 Claude Code v2.1.224 이상이 필요하고, 토큰을 무시하려면 v2.1.228 이상이 필요합니다.

• CLAUDE_CODE_PROJECT_DIR_NAME는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. v2.1.234 이상이 필요합니다.

• CLAUDE_CODE_RESTRICTED는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.

• CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 변수는 Claude Code v2.1.283 이상이 필요합니다.

• CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT, CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT, CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT 및 CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다.

• CLAUDE_CODE_WARN_DISK_FREE_GIB 및 CLAUDE_CODE_WARN_MEMORY_FREE_GIB는 Claude Code가 시작 환경에서만 읽으므로 모든 파일에서 무시됩니다. 이 변수는 Claude Code v2.1.304 이상이 필요합니다.

fileCheckpointingEnabled

Claude Code가 각 편집 전에 파일을 스냅샷하여 /rewind가 파일을 복원할 수 있도록 합니다. /config에 **코드 되감기(체크포인트)**로 표시되며, 여기서 토글하면 이 키가 사용자 설정에 기록됩니다.

• 범위: 모든 파일
• 유형: 부울
  • true: Claude Code가 각 편집 전에 파일을 스냅샷하여 /rewind가 파일을 복원할 수 있습니다
  • false: Claude Code가 파일을 스냅샷하지 않으므로 /rewind가 파일을 복원할 수 없습니다
• 기본값: true
• 세션별 재정의: CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING는 한 세션 동안 체크포인팅을 끕니다. 둘 중 하나가 끄면 다른 하나는 다시 켤 수 없습니다

{
  "fileCheckpointingEnabled": false
}

-p 실행 또는 Agent SDK 세션에서 Claude Code는 이 키를 무시합니다. SDK는 enableFileCheckpointing 옵션으로 체크포인팅을 켜고, 베어 -p 실행은 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true가 필요합니다. Agent SDK의 파일 체크포인팅을 참조하십시오.

idleCompaction

유휴 압축은 사용자가 자리를 비운 긴 대화를 프롬프트 캐시가 만료되기 직전에 압축합니다. 그러면 다음 메시지는 전체 대화 대신 요약을 전송합니다. 돌아오면 대화에 Compacted while idle, before the prompt cache expired로 시작하는 줄이 표시됩니다.

유휴 압축은 다음 조건을 모두 충족하는 대화에 대해 기본적으로 켜져 있습니다:

• 세션: 대화형 터미널 세션에 있습니다
• 자동 압축: autoCompactEnabled가 켜져 있습니다
• 프롬프트 캐시: 대화가 1시간 프롬프트 캐시 TTL을 사용합니다
• 기능 플래그: Claude Code가 Anthropic에서 기능 플래그를 가져올 수 있습니다
• 크기: 대화의 컨텍스트가 토큰 임계값에 도달했습니다. 이 임계값은 기본값 200,000에서 변경할 수 있습니다
• 유휴 시간: 마지막 요청 이후 약 54분이 지났으며, 그 시점에 컴퓨터가 깨어 있습니다

유휴 압축을 끄려면 이 키를 false로 설정합니다.

• 범위: 모든 파일
• 유형: 부울
  • true: Claude Code가 조건을 충족하는 유휴 대화를 압축합니다
  • false: 세션이 유휴 상태인 동안 Claude Code가 압축하지 않습니다
• 기본값: true
• 세션별 재정의: DISABLE_AUTO_COMPACT는 자동 압축과 함께 유휴 압축도 끕니다

{
  "idleCompaction": false
}

세션 내에서 유휴 압축을 끄거나 켜려면 /config를 실행하고 유휴 압축 행을 변경합니다. 선택한 값은 사용자 설정에 저장되며 즉시 적용됩니다. 이 행은 Claude Code v2.1.302 이상이 필요합니다. 해당 버전을 실행 중인데 /config에 이 행이 표시되지 않으면 다음 원인을 확인합니다:

• 다른 설정 소스가 키를 설정함: 관리형 설정, --settings 플래그 또는 프로젝트나 로컬 설정 파일의 값이 사용자 설정을 재정의합니다. 대신 해당 소스에서 키를 변경합니다
• 기능 플래그를 사용할 수 없음: Claude Code가 Anthropic에서 기능 플래그를 가져올 수 없는 환경에서는 유휴 압축이 실행되지 않으므로 끌 대상이 없습니다

이 키는 Claude Code v2.1.290 이상이 필요합니다. 이 키를 무시하는 이전 버전에서는 유휴 압축을 중지하려면 autoCompactEnabled를 끕니다.

유휴 압축 임계값 변경

CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS를 대화의 컨텍스트가 유휴 압축 대상이 되기 위해 도달해야 하는 토큰 수로 설정합니다. 양의 정수를 사용합니다. 100000 미만의 값은 가장 낮은 임계값인 100000으로 올려집니다.

기본값에서는 200K 컨텍스트 윈도우의 대화가 200,000 토큰에 도달하기 전에 자동 압축됩니다. 이 예제는 해당 대화가 조건을 충족하도록 임계값을 150,000으로 낮춥니다:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

plansDirectory

Claude Code가 플랜 모드에서 작성하는 계획 파일을 저장할 위치를 선택합니다. Claude Code는 경로를 프로젝트 루트에 상대적으로 해석합니다.

• 범위: 모든 파일
• 유형: 문자열, 프로젝트 루트에 상대적인 경로
• 기본값: 설정되지 않음. Claude Code는 ~/.claude/plans를 사용합니다

{
  "plansDirectory": "./plans"
}

다음과 같은 경우 Claude Code는 설정한 디렉토리 대신 ~/.claude/plans에 계획을 저장합니다:

• 프로젝트 루트 외부: "../plans"처럼 경로가 프로젝트 루트 외부로 해석되는 경우.
• macOS, Linux 및 WSL에서의 백슬래시: Windows 스타일의 "docs\\plans"처럼 해석된 경로에 백슬래시가 포함된 경우. Windows에서도 작동하는 "docs/plans"로 작성합니다.

skillListingBudgetFraction

각 턴마다 Claude는 설명과 함께 스킬 목록을 보며, Claude Code는 해당 목록을 컨텍스트 윈도우의 일부로 제한합니다. 목록이 제한을 초과하면 Claude Code는 모든 스킬의 이름을 유지하지만 가장 적게 사용된 스킬의 설명을 삭제하므로 Claude는 여전히 해당 스킬을 호출할 수 있지만 자체적으로 선택할 가능성이 낮습니다. 더 많은 설명을 표시하려면 이 키를 높이되 턴당 더 많은 컨텍스트를 사용합니다.

• 범위: 모든 파일
• 유형: 숫자, 0보다 크고 최대 1인 분수
• 기본값: 0.01, 컨텍스트 윈도우의 1%를 예약합니다

{
  "skillListingBudgetFraction": 0.02
}

목록이 사용하는 컨텍스트 양과 어떤 스킬이 가장 많이 기여하는지 확인하려면 /doctor를 실행합니다.

skillListingMaxDescChars

각 턴마다 Claude는 각 스킬의 description 및 when_to_use 텍스트를 보여주는 스킬 목록을 봅니다. 이 키는 Claude Code가 스킬당 해당 텍스트의 몇 문자를 표시하는지 제한합니다. 더 긴 텍스트는 제한에서 잘립니다.

• 범위: 모든 파일
• 유형: 문자 수, 양의 정수
• 기본값: 1536

{
  "skillListingMaxDescChars": 2048
}

긴 설명을 유지하려면 높이되 턴당 더 많은 컨텍스트를 사용합니다. skillListingBudgetFraction 아래에 더 많은 스킬을 맞추려면 낮춥니다.

taskOutputMaxChars

[!WARNING]

v2.1.277에서 제거되었으며, 크기를 조정한 TaskOutput 도구와 함께 제거되었습니다. 설정해도 현재 버전에는 영향을 주지 않습니다. Claude는 Read를 사용하여 백그라운드 작업의 출력 파일을 읽습니다.

v2.1.276까지 이 키를 설정하여 Claude가 TaskOutput 도구로 작업을 읽을 때 인라인으로 받은 백그라운드 작업의 출력 문자 수를 설정했습니다.

인터페이스 및 터미널

터미널에서 Claude Code의 모양과 동작을 변경합니다. 테마, 편집기 모드, 상태줄, 스피너, 세션 내 알림, 접근성을 다룹니다. 터미널 구성을 참조하십시오.

askUserQuestionTimeout

응답이 없는 AskUserQuestion 대화 상자가 일정 시간 유휴 상태가 지나면 자동으로 계속 진행되도록 하며, 이미 선택한 옵션을 제출합니다. 자리를 비운 동안 Claude가 사용자 없이 계속 진행하기를 원할 때 설정합니다. 기본값에서는 질문이 사용자가 답할 때까지 대기합니다. 타이머가 일시 중지되거나 시작되지 않는 경우는 질문 자동 계속 타임아웃을 참조하십시오.

• 범위: User or managed
• 유형: 문자열, "60s", "5m", "10m", "never" 중 하나
• 기본값: "never"

{
  "askUserQuestionTimeout": "5m"
}

/config에 Question auto-continue timeout으로 표시되며, 이 키를 사용자 설정에 기록합니다. 관리형 설정이나 --settings 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

autoContinueAtUsageLimit

claude.ai 사용 한도로 세션이 중지된 후, 열린 세션에서 대기하다가 한도가 초기화되면 작업을 자동으로 계속합니다. 자동 계속 끄기를 참조하십시오. Claude Code v2.1.234 이상이 필요합니다.

• 범위: User or managed. 사용자 설정, --settings, 관리형 설정에서만 읽습니다. 이 중 어느 것도 키를 설정하지 않은 경우, 프로젝트 또는 로컬 설정 파일이 이 키를 설정하면 무시되는 대신 기능이 꺼집니다.
• 유형: Boolean
  • true: claude.ai 사용 한도로 세션이 중지된 후, Claude Code가 열린 세션에서 대기하다가 한도가 초기화되면 작업을 자동으로 계속합니다
  • false: Claude Code가 스스로 대기를 시작하지 않습니다. 사용 한도 옵션 메뉴에서 직접 대기를 시작할 수는 있습니다
• 기본값: true

{
  "autoContinueAtUsageLimit": false
}

/config에 Continue automatically at usage limit으로 표시되며, 이 키를 사용자 설정에 기록합니다. 관리형 설정이나 --settings 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

autoScrollEnabled

전체 화면 렌더링에서 새 출력을 따라 대화 하단으로 이동합니다. 이 설정을 끄면 Claude가 작업을 계속하는 동안 스크롤한 위치에 머무릅니다. 권한 프롬프트는 여전히 화면에 스크롤되어 표시됩니다.

• 범위: Any file
• 유형: Boolean
  • true: 대화가 새 출력을 따라 하단으로 이동합니다
  • false: Claude가 작업을 계속하는 동안 스크롤한 위치에 머무릅니다. 권한 프롬프트는 여전히 트랜스크립트 아래에 표시됩니다
• 기본값: true

{
  "autoScrollEnabled": false
}

전체 화면 렌더링이 켜져 있을 때 /config에 Auto-scroll로 표시되며, 이 키를 사용자 설정에 기록합니다.

axScreenReader

스크린 리더 친화적인 출력을 렌더링합니다. 장식용 테두리나 애니메이션이 없는 평문 텍스트입니다. 스크린 리더 모드는 클래식 렌더러를 사용하므로 활성화된 동안에는 tui 설정이 효과가 없습니다. 연결된 백그라운드 세션은 여전히 전체 화면으로 렌더링됩니다.

• 범위: User or managed. --settings로 전달하는 파일에서도 키를 설정할 수 있습니다. Claude Code는 프로젝트 및 로컬 설정의 키를 무시하므로, 저장소나 사용자 자신의 .claude/settings.local.json 모두 스크린 리더 모드를 켜거나 끌 수 없습니다.
• 유형: Boolean
  • true: Claude Code가 클래식 렌더러를 사용하여 장식용 테두리나 애니메이션 없이 평문 텍스트를 렌더링합니다
  • false: Claude Code가 일반적으로 렌더링합니다
• 기본값: 설정되지 않음, 따라서 스크린 리더 모드가 꺼져 있습니다
• 세션별 재정의: --ax-screen-reader가 CLAUDE_AX_SCREEN_READER보다 우선하며, 둘 다 한 세션 동안 이 키보다 우선합니다

{
  "axScreenReader": true
}

bashEditDiffEnabled

Bash 명령이 실행되는 동안 Git 저장소에서 어떤 파일이 변경되었는지 Claude Code가 기록할지 선택합니다. 기록하면 명령 실행 후 터미널에서 해당 diff를 볼 수 있고, PostToolUse Bash 훅이 변경된 파일 목록을 받습니다.

목록에 있는 파일이 항상 해당 명령이 변경한 파일인 것은 아닙니다. 명령이 실행되는 동안 다른 프로그램이나 다른 Bash 호출이 만든 변경도 목록에 나타날 수 있습니다.

모든 권한 모드에서 기록하려면 키를 true로 설정합니다. Claude Code v2.1.269 이상이 필요합니다.

• 범위: User or managed. true는 사용자 설정, --settings로 전달된 JSON, 또는 관리형 설정에서만 유효하므로, 저장소의 .claude/settings.json이나 .claude/settings.local.json에 있는 true로는 기록을 켤 수 없습니다. 두 저장소 파일 중 하나에 있는 false는 우선순위가 더 높은 파일이 true를 설정하지 않는 한 여전히 기록을 끕니다.
• 유형: Boolean
• 기본값: 설정되지 않음, 따라서 Claude Code는 자동 모드와 bypassPermissions 모드에서 Claude에게 Bash를 통해 파일을 편집하도록 지시할 때 변경 사항을 기록합니다
• 세션별 재정의: CLAUDE_CODE_BASH_EDIT_DIFF가 한 세션 동안 이 키보다 우선합니다

{
  "bashEditDiffEnabled": true
}

companyAnnouncements

시작 시 사용자에게 조직의 공지 사항을 표시합니다. 두 개 이상을 나열하면 Claude Code가 세션마다 하나를 무작위로 선택합니다. 사용자가 처음 실행할 때는 첫 번째 항목을 표시합니다.

• 범위: Any file
• 유형: 문자열 배열
• 기본값: 설정되지 않음, 따라서 공지 사항이 표시되지 않습니다

{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

defaultShell

입력 상자에서 ! 접두사로 입력하는 셸 명령, 즉 Claude Code가 직접 실행하여 세션에 추가하는 명령을 Bash와 PowerShell 중 어느 것으로 실행할지 선택합니다.

"powershell"은 PowerShell 도구가 켜져 있을 때만 작동합니다. 이 도구는 Git Bash가 없는 Windows에서, 그리고 claude.ai 및 Console 계정의 경우 Git Bash가 있는 Windows에서 기본적으로 켜져 있습니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 세션과 macOS, Linux, WSL에서는 CLAUDE_CODE_USE_POWERSHELL_TOOL=1을 설정하여 도구를 켭니다. 도구를 끄려면 이 변수를 0으로 설정합니다.

• 범위: Any file
• 유형: 문자열, 다음 중 하나:
  • "bash": Claude Code가 ! 명령을 Bash에서 실행합니다
  • "powershell": Claude Code가 ! 명령을 PowerShell에서 실행합니다
• 기본값: "bash", Bash를 사용할 수 없는 Windows에서는 "powershell"

{
  "defaultShell": "powershell"
}

지정한 셸을 사용할 수 없으면 Claude Code는 다른 셸을 사용합니다. "powershell"은 PowerShell 도구가 꺼져 있을 때 Bash로 대체되고, "bash"는 Bash가 설치되어 있지 않을 때 PowerShell로 대체됩니다.

dialogExpiry

Remote Control 또는 SDK 호스트와 같이 Claude Code가 원격 클라이언트로 전달하는 대화 상자와 보류된 세션 간 메시지의 승인 대화 상자에 대한 기한을 설정합니다. Claude Code v2.1.236 이상에서는 터미널에 아무도 없을 수 있는 세션에서 세션 도중 표시되는 Fable 사용량 크레딧 동의 프롬프트에도 같은 기한이 적용됩니다. 기한 전에 응답이 없으면 Claude Code는 대화 상자를 취소하고 아무 작업도 하지 않는 기본 동작으로 계속합니다. Claude Code v2.1.224 이상이 필요합니다.

• 범위: User or managed
• 유형: 문자열, "60s", "5m", "10m", 또는 기한을 비활성화하는 "never" 중 하나
• 기본값: "5m"
• 세션별 재정의: CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS가 한 세션 동안 이 키보다 우선합니다

{
  "dialogExpiry": "10m"
}

권한 프롬프트와 AskUserQuestion 질문은 자체 흐름을 사용하며 이 기한의 적용을 받지 않습니다. /config에 Dialog expiry로 표시되며, 이 키를 사용자 설정에 기록합니다. 이 행은 Claude Code v2.1.232 이상이 필요하며, 관리형 설정이나 --settings 플래그가 키를 설정하는 동안에는 Claude Code가 이 행을 숨깁니다.

editorMode

입력 프롬프트의 키 바인딩 모드를 선택합니다.

• 범위: Any file
• 유형: 문자열, 다음 중 하나:
  • "normal": 프롬프트 입력의 표준 키 바인딩
  • "vim": NORMAL, INSERT, VISUAL 모드를 갖춘 vim 스타일 편집
• 기본값: "normal"

{
  "editorMode": "vim"
}

/config에 Editor mode로 표시되며, 이 키를 사용자 설정에 기록합니다.

emojiCompletionEnabled

프롬프트 입력에 :와 단축 코드를 입력하면 이모지 제안을 표시하고, :heart:와 같이 완성된 단축 코드를 해당 이모지로 바꿉니다. 둘 다 끄려면 false로 설정합니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 : 뒤에 이모지 제안을 표시하고 완성된 단축 코드를 해당 이모지로 바꿉니다
  • false: Claude Code가 이모지를 제안하지 않으며 단축 코드도 바꾸지 않습니다
• 기본값: true

{
  "emojiCompletionEnabled": false
}

이모지 단축 코드를 참조하십시오. Claude Code v2.1.217 이상이 필요합니다.

fileSuggestion

기본 제공 파일 제안 대신 자체 명령을 실행하여 @ 파일 경로 자동 완성을 제공합니다. 기본 제공 제안은 빠른 파일 시스템 탐색을 사용합니다. 대규모 모노레포에서는 미리 빌드된 파일 인덱스와 같은 프로젝트별 인덱싱이 더 나을 수 있습니다.

• 범위: Any file. 상태줄 및 파일 제안 게이트에 따라 Claude Code는 명령을 끄거나 관리형 값만 실행하며, 사용자의 명령은 경고 없이 건너뜁니다.
• 유형: 항상 "command"인 type과 실행할 셸 명령인 command가 있는 객체
• 기본값: 설정되지 않음, 따라서 Claude Code가 기본 제공 파일 제안을 사용합니다

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

이를 저장한 후 프롬프트에 @와 경로의 일부를 입력하면 명령 출력에서 제안이 나옵니다.

명령 입력 및 출력

Claude Code는 CLAUDE_PROJECT_DIR를 포함하여 훅과 동일한 환경 변수로 명령을 실행하며, 5초 후에는 대기를 중단합니다. 명령은 지금까지 입력한 내용을 담은 query 필드가 있는 JSON을 stdin으로 받습니다.

{"query": "src/comp"}

줄바꿈으로 구분된 파일 경로를 stdout으로 출력합니다. Claude Code는 최대 15개를 표시합니다.

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

다음 스크립트는 쿼리를 읽어 저장소 파일 인덱스에 전달합니다.

#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

footerLinksRegexes

정규식이 턴 출력(파일 내용과 가져온 페이지를 포함한 도구 결과, Claude 자체의 응답)과 일치하면 입력 상자 아래 푸터에 클릭 가능한 배지를 추가로 렌더링합니다. 리뷰 도구나 이슈 트래커와 같은 프로젝트 CLI가 출력하는 ID를 세션 링크로 바꾸는 데 사용합니다.

• 범위: User or managed
• 유형: 객체 배열, 각 객체에는 "regex"로 설정된 type, pattern 정규식, url 템플릿, 선택적 label이 있습니다. url과 label의 {name} 자리 표시자는 pattern의 명명된 캡처 그룹으로 채워집니다
• 기본값: 설정되지 않음, 따라서 배지가 렌더링되지 않습니다

이 예시는 PROJ-1234와 같은 이슈 키를 일치시키고 캡처된 키로 각 링크를 만듭니다.

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

이렇게 구성하면 도구 결과나 Claude의 응답에 PROJ-1234가 나타날 때 https://issues.example.com/browse/PROJ-1234로 연결되는 PROJ-1234 배지가 푸터에 표시됩니다.

배지 제약 조건

각 항목의 URL, 레이블, 배지 수는 다음과 같이 제한됩니다.

턴이 완료되면 Claude Code는 메인 스레드에서 각 항목의 pattern 정규식을 턴 출력과 대조하므로, 느린 정규식은 완료될 때까지 UI를 차단합니다. (a+)+$와 같은 중첩 수량자는 특정 입력에 대해 기하급수적으로 오래 걸려 세션을 멈추게 할 수 있으므로, 각 pattern을 선형으로 유지하고 +나 *를 중첩하지 마십시오.

사용자 지정 상태줄이 구성되어 있으면 푸터 배지는 그 옆에 함께 렌더링되며, 어느 쪽도 다른 쪽을 대체하지 않습니다. 세션 데이터로 자체 내용을 계산하는 스크립트 기반 행에는 상태줄을 사용하고, 스크립트 없이 대화의 ID를 링크로 바꾸려면 푸터 배지를 사용합니다.

keybindingFlavor

[!WARNING]

v2.1.261부터 deprecated되었으며 효과가 없습니다. 프롬프트의 단어 편집 키는 Bash에서처럼 항상 readline 규칙을 따릅니다. Claude Code는 여전히 keybindingFlavor를 허용하므로 이를 설정한 설정 파일은 계속 유효합니다.

v2.1.238부터 v2.1.260까지는 이 키를 "readline"으로 설정하면 Ctrl+W가 이전 단어만이 아니라 이전 공백까지 삭제했습니다.

• 범위: Any file
• 유형: 문자열, "classic" 또는 "readline"
• 기본값: 설정되지 않음

maxProseWidth

넓은 터미널에서도 줄을 읽기 쉽게 유지하도록 Claude 응답의 산문 너비를 제한합니다. 단락, 제목, 목록, 인용구는 이 열 수 안에서 줄바꿈되며, 표와 코드 블록은 전체 터미널 너비를 유지합니다. Claude Code v2.1.282 이상이 필요합니다.

• 범위: Any file
• 유형: 터미널 열 수, 정수, 최솟값 40. Claude Code는 다른 값을 무시합니다
• 기본값: 설정되지 않음, 따라서 산문이 터미널 가장자리에서 줄바꿈됩니다

{
  "maxProseWidth": 80
}

prefersReducedMotion

스피너, 시머, 깜박임 효과와 같은 인터페이스 애니메이션을 줄이거나 끕니다. /config에 Reduce motion으로 표시됩니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 스피너, 시머, 깜박임 효과와 같은 인터페이스 애니메이션을 줄이거나 끕니다
  • false: 설정되지 않은 경우와 같으며, Claude Code가 애니메이션을 표시합니다
• 기본값: false

{
  "prefersReducedMotion": true
}

promptSuggestionEnabled

프롬프트 입력에 나타나는 회색 예측인 프롬프트 제안을 표시하거나 숨깁니다. 숨기려면 false로 설정하거나 /config에서 Prompt suggestions를 끕니다.

• 범위: Any file
• 유형: Boolean
  • true: 프롬프트 입력에 프롬프트 제안이 표시됩니다
  • false: Claude Code가 프롬프트 제안을 숨깁니다
• 기본값: true
• 세션별 재정의: CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION이 한 세션 동안 이 키보다 우선합니다

{
  "promptSuggestionEnabled": false
}

프롬프트 제안에는 텔레메트리가 켜진 claude.ai 또는 Console 계정이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서, 또는 DISABLE_TELEMETRY 등으로 텔레메트리가 꺼진 경우에는 이 키가 효과가 없으며 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1만으로 프롬프트 제안을 켤 수 있습니다.

respectGitignore

@ 파일 선택기가 .gitignore 패턴과 일치하는 파일을 제외할지 제어합니다. /config에 Respect .gitignore in file picker로 표시됩니다.

• 범위: Any file. 어떤 설정 파일도 이 키를 설정하지 않으면 Claude Code는 /config 토글이 기록하는 ~/.claude.json의 respectGitignore를 사용합니다.
• 유형: Boolean
  • true: @ 파일 선택기가 .gitignore 패턴과 일치하는 파일을 제외합니다
  • false: @ 파일 선택기가 .gitignore 패턴과 일치하는 파일을 포함합니다
• 기본값: true

{
  "respectGitignore": false
}

respondToBashCommands

입력 상자에서 ! 접두사로 셸 명령을 실행한 후 Claude가 응답할지 선택합니다. 기본적으로 Claude Code는 명령 출력을 대화에 추가하고 Claude가 이에 응답합니다. 응답 없이 출력을 컨텍스트에 추가하려면 이 키를 false로 설정합니다. 이렇게 하면 여러 명령을 실행한 후 한꺼번에 질문할 수 있습니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 명령 출력을 대화에 추가하고 Claude가 이에 응답합니다
  • false: Claude Code가 응답 없이 출력을 컨텍스트에 추가합니다
• 기본값: true

{
  "respondToBashCommands": false
}

! 접두사를 사용하는 셸 모드를 참조하십시오.

showClearContextOnPlanAccept

Claude가 플랜 모드에서 계획을 완료하면 승인 메뉴를 표시합니다. 계획 수립에는 많은 컨텍스트가 사용될 수 있으므로, 이 키는 해당 메뉴에 첫 번째 옵션으로 **Yes, clear context and …**를 추가합니다. 이 옵션은 계획을 승인하고 대화 컨텍스트를 지운 다음 계획만으로 구현을 시작합니다. 레이블의 나머지 부분에는 세션이 계속 진행될 권한 모드와 계획 수립에 사용된 컨텍스트의 양이 표시됩니다.

• 범위: Any file
• 유형: Boolean
  • true: 계획 승인 메뉴에 계획을 승인하고 대화 컨텍스트를 지우는 첫 번째 옵션 **Yes, clear context and …**가 추가됩니다
  • false: 계획 승인 메뉴에 컨텍스트 지우기 옵션이 표시되지 않습니다
• 기본값: false

{
  "showClearContextOnPlanAccept": true
}

showTurnDuration

각 응답 후에 "Cooked for 1m 6s · done 6:05 PM"과 같은 턴 소요 시간 메시지를 표시하거나 숨깁니다. "done" 뒤의 시각은 턴이 끝난 시간을 나타내며, timeFormat과 timeZone이 그 형식과 시간대를 제어합니다. /config에 Show turn duration으로 표시됩니다.

• 범위: Any file. 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 ~/.claude.json에 있는 값이 적용됩니다.
• 유형: Boolean
  • true: 각 응답 후에 턴 소요 시간 메시지가 표시됩니다
  • false: Claude Code가 턴 소요 시간 메시지를 숨깁니다
• 기본값: true

{
  "showTurnDuration": false
}

spellcheck

사용자가 설치한 맞춤법 검사기를 사용하여 입력하는 동안 프롬프트 입력에서 철자가 틀린 단어에 밑줄을 표시합니다. Claude Code는 입력 상자의 텍스트만 검사합니다. aspell, hunspell, ispell 설치 방법과 검사기가 다루는 범위는 입력하면서 맞춤법 검사를 참조하십시오. Claude Code v2.1.235 이상이 필요합니다.

• 범위: User or managed. 이 키를 설정하는 가장 높은 계층의 블록이 전체로 적용됩니다.
• 유형: enabled(Boolean), checker("aspell", "hunspell", "ispell", 또는 "auto"), language(문자열, 검사기에 사전 이름으로 전달됨), color(문자열, 터미널 색상 이름, #rrggbb, rgb(r,g,b), ansi256(n), 또는 ansi:<name>)가 있는 객체
• 기본값: 설정되지 않음, 따라서 맞춤법 검사가 꺼져 있습니다. checker의 기본값은 "auto"이며, 이는 세 검사기 중 PATH에서 가장 먼저 발견되는 것을 사용한다는 의미입니다. language의 기본값은 검사기 자체의 사전이며, color의 기본값은 테마의 오류 색상입니다

{
  "spellcheck": { "enabled": true, "language": "en_GB" }
}

spinnerTipsEnabled

Claude가 작업하는 동안 스피너 줄에는 "Use Plan Mode to prepare for a complex request before making changes. Press Shift+Tab twice to enable."와 같은 Claude Code 기능에 관한 짧은 팁이 순환 표시됩니다. 이를 숨기려면 이 키를 false로 설정합니다. /config에 Show tips로 표시됩니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude가 작업하는 동안 스피너에 팁이 표시됩니다
  • false: Claude Code가 스피너 팁을 숨깁니다
• 기본값: true

{
  "spinnerTipsEnabled": false
}

spinnerTipsOverride

Claude가 작업하는 동안 Claude Code가 표시하는 스피너 팁에 자체 팁을 추가하거나, 기본 제공 팁을 자체 팁으로 대체합니다. Claude Code는 사용자의 팁을 기본 제공 팁과 같은 순환에 넣습니다.

spinnerTipsEnabled를 false로 설정하면 Claude Code는 사용자의 팁을 포함하여 모든 팁을 숨깁니다.

• 범위: Any file. Claude Code는 사용자 설정, --settings 플래그, 관리형 설정의 팁 객체, tipsFile, label, excludeDefault를 적용하며, 프로젝트 및 로컬 설정에서는 일반 문자열 팁만 읽습니다.
• 유형: 각각 선택 사항인 tips, tipsFile, label, excludeDefault 필드가 있는 객체
• 기본값: 설정되지 않음, 따라서 Claude Code가 기본 제공 팁만 표시합니다

팁 객체, tipsFile, label, 그리고 프로젝트 및 로컬 설정이 일반 문자열만 제공한다는 범위 항목의 규칙은 Claude Code v2.1.247 이상이 필요합니다.

각 tips 항목은 일반 문자열이거나 다음 필드가 있는 객체입니다.

Claude Code는 일반 문자열을 해당 기본값과 위치 기반 id를 가진 팁으로 읽으므로, 목록 순서를 바꾸면 표시 기록이 초기화됩니다. 편집 후에도 기록을 유지하려면 팁에 id를 지정하십시오.

Claude Code는 tips와 tipsFile을 합쳐 최대 200개의 팁을 읽으며, 유효하지 않은 항목은 설정 파일을 거부하는 대신 디버그 경고와 함께 삭제합니다.

나머지 필드를 사용하여 팁 파일을 지정하고, 접두사를 설정하고, 기본 제공 팁을 숨깁니다.

• tipsFile: 같은 항목의 배열 또는 tips 배열이 있는 객체를 담은 로컬 JSON 파일의 절대 경로 또는 ~/ 경로, 최대 256 KB. Claude Code는 프로세스당 한 번 파일을 읽으므로, 편집 내용은 다음 시작 시 로드됩니다. 서버 관리형 설정을 통해서는 설정할 수 없습니다. 이 경우 인라인 tips를 배포하거나, 디스크상의 managed-settings.json에 경로를 배포하십시오.
• label: 사용자, --settings, 관리형 설정의 팁 앞에 Claude Code가 표시하는 접두사, 최대 40자. 기본값은 기본 제공 팁과 같은 접두사인 Tip이며, 프로젝트 및 로컬 설정의 팁은 항상 이 접두사를 사용합니다.
• excludeDefault: 기본 제공 팁을 숨기고 사용자의 팁만 표시하려면 true로 설정합니다. 예를 들어 tipsFile이 존재하지 않거나 모든 항목이 유효하지 않아 Claude Code가 사용자의 팁을 하나도 로드할 수 없으면, 빈 스피너 대신 기본 제공 순환을 유지합니다.

둘 이상의 설정 파일이 이 키를 설정하면 Claude Code는 모든 파일의 팁을 표시하며, tipsFile, label, excludeDefault는 각각을 설정하는 관리형 설정, --settings 플래그, 사용자 설정 중 우선순위가 가장 높은 것에서 가져옵니다.

사용자 설정에 있는 이 예시는 Acme tip 접두사로 일반 문자열 팁과 객체 팁을 순환에 추가합니다.

{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}

예시의 각 필드는 Claude Code가 팁을 표시하는 방식의 한 가지를 바꿉니다.

• label: Claude Code가 두 팁을 모두 Tip: ... 대신 Acme tip: ...으로 표시합니다.
• 일반 문자열: Claude Code가 기본값을 적용하므로 바로 다음 세션에 다시 나타날 수 있습니다.
• id: Claude Code가 두 번째 팁의 표시 기록을 gateway-errors 기준으로 관리하므로, 팁을 추가하거나 순서를 바꾼 후에도 쿨다운이 계속 적용됩니다.
• cooldownSessions: Claude Code가 gateway-errors 팁을 표시한 후에는 다섯 세션이 지날 때까지 해당 팁을 다시 표시하지 않습니다.
• priority: gateway-errors 팁과 다른 팁이 같은 세션 수 동안 표시되지 않은 경우(예: 둘 다 아직 표시된 적이 없는 경우), Claude Code는 gateway-errors를 먼저 표시합니다. 일반 문자열은 기본 우선순위인 0을 가집니다.

Claude가 작업하는 동안 Claude Code는 Acme tip: Run /review before opening a PR과 같이 사용자의 접두사와 함께 스피너에 팁을 표시합니다.

spinnerVerbs

턴이 진행되는 동안 스피너에는 "Accomplishing", "Architecting", "Baking"과 같은 동사가 순환 표시됩니다. 이 키를 사용하여 해당 순환에 자체 동사를 추가하거나 기본 제공 목록을 자체 목록으로 대체합니다.

• 범위: Any file
• 유형: 문자열 배열인 verbs와 다음 중 하나인 mode가 있는 객체:
  • "append": Claude Code가 기본 제공 세트에 사용자의 동사를 추가합니다
  • "replace": Claude Code가 사용자의 동사만 표시합니다
• 기본값: 설정되지 않음, 따라서 Claude Code가 기본 제공 동사를 사용합니다

이 예시는 기본 제공 세트에 두 개의 동사를 추가합니다.

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  }
}

"replace" 모드에서 verbs 배열이 비어 있으면 Claude Code는 기본 제공 동사를 유지합니다.

statusLine

자체 명령을 실행하여 모델, 비용, git 브랜치와 같은 컨텍스트를 담은 상태줄을 프롬프트 아래에 렌더링합니다. 선택적 필드로 간격을 조정하고, 주기적 재실행을 추가하고, 스크립트가 vim.mode를 직접 렌더링할 때 기본 제공 vim 모드 표시기를 숨길 수 있습니다.

• 범위: Any file. allowManagedHooksOnly가 켜져 있거나 disableAllHooks가 관리형 설정 외부에서 설정된 경우 관리형 설정 값만 실행됩니다.
• 유형: "command"로 설정된 type과 command 문자열, 그리고 선택적으로 문자 수인 padding, 초 단위(최솟값 1)인 refreshInterval, Boolean인 hideVimModeIndicator가 있는 객체
• 기본값: 설정되지 않음, 따라서 상태줄이 없습니다

이 예시는 모델 이름과 컨텍스트 사용량을 출력하고 수평 간격 2자를 추가합니다.

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}

이 예시는 jq가 설치되어 있어야 하며 셸에서 실행됩니다. PowerShell 및 Git Bash용 동등한 예시는 Windows 구성을, 전체 설정 방법은 상태줄 수동 구성을 참조하십시오.

subagentStatusLine

Claude가 서브에이전트를 실행하면 Claude Code는 프롬프트 아래의 작업 표시에 서브에이전트당 한 행씩 name · description · token count를 표시하여 나열합니다. 이 키를 사용하면 자체 명령을 실행하여 이러한 행을 다시 작성할 수 있습니다. 예를 들어 각 서브에이전트의 컨텍스트 사용량을 백분율로 표시할 수 있습니다. 새로 고칠 때마다 Claude Code는 각 서브에이전트의 id, name, status, model, tokenCount 등을 담은 tasks 배열이 포함된 하나의 JSON 객체로 표시된 행을 stdin에 보내고, {"id", "content"} 줄로 다시 작성한 각 id의 행을 대체합니다. 다시 작성하지 않은 행은 기본 렌더링을 유지합니다.

• 범위: Any file. allowManagedHooksOnly가 켜져 있거나 disableAllHooks가 관리형 설정 외부에서 설정된 경우 관리형 설정 값만 실행됩니다.
• 유형: "command"로 설정된 type과 command 문자열이 있는 객체
• 기본값: 설정되지 않음, 따라서 Claude Code가 기본 행을 렌더링합니다

{
  "subagentStatusLine": {
    "type": "command",
    "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"
  }
}

서브에이전트 상태줄을 참조하십시오.

syntaxHighlightingDisabled

Claude Code는 터미널에 표시하는 diff, 코드 블록, 파일 미리 보기의 코드를 기본 제공 하이라이터로 언어별로 색상을 입힙니다. 플러그인이나 언어 서버는 관여하지 않습니다. 색상이 터미널 테마와 어울리지 않거나 스크린 리더를 느리게 하는 경우 등에는 이 키를 true로 설정하여 일반 텍스트로 표시합니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 diff, 코드 블록, 파일 미리 보기에서 구문 강조를 끕니다
  • false: Claude Code가 구문을 강조합니다
• 기본값: false

{
  "syntaxHighlightingDisabled": true
}

terminalProgressBarEnabled

일부 터미널은 터미널에서 실행 중인 프로그램에 대한 진행률 표시기를 탭이나 작업 표시줄에 표시할 수 있습니다. Claude가 작업하는 동안 Claude Code는 터미널에 진행 중 상태를 보고하므로, 다른 탭이나 창에서 세션이 아직 바쁜지 확인할 수 있습니다. 턴이 끝난 후에도 백그라운드 서브에이전트나 동적 워크플로가 아직 실행 중이면 표시기가 계속 보이며, 세션이 유휴 상태가 되면 사라집니다.

Claude Code는 표시기를 지원하는 터미널(ConEmu, Ghostty 1.2.0 이상, iTerm2 3.6.6 이상)에서만 이를 보고합니다. Claude Code가 보고하지 않도록 하려면 이 키를 false로 설정합니다. /config에 Terminal progress bar로 표시됩니다.

• 범위: Any file. 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 ~/.claude.json에 있는 값이 적용됩니다.
• 유형: Boolean
  • true: 지원하는 터미널에서 터미널 진행률 표시줄이 표시됩니다
  • false: Claude Code가 터미널 진행률 표시줄을 숨깁니다
• 기본값: true

{
  "terminalProgressBarEnabled": false
}

terminalTitleFromRename

Claude Code는 터미널 탭의 제목을 설정합니다. 기본적으로 대화에서 생성한 제목을 사용하며, /rename 또는 --name으로 세션에 이름을 지정하면 탭에 그 이름이 대신 표시됩니다. 세션에 이름을 지정한 후에도 탭에 생성된 제목을 유지하려면 이 키를 false로 설정합니다. 이름 자체는 여전히 적용되므로 /resume <name>과 세션 선택기에서 찾을 수 있습니다.

• 범위: Any file
• 유형: Boolean
  • true: 터미널 탭 제목에 설정한 세션 이름이 표시됩니다
  • false: 탭이 대화에서 Claude Code가 생성한 제목을 유지합니다
• 기본값: true

{
  "terminalTitleFromRename": false
}

Claude Code가 터미널 제목을 아예 업데이트하지 않도록 하려면 대신 CLAUDE_CODE_DISABLE_TERMINAL_TITLE를 1로 설정합니다.

theme

인터페이스의 색상 테마를 선택합니다. /config에 Theme으로 표시됩니다.

• 범위: Any file. 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 ~/.claude.json에 있는 값이 적용됩니다.
• 유형: 문자열, 다음 중 하나:
  • "auto": 터미널의 밝은 배경 또는 어두운 배경에 맞춥니다
  • "dark": 어두운 테마
  • "light": 밝은 테마
  • "dark-daltonized": 색각 이상자 친화적인 색상의 어두운 테마
  • "light-daltonized": 색각 이상자 친화적인 색상의 밝은 테마
  • "dark-ansi": 터미널의 ANSI 색상 팔레트만 사용하는 어두운 테마
  • "light-ansi": 터미널의 ANSI 색상 팔레트만 사용하는 밝은 테마
  • "custom:<slug>" 또는 "custom:<plugin-name>:<slug>": ~/.claude/themes/ 또는 플러그인의 사용자 지정 테마
• 기본값: "dark"

{
  "theme": "light-daltonized"
}

사용자 지정 테마 만들기를 참조하십시오.

timeFormat

각 턴 소요 시간 메시지 끝의 done 6:05 PM이나 트랜스크립트 뷰어의 타임스탬프와 같이 Claude Code가 인터페이스에 표시하는 시간의 표기 방식을 선택합니다. 프리셋을 선택하려면 /config를 실행하고 Time format을 설정합니다. Claude Code v2.1.257 이상이 필요합니다.

• 범위: Any file
• 유형: 문자열, 다음 중 하나:
  • "auto": 설정되지 않은 경우와 같으며, 각 시간은 기본 제공 형식을 유지합니다. 턴 소요 시간 메시지에서는 로캘을 따릅니다
  • "12-hour": 12시간제
  • "24-hour": 24시간제
  • "24-hour-utc": 18:05Z와 같이 분 뒤에 Z가 붙는 UTC 기준 24시간제. 이 프리셋에서는 Claude Code가 timeZone을 무시합니다
  • "%H:%M"과 같은 strftime 패턴: Claude Code가 각 시간을 패턴으로 표기합니다. %가 포함된 값은 모두 패턴이며, 프리셋이 아닌 그 밖의 값은 "auto"로 간주됩니다
• 기본값: "auto"

{
  "timeFormat": "24-hour"
}

/config는 프리셋만 제공하므로, strftime 패턴을 사용하려면 설정 파일에 키를 추가하십시오. 이 예시는 각 시간을 두 자리 24시간제로 표시합니다.

{
  "timeFormat": "%H:%M"
}

그러면 턴 소요 시간 메시지와 트랜스크립트 뷰어에 18:05와 같은 시간이 표시됩니다. 트랜스크립트 뷰어에서는 패턴이 타임스탬프 전체이므로, 날짜를 표시하려면 날짜 지시어를 추가하십시오. 이 예시는 시각 앞에 날짜를 넣습니다.

{
  "timeFormat": "%Y-%m-%d %H:%M"
}

그러면 같은 위치에 2026-09-01 18:05와 같은 시간이 표시됩니다.

timeZone

인터페이스의 시간을 시스템과 다른 시간대로 표시합니다. "UTC" 또는 "Europe/Dublin"과 같은 IANA 시간대 이름으로 설정합니다. 그러면 timeFormat이 제어하는 시간이 이 시간대로 표시됩니다. timeFormat이 "24-hour-utc"이면 시간은 UTC로 유지되며 Claude Code는 이 키를 무시합니다. /config에는 이 키에 대한 행이 없으므로 설정 파일에서 설정하십시오. Claude Code v2.1.257 이상이 필요합니다.

• 범위: Any file
• 유형: 문자열, IANA 시간대 이름. Claude Code가 이름을 인식하지 못하면 시스템 시간대를 사용합니다
• 기본값: 설정되지 않음, 따라서 시간이 시스템 시간대로 표시됩니다

{
  "timeZone": "Europe/Dublin"
}

tui

터미널 UI 렌더러를 선택합니다. 가상화된 스크롤백을 갖춘 깜박임 없는 대체 화면 렌더러에는 "fullscreen"을, 클래식 메인 화면 렌더러에는 "default"를 사용합니다. /tui fullscreen 또는 /tui default를 실행하면 이 키가 자동으로 기록됩니다.

• 범위: Any file
• 유형: 문자열, 다음 중 하나:
  • "default": 클래식 메인 화면 렌더러
  • "fullscreen": 가상화된 스크롤백을 갖춘 깜박임 없는 대체 화면 렌더러
• 기본값: 설정되지 않음, 따라서 Claude Code가 렌더러를 자동으로 선택합니다
• 세션별 재정의: CLAUDE_CODE_NO_FLICKER와 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN이 한 세션 동안 이 키보다 우선합니다. CLAUDE_CODE_NO_FLICKER=1은 전체 화면을 켜고, CLAUDE_CODE_NO_FLICKER=0 또는 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1은 끕니다. 둘 다 설정된 경우 Claude Code는 전체 화면을 끕니다

{
  "tui": "fullscreen"
}

tmux -CC에서 또는 Windows로의 SSH 연결에서는 CLAUDE_CODE_NO_FLICKER=1을 설정하지 않는 한 Claude Code가 클래식 렌더러를 유지합니다. 에이전트 뷰에서 연 백그라운드 세션은 이 설정과 관계없이 항상 전체 화면 렌더러를 사용합니다.

verbose

기본적으로 트랜스크립트는 각 도구 호출을 Claude가 실행한 명령과 출력의 줄 수 같은 짧은 요약으로 접으며, 세부 정보를 보려면 Ctrl+O를 눌러 트랜스크립트 전체를 확장 보기로 전환합니다. 이 키를 true로 설정하면 모든 도구 호출의 전체 입력과 출력이 발생하는 즉시 인라인으로 표시되며, 훅, MCP 서버, 또는 긴 셸 명령을 디버깅할 때 유용합니다. /config에 Verbose output으로 표시됩니다.

• 범위: Any file. 어떤 설정 파일도 이 키를 설정하지 않으면 이전 버전의 ~/.claude.json에 있는 값이 적용됩니다.
• 유형: Boolean
  • true: 전체 도구 출력이 표시됩니다
  • false: 도구 출력의 잘린 요약이 표시됩니다
• 기본값: false
• 세션별 재정의: --verbose가 한 세션 동안 이 키보다 우선합니다

{
  "verbose": true
}

viewMode 값이나 유지되는 /focus 선택은 모든 세션에서 이 키를 재정의합니다.

viewMode

Claude Code가 시작할 때의 트랜스크립트 보기를 "default", "verbose", "focus" 중에서 설정합니다. 설정하면 유지되는 /focus 선택과 verbose 설정을 모두 재정의합니다.

• 범위: Any file
• 유형: 문자열, 다음 중 하나:
  • "default": 도구 출력이 잘린 일반 트랜스크립트
  • "verbose": 전체 도구 출력이 포함된 트랜스크립트
  • "focus": 마지막 프롬프트, 편집 diffstat이 포함된 도구 호출의 한 줄 요약, 최종 응답만 표시합니다. 포커스 보기에는 전체 화면 렌더러가 필요합니다
• 기본값: 설정되지 않음, 따라서 verbose 설정과 마지막 /focus 선택이 적용됩니다
• 세션별 재정의: --verbose가 한 세션 동안 이 키보다 우선합니다

{
  "viewMode": "focus"
}

vimInsertModeRemaps

vim 편집기 모드에서 두 키로 된 INSERT 모드 시퀀스를 Escape에 매핑합니다. 각 키는 순서대로 입력하는 정확히 두 개의 인쇄 가능한 문자이며, 지원되는 대상은 "<Esc>"뿐입니다. Claude Code는 다른 항목을 무시합니다.

• 범위: User or managed. 저장소는 사용자의 키 입력을 다시 매핑할 수 없습니다.
• 유형: 두 문자 시퀀스를 "<Esc>"에 매핑하는 객체
• 기본값: 설정되지 않음

{
  "vimInsertModeRemaps": {
    "jj": "<Esc>"
  }
}

editorMode가 "vim"이 아니면 효과가 없습니다. INSERT 모드 키 시퀀스 다시 매핑을 참조하십시오.

voice

음성 받아쓰기를 켜고 받아쓰기 키의 동작 방식을 선택합니다. /voice를 실행하면 Claude Code가 이 객체를 자동으로 기록합니다.

• 범위: Any file
• 유형: Boolean인 enabled, 홀드 모드에서만 적용되는 Boolean인 autoSubmit, 그리고 다음 중 하나인 mode가 있는 객체:
  • "hold": 말하는 동안 받아쓰기 키를 누르고 있다가 떼면 중지됩니다
  • "tap": 키를 한 번 눌러 녹음을 시작하고 다시 눌러 전송합니다
• 기본값: 설정되지 않음, 따라서 받아쓰기가 꺼져 있습니다. enabled가 true이고 mode가 설정되지 않은 경우 Claude Code는 "hold"를 사용합니다

이 예시는 받아쓰기를 켜고, 키를 한 번 눌러 녹음을 시작하고 다시 눌러 전송하도록 합니다.

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

autoSubmit은 홀드 모드에서 키를 뗄 때 프롬프트를 전송합니다. 음성 받아쓰기에는 claude.ai 계정이 필요합니다.

voiceEnabled

[!WARNING]

v2.1.92에서 voice 객체로 대체되면서 deprecated되었습니다. 이전 설정 파일이 계속 작동하도록 Claude Code가 여전히 이 키를 읽지만, 새 구성에서는 voice.enabled를 설정해야 합니다.

voice 객체 이전에 사용되던 단일 Boolean 형식으로 음성 받아쓰기를 켭니다. 둘 다 설정된 경우 voice.enabled가 적용됩니다.

• 범위: Any file
• 유형: Boolean
  • true: voice.enabled가 설정되지 않은 한, claude.ai 계정으로 로그인되어 있고 조직의 정책이 음성을 허용하면 음성 받아쓰기가 켜집니다
  • false: voice.enabled가 설정되지 않은 한 음성 받아쓰기가 꺼집니다
• 기본값: 설정되지 않음

{
  "voiceEnabled": true
}

wheelScrollAccelerationEnabled

전체 화면 렌더링에서 빠르게 스크롤할 때 마우스 휠 스크롤 속도를 가속합니다. 휠 한 칸당 일정한 스크롤 속도를 원하면 false로 설정합니다.

• 범위: Any file
• 유형: Boolean
  • true: Claude Code가 빠르게 스크롤할 때 마우스 휠 스크롤 속도를 가속합니다
  • false: Claude Code가 휠 한 칸당 일정한 속도로 스크롤합니다
• 기본값: true

{
  "wheelScrollAccelerationEnabled": false
}

Git 및 속성

Claude Code가 커밋 및 풀 요청에 추가하는 속성을 제어하고 git과 어떻게 작동하는지 관리합니다.

attribution

Claude Code가 git 커밋 및 풀 요청에 추가하는 속성을 사용자 정의합니다. 커밋은 기본적으로 Co-Authored-By와 같은 git 트레일러를 받습니다. 풀 요청 설명은 일반 텍스트를 받습니다. 아래의 하위 키를 사용하여 각 부분을 별도로 설정합니다.

• 범위: 모든 파일
• 유형: commit 및 pr 문자열과 sessionUrl 부울을 포함하는 객체, 또는 모든 속성을 숨기려면 false. false 값은 Claude Code v2.1.281 이상이 필요합니다. 이전 버전은 이를 거부하고 이를 포함하는 전체 사용자, 프로젝트 또는 로컬 설정 파일을 건너뜁니다.
• 기본값: 설정되지 않음. 따라서 Claude Code는 각 하위 키 아래에 표시된 표준 속성을 사용합니다.

모든 속성을 숨기려면 attribution을 false로 설정합니다. 이전 버전도 읽는 설정 파일에서는 commit 및 pr을 빈 문자열로 설정하고 sessionUrl을 false로 설정합니다.

이 예제는 커밋 속성을 바꾸고, 풀 요청 속성을 제거하며, 세션 링크를 삭제합니다:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": "",
    "sessionUrl": false
  }
}

commit 또는 pr을 설정하면 Claude Code는 더 이상 사용되지 않는 includeCoAuthoredBy 설정을 무시하고 설정하지 않은 두 항목에 대해 기본 텍스트를 사용합니다.

Claude Code는 Claude에게 속성에 대한 사용자 정의 지침(예: CLAUDE.md 또는 메모리 규칙)이 이러한 커밋 및 PR 라인보다 우선한다고 알립니다. 단, 라인이 관리되는 설정에서 설정된 경우는 제외합니다.

includeCoAuthoredBy

[!WARNING]

v2.0.62 이후 더 이상 사용되지 않음. attribution이 이를 대체했습니다. Claude Code는 여전히 이를 읽지만, 새로운 구성은 attribution을 설정해야 합니다.

이 키를 대체하는 attribution을 대신 사용하십시오. 이를 통해 커밋 트레일러, 풀 요청 텍스트 및 세션 링크를 별도로 변경하거나 숨길 수 있습니다. Claude Code는 여전히 attribution이 존재하기 이전의 설정 파일에서 includeCoAuthoredBy: false를 준수하지만, attribution.commit 또는 attribution.pr을 설정하면 이를 무시합니다.

• 범위: 모든 파일
• 유형: 부울
  • true: 설정되지 않은 것과 동일합니다. Claude Code는 커밋 트레일러 및 풀 요청 속성 텍스트를 추가합니다.
  • false: Claude Code는 커밋 트레일러 및 풀 요청 속성 텍스트를 모두 생략합니다. 단, attribution이 commit 또는 pr을 설정하는 경우 attribution 규칙이 적용됩니다.
• 기본값: true

{
  "includeCoAuthoredBy": false
}

모든 속성을 숨기려면 attribution을 참조하십시오.

includeGitInstructions

Claude Code는 Claude에게 두 가지 git 관련 컨텍스트를 제공합니다. Bash 도구의 설명에 있는 커밋 및 풀 요청 작성 방법에 대한 기본 제공 지침과 저장소의 git 상태 스냅샷입니다. 스냅샷은 현재 분기, 주 분기, git status 출력 및 최근 커밋을 포함합니다. Claude Code는 대화가 시작될 때 이를 읽습니다.

예를 들어 자신의 git 워크플로우 스킬을 사용할 때 이 키를 false로 설정하여 둘 다 제외합니다.

• 범위: 모든 파일
• 유형: 부울
  • true: Claude Code는 기본 제공 커밋 및 풀 요청 워크플로우 지침과 git 상태 스냅샷을 포함합니다. 클라우드 세션은 스냅샷을 포함하지 않습니다.
  • false: Claude Code는 둘 다 제외합니다.
• 기본값: true
• 세션별 재정의: CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS는 한 세션에 대해 이 키보다 우선합니다.