SpyBara
Go Premium

model-config.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 466 additions and 248 deletions.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58 Mon 21 22:59 Tue 22 23:59

모델 구성

Claude Code가 사용하는 모델, 노력 수준, 확장된 컨텍스트 및 자동 압축 윈도우를 구성합니다

사용 가능한 모델

Claude Code의 model 설정에서 다음 중 하나를 구성할 수 있습니다:

  • 모델 별칭
  • 모델 이름
    • Anthropic API: 전체 모델 이름
    • Amazon Bedrock: 추론 프로필 ARN
    • Microsoft Foundry: 배포 이름
    • Google Cloud의 Agent Platform: 버전 이름

어떤 모델과 노력 수준이 다양한 종류의 작업에 적합한지에 대한 지침은 블로그의 Claude Code에서 Claude 모델 및 노력 수준 선택하기를 참조하십시오.

모델 별칭

모델 별칭을 사용하여 정확한 버전 번호를 기억하지 않고도 모델 설정을 선택합니다:

모델 별칭 동작
default 모든 모델 재정의를 지우고 계정의 런타임 기본값으로 되돌리는 특수 값입니다. 자체로는 모델 별칭이 아닙니다
best fable 별칭이 확인되는 모델을 사용합니다. Fable을 사용할 수 있는 경우, 그렇지 않으면 opus와 동일한 모델을 사용합니다
fable 가장 어렵고 오래 실행되는 작업을 위해 공급자의 Fable 모델을 사용합니다
sonnet 일상적인 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다
opus 복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다
haiku 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다
sonnet[1m] 긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 가진 Sonnet을 사용합니다. sonnet이 이미 기본 100만 윈도우를 가진 Sonnet 5로 확인되는 경우 효과가 없습니다. LLM 게이트웨이 뒤에서는 Sonnet 5의 100만 윈도우를 선택합니다
opus[1m] 긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 가진 Opus를 사용합니다
opusplan 계획 모드 중에 opus를 사용한 다음 실행을 위해 sonnet으로 전환하는 특수 모드입니다

opus 및 sonnet 별칭이 확인되는 버전은 공급자에 따라 다릅니다:

공급자 opus sonnet
Anthropic API Opus 5 Sonnet 5
AWS의 Claude Platform Opus 5 Sonnet 4.6
Amazon Bedrock, Google Cloud의 Agent Platform Opus 5 Sonnet 4.5
Microsoft Foundry Opus 4.6 Sonnet 4.5

ANTHROPIC_DEFAULT_FABLE_MODEL을 설정하지 않으면 fable 별칭은 Fable 5.1로 확인됩니다. 단, Claude 앱 게이트웨이 세션에서는 fable 및 best가 Fable 5로 확인됩니다. v2.1.257 이전에는 fable이 모든 공급자에서 Fable 5로 확인되었습니다.

claude-fable-5-1을 제공하도록 구성되지 않은 게이트웨이는 해당 모델에 대한 요청을 거부합니다. 이를 제공하는 게이트웨이를 통해 Fable 5.1을 사용하려면 /model claude-fable-5-1로 선택합니다.

별칭이 이전 모델로 확인되는 경우, 전체 모델 이름을 명시적으로 선택하거나 ANTHROPIC_DEFAULT_OPUS_MODEL 또는 ANTHROPIC_DEFAULT_SONNET_MODEL을 설정하여 최신 모델을 사용할 수 있습니다.

v2.1.219 이전에는 opus가 Anthropic API에서 v2.1.154부터 Opus 4.8로 확인되었고, Claude Platform on AWS, Amazon Bedrock, Google Cloud의 Agent Platform에서 v2.1.207부터 확인되었습니다. v2.1.207 이전에는 opus가 Claude Platform on AWS에서 Opus 4.7로, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Opus 4.6으로 확인되었습니다.

별칭은 공급자의 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: claude-opus-5)을 사용하거나 ANTHROPIC_DEFAULT_OPUS_MODEL과 같은 해당 환경 변수를 설정합니다.

Fable 작업하기

Claude Fable 5.1 및 Claude Fable 5는 Claude Code에서 가장 강력한 모델로, 한 번의 세션보다 큰 작업에 적합합니다. 이들은 긴 자율 세션을 유지하고, 행동하기 전에 조사하며, 더 작은 모델보다 더 자주 자신의 작업을 검증합니다. Fable 5.1은 더 최신 릴리스입니다.

두 Fable 모델 모두 어떤 플랜이나 공급자에서도 계정 유형 기본값이 아닙니다. 명시적으로 선택합니다:

  • Fable 5.1: /model fable을 실행하거나 claude --model fable로 시작합니다. Claude 앱 게이트웨이 세션에서 별칭이 Fable 5로 확인되는 경우 대신 /model claude-fable-5-1을 실행합니다.
  • Fable 5: 모델 ID로 선택합니다. Anthropic API에서 /model claude-fable-5를 실행하거나 claude --model claude-fable-5로 시작합니다. 다른 공급자에서는 공급자의 Fable 5 모델 ID를 사용하거나 ANTHROPIC_DEFAULT_FABLE_MODEL로 고정합니다.

Anthropic API에 직접 연결하고 사용자 설정에 모델로 claude-fable-5 또는 claude-fable-5[1m]이 있는 경우(예: v2.1.257 이전에 /model 선택기에서 Fable을 선택했기 때문), Claude Code는 v2.1.257 이상을 처음 실행할 때 저장된 값을 fable 또는 fable[1m] 별칭으로 변경합니다. 시작 모델 라인은 한 번 (auto-updated)를 표시합니다. 프로젝트, 로컬 또는 관리 설정의 claude-fable-5 값은 그대로 유지됩니다.

Fable 모델의 안전 분류기가 플래그를 지정하는 요청(대부분 사이버 보안 및 생물학 도메인)은 자동 모델 폴백을 트리거합니다.

Fable을 최대한 활용하려면:

  • 결과를 설명하고 단계는 설명하지 마십시오: 원하는 결과를 제공하고 경로를 계획하도록 합니다. 해당 결과를 향해 작업하도록 유지하려면 목표를 설정합니다.
  • 모호한 문제를 제공합니다: 근본 원인 조사, 중단 디버깅, 아키텍처 결정은 추가 조사 및 검증이 가치 있는 곳입니다.
  • 검증 알림을 건너뜁니다: 자신의 작업을 더 적은 프롬프트로 검증하므로 테스트 또는 확인 알림은 일반적으로 불필요합니다.
  • 더 큰 작업을 크기 조정합니다: 일반적으로 조각으로 나누는 작업을 제공합니다. 긴 세션을 유지하면서 스레드를 잃지 않습니다.

Anthropic API에서 /model 선택기는 서버가 조직에 대해 사용 가능하다고 보고한 후에만 Fable 모델을 나열합니다. /model fable 또는 Fable 모델 ID를 입력하면 Claude Code는 서버와 직접 가용성을 확인하므로 선택기가 항목을 나열하지 않아도 입력된 선택이 성공할 수 있습니다.

Fable 및 사용 크레딧

플랜 및 시트 계층에 따라 Fable 사용은 사용 크레딧으로 청구되거나 플랜의 포함된 한도를 사용할 수 있습니다. 그렇게 되면 /model 선택기는 Fable 행에 "사용 크레딧 필요"를 표시합니다. 사용 크레딧을 관리하려면 구독에 사용 크레딧 추가를 참조하십시오.

대화형 세션에서 Claude Code는 Fable 요청이 사용 크레딧을 청구하기 전에 동의 프롬프트를 표시합니다. 조직 청구가 있는 Enterprise 플랜의 구성원은 프롬프트를 보지 않습니다. 사용 크레딧을 사용하여 Fable을 계속하거나 기본 모델로 전환할 수 있습니다. 프롬프트를 해제할 수도 있습니다:

  • /model 선택기에서 현재 모델을 유지합니다.
  • 세션 중간에 Claude Code는 기본 모델에서 턴을 계속합니다.

사용 크레딧을 사용하여 Fable을 계속하도록 선택한 후 Claude Code는 프롬프트를 다시 표시하지 않습니다.

Remote Control이 연결된 세션, 백그라운드 세션, 또는 에이전트 팀 팀원의 세션에서 터미널에 아무도 없을 수 있으므로 Claude Code는 dialogExpiry 기한(기본값 5분)까지 세션 중간 동의 프롬프트를 유지합니다. 기한까지 아무도 응답하지 않으면 Claude Code는 요청을 보내지 않고 턴을 종료하고 트랜스크립트에 알림을 추가하며, Remote Control 클라이언트도 이를 표시합니다. 모델 선택은 변경되지 않으며 Claude Code는 다음 메시지에서 동의를 다시 요청합니다.

프롬프트가 대기 중인 동안 수행할 수 있는 작업은 세션에 따라 다릅니다:

  • Remote Control이 연결되었거나 팀원의 세션에서 터미널의 아무 키나 눌러 기한을 취소하면 Claude Code는 답변을 기다립니다.
  • 백그라운드 세션에서 기한 전에 답변합니다.
  • 터미널에서 아무도 입력하기 전에 원격 클라이언트에서 새 메시지를 보내면 Claude Code는 같은 방식으로 턴을 종료하고 새 메시지가 다음 턴을 시작합니다. 누군가 터미널에 입력한 후 Claude Code는 답변을 기다리고 새 메시지를 뒤에 대기열에 넣습니다.

비대화형 모드에서 -p 플래그 및 Agent SDK를 통해 Claude Code는 동의 프롬프트를 표시하지 않습니다. Fable 요청이 사용 크레딧으로 청구될 때 Claude Code는 묻지 않고 청구합니다.

모델 설정하기

여러 가지 방법으로 모델을 구성할 수 있으며, 우선순위 순서대로 나열됩니다:

  1. 세션 중: /model <alias|name>을 사용하여 즉시 전환하거나 인수 없이 /model을 실행하여 선택기를 엽니다. Claude Code가 전환을 확인하도록 요청할 때를 참조하십시오
  2. 시작 시: claude --model <alias|name>으로 시작합니다
  3. 환경 변수: ANTHROPIC_MODEL=<alias|name>을 설정합니다
  4. 설정: model 필드를 사용하여 설정 파일에서 영구적으로 구성합니다
  5. 새 세션의 기본값: ANTHROPIC_DEFAULT_MODEL=<alias|name>을 설정합니다

/model은 사용자 설정에서 model 필드를 작성하여 선택을 새 세션의 기본값으로 저장합니다. 선택기에서:

  • Enter: 모델을 전환하고 기본값으로 저장합니다
  • s: 이 세션에만 모델을 전환합니다

/model <name>을 직접 입력하는 것은 Enter처럼 동작합니다. /model로 설정된 모델은 비대화형 모드에서 -p 플래그를 사용하면 현재 세션에만 적용되며 기본값으로 저장되지 않습니다. 프로젝트 및 관리 설정은 여전히 우선순위를 가지며 다음 시작 시 다시 적용됩니다. 관리자가 구성한 조직 기본 모델은 사용자 선택을 재정의하도록 설정되어 있으면 다음 시작 시 다시 적용됩니다.

v2.1.144부터 v2.1.152까지 /model은 현재 세션에만 적용되었고 선택기의 d는 기본값을 저장했습니다.

--model 플래그 및 ANTHROPIC_MODEL 환경 변수는 시작한 세션에만 적용됩니다. 동시에 다른 터미널에서 다른 모델을 실행하려면 /model로 전환하는 대신 각각 자신의 --model 플래그로 시작합니다.

/model 선택기의 가격은 Claude Code가 Anthropic API와 직접 또는 LLM 게이트웨이를 통해 프록시할 때 나타나며, 행의 가격은 해당 행이 선택하는 모델의 가격입니다. Amazon Bedrock과 같은 타사 공급자에서 및 Claude 앱 게이트웨이에서 공급자 또는 게이트웨이가 지불하는 금액을 결정하므로 선택기 행은 가격을 표시하지 않습니다. 가격은 표시 레이블일 뿐이며, 행이 선택하는 모델이나 공급자가 청구하는 금액에 영향을 주지 않습니다. v2.1.206 이전에는 AWS의 Claude Platform 및 게이트웨이 세션이 Anthropic 정가를 표시했으며, 행은 선택하는 모델과 다른 모델의 가격을 표시할 수 있었습니다.

claude --resume, --continue 또는 /resume 선택기로 시작된 재개된 세션은 현재 model 설정에 관계없이 트랜스크립트가 저장되었을 때 사용 중이던 모델을 유지합니다. 복원된 모델이 폐기되었거나 availableModels에 의해 제외되면 세션은 정상 우선순위 순서로 폴백됩니다. 이는 다른 세션의 /model 선택이 재개 시 모델을 변경하는 것을 방지합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같이 Anthropic 모델 ID 대신 공급자별 배포 ID를 사용하는 공급자에서는 트랜스크립트 모델이 전혀 복원되지 않으며 세션은 정상 우선순위 순서를 통해 모델을 확인합니다.

새 시작을 위해 --model 또는 ANTHROPIC_MODEL로 선택한 모델은 여전히 복원된 모델보다 우선순위를 가집니다. v2.1.195부터 ANTHROPIC_DEFAULT_OPUS_MODEL 패밀리 변수도 마찬가지입니다. ANTHROPIC_DEFAULT_MODEL도 해당 섹션에 나열된 조건 하에서 가능합니다.

시작 시 활성 모델이 자신의 선택이 아닌 프로젝트 또는 관리 설정에서 나오면 시작 헤더는 어떤 설정 파일이 설정했는지 표시합니다. /model을 실행하여 재정의합니다. 프로젝트 또는 관리 설정은 다음 시작 시 다시 적용됩니다. Claude Code를 포함하고 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정하는 플랫폼에서 호스트의 모델 구성은 관리 모델 설정보다 우선순위를 가지며, 호스트가 자신의 것을 제공하지 않으면 관리 availableModels 허용 목록이 적용됩니다. 관리 설정 우선순위의 예외는 호스트가 재정의하는 키 및 변수를 나타냅니다.

조직이 PreModelSwitch 훅을 구성하면 요청된 전환이 적용되기 전에 실행되며 이를 차단하거나 확인을 요청할 수 있습니다.

Claude Code가 조직의 관리 플러그인이 제공하는 PreModelSwitch 훅을 알 수 없는 경우(예: 관리 플러그인이 로드되지 않음), 확인되지 않은 상태로 적용하는 대신 전환을 거부하며, 각 새 시도에서 다시 확인합니다. PreModelSwitch 훅에 의해 모델 전환이 차단되었습니다를 참조하여 메시지 및 복구를 확인합니다.

Agent SDK setModel() 메서드를 통해 모델을 전환하거나 Remote Control을 통해 연결된 장치에서, 또는 Claude Code CLI를 전환하는 Desktop 앱과 같은 앱에서 Claude Code는 문자열이 인식하는 것인지 확인한 후 저장합니다. 이 확인에는 Claude Code v2.1.200 이상이 필요합니다. Remote Control 선택을 확인하려면 머신에 Claude Code v2.1.260 이상이 필요합니다. Anthropic API에서 Claude Code는 다음을 인식합니다:

Claude Code는 인식되지 않은 문자열을 Model "<name>" is not a recognized model id.로 거부하며 세션은 현재 모델을 유지하고, 문자열을 저장하고 다음 요청에서 실패하는 대신입니다. 복구 단계는 오류 참조를 참조하십시오.

확인은 Anthropic API에서만 실행됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform, LLM 게이트웨이 뒤 또는 사용자 정의 ANTHROPIC_BASE_URL에서 공급자 또는 게이트웨이가 모델 이름을 정의하므로 Claude Code는 확인 없이 모든 문자열을 통과시킵니다. 확인은 또한 --model 플래그, ANTHROPIC_MODEL 환경 변수 또는 model 설정을 다루지 않습니다. 잘못 입력된 값은 첫 번째 요청에서 선택된 모델에 문제가 있습니다를 생성합니다. Claude Code는 여전히 모든 공급자에서 요청 시간에 인식되지 않은 모델 진단 라인을 작성할 수 있습니다.

요청된 모델에 예정된 폐기 날짜가 있거나 자동으로 최신 버전으로 다시 매핑되면 Claude Code는 요청된 모델의 이름을 지정하는 경고를 표시합니다. 대화형 세션은 시작 알림으로 표시합니다. v2.1.182부터 기본 텍스트 출력 형식을 사용할 때 비대화형 모드에서 동일한 경고가 stderr에 작성됩니다. 확인은 또한 서브에이전트 프론트매터에 설정된 model을 다룹니다. stderr 경고는 --output-format json 및 stream-json에 대해 억제됩니다. 결과 메시지의 modelUsage 필드에서 실제 모델을 읽습니다.

예를 들어 Opus에서 세션을 시작합니다:

claude --model opus

그런 다음 세션 내에서 모델을 전환합니다:

/model sonnet

예제 설정 파일:

{
    "permissions": {
        "allow": ["Bash(npm run lint)"]
    },
    "model": "opus"
}

새 세션의 기본 모델 설정하기

ANTHROPIC_DEFAULT_MODEL=<alias|name>을 설정하여 세션이 기본적으로 시작되는 모델을 선택합니다. Claude Code v2.1.236 이상이 필요합니다.

Claude Code는 다음 중 어느 것도 모델을 선택하지 않을 때만 변수의 모델에서 새 세션을 시작합니다:

  • --model 플래그
  • ANTHROPIC_MODEL
  • 모든 설정 파일의 model 값(예: /model로 저장한 선택 포함)
  • 조직 기본 모델

/model로 저장한 선택은 나중의 시작에서도 변수보다 우선순위를 가집니다. 대신 ANTHROPIC_MODEL이 설정되면 Claude Code는 /model로 저장한 것에 관계없이 다음 시작에서 해당 변수의 모델로 돌아갑니다.

Claude Code는 또한 조직 기본 모델이 적용되지 않으면 Default 옵션을 변수의 모델로 확인합니다. Default 옵션이 변수의 모델로 확인되면 /model 선택기의 Default 행은 ANTHROPIC_DEFAULT_MODEL로 설정된 레이블을 표시합니다.

Claude Code는 이 경우들에서 변수를 무시하며, Default 옵션은 설정하지 않은 것처럼 확인됩니다:

새 세션이 변수의 모델에서 시작될 때 claude --resume, --continue 또는 /resume 선택기로 재개한 세션도 시작됩니다. Claude Code는 해당 세션의 트랜스크립트에 저장된 모델을 복원하지 않습니다. 그렇지 않으면 Claude Code는 세션을 재개할 때 변수를 사용하지 않습니다.

새 세션이 선택한 것과 다른 모델에서 시작됩니다

/model로 모델을 선택하고 다음 세션이 다른 것에서 시작되면 이것이 일반적인 원인입니다:

  • 한 세션에만 선택했습니다. 선택기에서 s를 누르고, --model로 시작하고, 비대화형 모드에서 /model을 실행하는 것은 모두 현재 세션에 적용되며 저장된 기본값을 그대로 둡니다.
  • 더 높은 우선순위를 가진 것이 모델을 설정합니다. 프로젝트 또는 관리 설정의 model 값, 셸의 ANTHROPIC_MODEL, 또는 관리자가 사용자 선택을 재정의하도록 설정한 조직 기본값은 모든 시작에서 다시 적용됩니다. /model 선택은 여전히 저장됩니다. 우선순위가 높습니다. 프로젝트 또는 관리 설정이 모델을 설정하면 시작 헤더가 파일의 이름을 지정합니다.
  • Claude Code가 선택을 저장할 수 없었습니다. /model은 ~/.claude/settings.json에 model을 작성합니다. 다른 도구가 생성하거나 읽기 전용 복사본에 연결하는 경우와 같이 해당 파일에 쓸 수 없으면 선택한 모델은 세션 동안 지속되고 다음 시작은 이전 값을 읽습니다. 파일을 생성하는 도구에서 model을 설정하거나 파일을 쓰기 가능하게 만듭니다. Claude Code에서 만든 변경 사항이 새 세션에서 손실됩니다를 참조하십시오.
  • 세션을 재개했습니다. claude --resume 또는 --continue로 재개한 세션은 일반적으로 현재 기본값이 아닌 사용 중이던 모델을 유지합니다.

모델 선택 제한

엔터프라이즈 관리자는 관리형 또는 정책 설정에서 availableModels를 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다. 항목은 sonnet과 같은 모델 패밀리, claude-sonnet-4-5와 같은 버전 접두사, 또는 claude-sonnet-4-5-20250929와 같은 전체 모델 ID와 일치합니다. 버전 접두사는 또한 다른 세그먼트로 확장하는 이후 모델 ID와도 일치하므로, claude-fable-5는 Fable 5와 Fable 5.1을 모두 허용하고, claude-fable-5-1은 Fable 5.1만 허용합니다.

Claude Code를 포함하고 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정하는 플랫폼에서는 호스트의 모델 구성이 관리형 모델 설정보다 우선하며, 관리형 availableModels 허용 목록은 호스트가 자체 목록을 제공하지 않는 한 계속 적용됩니다. 관리형 설정 우선순위의 예외에서 호스트가 재정의하는 키와 변수를 설명합니다.

availableModels가 설정되면, 허용 목록은 사용자가 모델을 지정할 수 있는 모든 곳에 적용됩니다:

  • 메인 세션 모델: /model, --model 플래그, ANTHROPIC_MODEL 환경 변수, model 설정, ANTHROPIC_DEFAULT_MODEL, 그리고 세션 재개할 때 복원되는 모델
  • 별칭 해석: ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, 그리고 ANTHROPIC_DEFAULT_FABLE_MODEL 환경 변수는 허용된 별칭을 목록 외부의 모델로 리디렉션할 수 없습니다
  • 빠른 모드: /fast는 목록 외부의 Opus 모델로 암묵적으로 전환할 때 토글을 거부하며, "is not in your organization's allowed models" 메시지를 표시합니다
  • 서브에이전트 및 팀원 모델: 서브에이전트 frontmatter의 model 필드, Agent 도구의 model 매개변수, 에이전트 팀 팀원 모델, CLAUDE_CODE_SUBAGENT_MODEL, 그리고 v2.1.197 이전에는 /agents 마법사의 모델 선택기
  • 스킬 및 명령 모델: 스킬 및 명령의 model frontmatter
  • 어드바이저 모델: 구성된 advisorModel 설정 및 --advisor 플래그
  • 백그라운드 에이전트 모델: 디스패치 선택기에서 선택된 모델

Anthropic API 및 Claude Platform on AWS에서 모델 패밀리 별칭 opus, sonnet, haiku, 또는 fable은 허용 목록이 해당 모델을 허용할 때 일반적인 모델로 해석됩니다. 허용 목록이 해당 모델을 차단할 때, Claude Code는 허용 목록이 허용하는 패밀리의 최신 버전으로 대체하고 요청된 모델과 대체된 모델을 모두 이름 지은 공지를 표시합니다. 예를 들어 ["sonnet", "claude-opus-4-6"]을 사용하면, /model opus와 --model opus 모두 허용된 최신 Opus인 Claude Opus 4.6을 선택합니다. v2.1.205 이전에는 최신 릴리스 버전이 목록 외부에 있는 별칭은 목록이 이전 버전을 허용하더라도 다른 차단된 선택처럼 거부되거나 대체되었습니다.

대체는 착지할 수 있는 허용된 버전이 필요합니다: 허용 목록이 별칭의 패밀리의 버전을 허용하지 않을 때, 별칭은 다른 차단된 값처럼 아래의 거부 및 대체 동작을 따릅니다.

Claude Code는 모델이 설정된 위치에 따라 다른 차단된 선택을 처리합니다:

  • /model: Claude Code는 오류로 전환을 거부합니다

  • --model 플래그, ANTHROPIC_MODEL, 또는 model 설정: Claude Code는 시작 시 값을 요청된 모델과 대체된 모델을 모두 이름 지은 경고와 함께 대체하며, 세션은 기본 모델에서 시작됩니다

  • ANTHROPIC_DEFAULT_MODEL: Claude Code는 변수를 무시합니다

  • 서브에이전트 또는 팀원 재정의: Claude Code는 요청을 실패하지 않고 서브에이전트 또는 팀원을 폴백 모델에서 실행합니다. 서브에이전트 폴백은 모델 선택을 참조하고 팀원 폴백은 팀원 및 모델 지정을 참조하세요.

    대화형 세션에서 Claude Code는 이 폴백 또는 위의 최신 허용 버전 대체로 서브에이전트의 모델을 대체할 때 요청된 모델과 대체된 모델을 이름 지어 경고합니다. 팀원의 폴백은 보고하지 않습니다.

    위의 최신 허용 버전 대체가 작동하는 경우, 차단된 패밀리 별칭이 대신 따릅니다. v2.1.222 이전에는 별칭이 모든 제공자에서 다른 차단된 값처럼 폴백했습니다

  • 스킬 또는 명령 재정의: Claude Code는 차단된 패밀리 별칭을 포함한 재정의를 무시하고 스킬 또는 명령은 세션 모델에서 실행됩니다. 서브에이전트에서 실행되는 스킬 또는 명령은 대신 위의 서브에이전트 동작을 따릅니다

  • advisorModel 설정: 어드바이저는 세션에 대해 비활성화됩니다

  • --advisor 플래그: Claude Code는 시작 시 오류로 종료됩니다. 백그라운드 세션에서는 종료하지 않고 어드바이저 없이 세션을 시작합니다

Claude Code는 /model 선택기에서 제외된 모델을 숨깁니다. 목록의 전체 모델 ID가 목록이 고정하는 이전 버전과 같이 기본 제공 선택기 행이 없으면, Claude Code가 기본 제공 옵션을 modelPicker 라인업으로 대체하지 않는 한 /model 선택기에 자체 레이블이 지정된 행으로 나타납니다. v2.1.199 이전에는 이러한 ID는 /model <id>를 입력하여만 선택할 수 있었습니다.

Claude Code가 사용자를 대신하여 수행하는 모델 변경은 동일한 방식으로 확인됩니다:

  • 폴백 모델 체인: 허용 목록 외부의 항목은 삭제됩니다
  • Plan 모드 업그레이드: Anthropic API 및 Claude Platform on AWS에서 opusplan과 같은 제외된 모델로의 업그레이드는 업그레이드 패밀리의 최신 허용 버전을 사용합니다. 제공자별 모델 ID가 있는 제공자에서 그리고 허용된 버전이 없을 때, 업그레이드는 건너뛰고 계획은 세션의 모델에서 계속됩니다
  • 자동 모델 폴백: 대상이 제외된 폴백은 실행되지 않으므로 플래그된 요청은 거부로 끝납니다
  • Auto 모드 분류기: 분류기의 Claude Sonnet 5 기본값은 허용 목록이 Sonnet 5를 허용할 때만 적용됩니다. 제외될 때, 분류기는 허용 목록이 이미 관리하는 세션의 모델에서 실행되거나, 세션이 Fable 모델에서 실행될 때 Opus 모델에서 실행됩니다. Anthropic API 이외의 제공자에서 해당 Opus 폴백은 허용 목록을 참조하지 않고 제공자의 기본 Opus 모델에서 실행됩니다. Claude Code v2.1.210 이상 필요
  • 빠른 모드: 세션이 그 후 실행될 모델이 허용 목록 외부에 있을 때 빠른 모드 활성화가 거부됩니다
{
  "availableModels": ["sonnet", "haiku"]
}

표면 범위

모든 표면은 수신하는 허용 목록을 적용합니다. 각 표면에 도달하는 전달 메커니즘은 다릅니다:

전달 메커니즘 CLI 및 IDE 데스크톱 로컬 세션 웹, 모바일 및 클라우드 세션 Agent SDK 및 비대화형 Cowork
관리 콘솔의 서버 관리 설정 적용됨 적용됨 적용됨 적용됨 전달되지 않음
MDM 또는 관리형 설정 파일 적용됨 적용됨 Anthropic 호스팅 환경에서는 전달되지 않음. 자체 호스팅 환경에서는 Claude Code가 관리형 소스를 결합하는 방식에 따라 러너 이미지에서 적용됨 적용됨 배포된 경우 적용됨
  • 클라우드 세션은 Claude Code on the web 또는 Desktop 앱에서 기본적으로 Anthropic 관리 VM에서 실행됩니다: 장치에 배포된 설정은 이에 도달하지 않으므로 서버 관리 설정을 통해 허용 목록을 전달합니다. 조직이 자체 호스팅 환경으로 라우팅하는 세션은 자신의 컴퓨팅에서 실행되고 러너 이미지의 관리형 설정 파일도 읽습니다. Claude Code가 관리형 소스를 결합하는 방식에서 해당 파일이 적용되는 시기를 설명합니다. 클라우드 세션의 중간 세션 모델 전환은 요청된 모델이 허용 목록에 의해 제외될 때 거부됩니다. 세션 생성 시 서버 측 거부는 availableModels 설정 키가 아닌 조직 모델 제한에 적용됩니다.
  • Cowork는 Claude Desktop 앱의 에이전트 작업 탭이며, 설계상 claude.ai 관리 콘솔에서 서버 관리 설정을 수신하지 않습니다. 관리형 설정 파일은 세션이 실행되는 위치에 있을 때 Cowork 세션에 적용됩니다. 원격 Cowork 세션은 Anthropic 관리 VM에서 실행되며, 여기서 장치 배포 파일은 없습니다.
  • Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 그리고 Claude Platform on AWS와 같은 타사 제공자의 세션은 서버 관리 설정을 수신하지 않으므로 MDM 또는 관리형 설정 파일을 통해 허용 목록을 전달합니다.
  • 서버 관리 전달은 또한 세션이 적격 로그인 또는 키로 인증하도록 요구합니다. apiKeyHelper 스크립트를 통해서만 키를 생성하는 플릿은 MDM 또는 관리형 설정 파일을 통해 허용 목록을 전달해야 합니다.
  • Desktop Code 탭은 또한 SSH 세션을 호스팅하며, 이는 실행되는 원격 호스트에서 관리형 설정 파일을 읽습니다. Desktop 관리형 설정을 참조하세요.
  • claude.ai 및 Desktop 앱의 모델 선택기는 조직의 허용 목록에 의해 제외된 모델을 숨기거나 회색으로 표시합니다. 선택기 상태는 사용자를 위한 편의입니다. 적용은 세션에서 발생합니다.

기본 모델 동작

자체적으로 availableModels는 enforceAvailableModels도 설정할 때까지 Default 옵션을 시스템의 런타임 기본값에 남겨둡니다. 해당 기본값이 제한하려는 모델이면 enforceAvailableModels도 설정하세요.

빈 availableModels 배열은 Default 모델 적용을 절대 활성화하지 않습니다: availableModels: []을 사용하면 명명된 모델 선택은 차단되지만 계정 유형의 Default 모델은 enforceAvailableModels에 관계없이 사용 가능합니다.

Default 모델에 대한 허용 목록 적용

관리형 설정에서 비어있지 않은 availableModels와 함께 enforceAvailableModels: true를 설정하여 허용 목록을 Default 옵션으로 확장합니다. 이는 Claude Code v2.1.175 이상이 필요합니다.

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

Default 옵션은 계정 유형 기본값으로 해석되거나, 관리자가 설정한 경우 조직 기본 모델로 해석됩니다. 해당 모델이 허용 목록에 없으면, Default 옵션은 대신 허용되고 사용 가능한 모델을 이름 지은 첫 번째 availableModels 항목으로 해석되며, /model 선택기의 Default 행은 해당 모델을 표시합니다. 이는 기본값에 도달하는 모든 곳에 적용됩니다: 세션 시작, /model에서 Default 선택, 폴백 모델 체인의 "default" 키워드, 그리고 제외된 선택이 삭제될 때 사용되는 폴백.

enforceAvailableModels는 availableModels가 비어있지 않을 때만 Default 옵션을 재매핑합니다. availableModels: []을 사용하면 계정 유형의 Default 모델은 사용 가능하므로 설정이 사용자를 모든 모델에서 잠글 수 없습니다. availableModels가 비어있지 않지만 허용되고 사용 가능한 모델을 이름 지은 항목이 없으면, 적용은 건너뛰고 Default는 --debug 아래에서만 표시되는 경고와 함께 계정 유형 기본값으로 해석됩니다. 이를 피하려면 목록에 최소한 하나의 보장된 사용 가능 항목을 유지하세요.

전달하는 최상위 순위 관리형 소스에 두 키를 함께 배포합니다. 기본적으로 Claude Code는 해당 소스만 읽으므로 관리형 설정 파일에 배치된 쌍은 관리 콘솔이 설정을 전달할 때 무시됩니다. Claude Code가 관리형 소스를 결합하는 방식의 옵트인 병합에서 Claude Code는 여전히 availableModels를 설정하는 소스 아래에 순위가 지정된 소스의 modelOverrides 맵을 무시합니다.

사용자가 실행하는 모델 제어

model 설정은 초기 선택이지 적용이 아닙니다. 세션이 시작될 때 활성 모델을 설정하지만 사용자는 여전히 /model을 열고 Default를 선택할 수 있으며, 이는 enforceAvailableModels이 리디렉션하지 않는 한 model이 설정된 것에 관계없이 시스템의 런타임 기본값으로 해석됩니다.

모델 경험을 완전히 제어하려면 이러한 설정을 결합하세요:

  • availableModels: 사용자가 전환할 수 있는 명명된 모델을 제한합니다
  • enforceAvailableModels: availableModels 허용 목록을 Default 옵션으로 확장하므로 Default는 목록 외부의 모델로 해석될 수 없습니다
  • model: 세션이 시작될 때 초기 모델 선택을 설정합니다
  • ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL / ANTHROPIC_DEFAULT_FABLE_MODEL: sonnet, opus, haiku, 그리고 fable 별칭이 해석되는 것을 제어하고 계정 유형 기본값이 사용하는 버전을 제어합니다

이 예제는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet 및 Haiku로 제한하며, Default가 계정 유형 기본값이 아닌 허용 목록의 모델로 해석되도록 합니다:

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "enforceAvailableModels": true,
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

enforceAvailableModels 또는 env 블록이 없으면, 선택기에서 Default를 선택하는 사용자는 model에 고정된 버전이 아닌 런타임 기본값을 얻습니다. 두 설정은 다른 범위를 다룹니다: enforceAvailableModels는 Default가 허용 목록을 따르도록 하고, env 블록은 sonnet과 같은 허용된 별칭이 해석되는 버전을 고정합니다. 모델 패밀리 제한이 충분할 때 enforceAvailableModels만 사용하세요. 특정 버전을 고정해야 할 때도 env 블록을 추가하세요.

병합 동작

Claude Code가 적용하는 관리형 설정이 availableModels를 정의할 때, 해당 목록만 적용되며, 자체 목록을 제공하는 호스트 플랫폼 제외: 사용자, 프로젝트 또는 로컬 설정의 항목은 이를 확장할 수 없으며, Claude Code는 관리형 소스 전체에서 availableModels를 병합하지 않습니다. Claude Code가 관리형 소스를 결합하는 방식에서 어느 소스의 목록이 적용되는지 설명합니다. 그렇지 않으면 사용자, 프로젝트 및 로컬 설정의 목록은 다른 배열 설정처럼 연결되고 중복 제거됩니다. Claude Code v2.1.175 이전에는 낮은 우선순위 범위의 항목이 대체되지 않고 관리형 목록으로 병합되었습니다.

유효한 목록 내에서 패밀리의 특정 모델을 이름 지은 항목(버전 접두사 또는 전체 모델 ID 여부)은 해당 패밀리의 와일드카드 항목을 비활성화합니다: ["sonnet", "claude-sonnet-4-5"]는 모든 Sonnet 모델이 아닌 Sonnet 4.5 버전만 허용합니다.

Mantle 모델 ID

Amazon Bedrock Mantle 엔드포인트가 활성화되면, availableModels의 anthropic.으로 시작하는 항목이 /model 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 타사 배포를 위한 모델 고정에서 설명한 별칭 일치의 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하며, Mantle ID는 패밀리 이름을 포함하므로 특정 항목으로 계산되고 해당 패밀리의 와일드카드를 비활성화합니다: 모든 Mantle ID와 함께 유지하려는 버전 접두사 또는 전체 ID를 나열합니다. 병합 동작을 참조하세요.

조직 모델 제한

Claude Enterprise 플랜의 조직 관리자는 claude.ai 관리 콘솔에서 개별 모델을 비활성화하여 구성원이 실행할 수 있는 모델을 제한합니다. 이 제한은 설정의 availableModels 목록과 별도로 Claude Code가 인증할 때 계정의 자격과 함께 전달되며, 서버는 세션이 생성될 때 동일한 제한을 독립적으로 적용합니다. Claude Code v2.1.187 이상이 필요합니다.

제한은 구성원이 로그인하거나 자신의 API 키를 사용할 때 적용됩니다. 조직 서비스 키와 같은 조직 범위 자격증명은 사용자와 연결되지 않으므로 제한이 적용되지 않습니다.

Claude Console에는 모델 제한 제어가 없습니다. Claude Enterprise 플랜이 없는 조직(Anthropic API를 통해 인증하는 구성원을 포함)은 관리형 설정에서 availableModels를 사용하여 모델을 제한하고, Default 옵션을 다루기 위해 enforceAvailableModels를 추가합니다. 이러한 설정은 서버가 아닌 Claude Code 자체에 의해 적용됩니다.

제한된 모델은 /model 선택기에서 숨겨집니다. --model, ANTHROPIC_MODEL 환경 변수, 또는 model 설정으로 이름으로 선택하면 Model "<name>" is restricted by your organization's settings. Using <model> instead. 공지를 표시하고 세션은 허용된 모델에서 시작됩니다. 제한된 모델에 대해 /model <name>을 입력하면 Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.로 거부되고 세션은 현재 모델을 유지합니다.

opus와 같은 모델 패밀리 별칭은 조직이 허용할 때 일반적인 모델로 해석됩니다. 조직이 해당 모델을 제한할 때, Claude Code는 조직이 허용하는 패밀리의 최신 버전으로 대체하며 동일한 대체 공지를 표시합니다. /model <alias>는 패밀리의 모든 버전이 제한될 때만 거부됩니다. --model, ANTHROPIC_MODEL, 또는 model 설정으로 설정된 별칭은 여전히 시작 시 대체됩니다. v2.1.205 이전에는 패밀리 별칭이 최신 릴리스 버전만을 기반으로 대체되거나 거부되었으며, 이전 버전이 허용되었을 때도 마찬가지였습니다.

제한은 조직 전체 또는 역할별로 적용됩니다:

  • 조직 수준에서 모델을 비활성화하면 모든 구성원에게서 제거됩니다.
  • 역할 수준 액세스는 다양한 사용자 정의 역할에 다양한 모델을 부여하며, 여러 역할을 보유한 구성원은 자신의 역할 중 하나가 부여하는 모든 모델을 사용할 수 있습니다.
  • Haiku 모델은 항상 사용 가능하며 비활성화할 수 없으므로 모든 구성원은 최소한 하나의 사용 가능한 모델을 유지합니다.
  • 액세스 변경은 약 1분 내에 새 요청에 적용됩니다. /model 선택기는 다음 세션이 시작될 때 이를 반영합니다.

두 제한이 함께 적용됩니다: 모델은 availableModels에 의해 허용되고 조직에 의해 제한되지 않을 때만 선택 가능합니다. 조직 제한은 Anthropic API 및 LLM 게이트웨이 배포의 세션에만 도달합니다. 다른 제공자에서는 대신 availableModels를 사용하세요.

조직 기본 모델

Claude Enterprise 플랜의 조직 관리자는 claude.ai 관리 콘솔에서 전체 조직 또는 사용자 정의 역할별로 Claude Code 멤버의 기본 모델을 설정할 수 있습니다. 기본 모델이 설정되면 기본값 옵션이 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다.

/model 선택기의 기본값 행에는 조직 기본값의 이름이 Org default 레이블과 함께 표시됩니다. 관리자가 전체 조직에 대해 기본값을 설정했는지 또는 역할에 대해 설정했는지 여부에 관계없이 레이블은 Org default로 표시됩니다. 역할 기본값은 해당 사용자 정의 역할의 멤버를 포함하며 조직 전체 기본값보다 우선합니다. 여러 역할이 서로 다른 기본값을 설정한 경우 가장 성능이 우수한 모델이 적용됩니다.

조직 기본값은 시작점이지 제한이 아닙니다. 다음 선택 항목이 이를 우선합니다.

  • --model 플래그 및 ANTHROPIC_MODEL 환경 변수
  • 관리 설정에서 제공되거나 --settings를 통해 제공되는 model 값
  • 사용자, 프로젝트 또는 로컬 설정의 model 값(예: /model로 저장한 모델 포함)

관리자는 조직 기본값을 구성하여 사용자 선택을 재정의할 수도 있습니다. 재정의가 활성화되면 사용자, 프로젝트 및 로컬 설정의 model 값보다 우선하므로 /model로 저장한 모델은 현재 세션에 적용되고 다음 시작 시 조직 기본값으로 돌아갑니다. 선택 항목이 다를 경우 /model은 Your organization's default (<model>) applies on restart를 표시합니다. --model 플래그, ANTHROPIC_MODEL, 관리 설정 및 --settings는 재정의가 활성화된 경우에도 계속 우선합니다. 재정의는 제한된 조직 집합에서만 사용 가능합니다. 가용성에 대해 Anthropic 계정 팀에 문의하세요.

멤버가 선택할 수 있는 모델을 제한하려면 조직 모델 제한 또는 availableModels를 대신 사용하세요.

Claude Code는 시작 시 조직 기본값을 한 번만 읽으므로 관리자가 세션 중에 변경한 기본값은 다음 시작 시 적용됩니다.

조직 기본값이 사용자 선택을 재정의하지 않을 경우, 관리자가 변경한 후 첫 번째 대화형 시작 시 사용자 설정에서 model 키를 한 번 지워서 새 기본값이 적용되도록 합니다. 파일의 다른 항목은 변경하지 않으며, 해당 시작 후 /model로 저장한 모델은 유지됩니다.

조직 기본값은 채택되기 전에 다음 제한 확인을 통과합니다.

  • availableModels는 자체적으로 조직 기본값에 적용되지 않으므로 허용 목록 외부의 조직 기본값도 계속 적용됩니다. enforceAvailableModels도 설정된 경우, 허용 목록 외부의 조직 기본값은 다른 기본값처럼 첫 번째 허용 목록 항목으로 다시 매핑됩니다.
  • 조직 모델 제한이 계정에 대해 거부하는 조직 기본값은 해당 제품군의 최신 허용 모델로 바뀌거나, 모든 버전이 제한된 경우 더 저렴한 제품군으로 바뀝니다.
  • 계정에서 전혀 사용할 수 없는 조직 기본값은 건너뛰고, 기본값 옵션은 조직 기본값 없이 확인되는 것처럼 확인됩니다.

v2.1.199부터 조직 기본값이 계정 유형의 일반적인 기본값과 다른 모델 제품군인 경우, /model 선택기는 해당 일반적인 제품군에 대해 별도의 행을 유지하므로 세션에 대해 계속 전환할 수 있습니다. v2.1.196부터 v2.1.198까지는 해당 행이 선택기에서 누락됩니다.

조직 기본값은 Anthropic API로 인증된 세션에만 도달합니다. LLM gateway 배포를 포함하여 다른 곳에서 기본값을 설정하려면 관리 설정에서 model 키를 대신 사용하세요.

조직 노력 제한

Claude Enterprise 플랜의 조직 관리자는 각 사용자 정의 역할에 대해 모델별 최대 노력 수준을 설정할 수 있으며, 역할 수준의 조직 모델 제한과 함께 설정할 수 있습니다. 상한선을 초과하는 수준은 /effort 선택기에서 제공되지 않으며, --effort 또는 /effort로 더 높은 수준을 지정하면 상한선에서 실행됩니다. 대화형 세션 및 일반 텍스트 --print 실행에서는 요청된 수준과 적용된 수준을 명시하는 경고가 표시되며, json 또는 stream-json 출력이거나 백그라운드 에이전트에서는 제한이 자동으로 적용됩니다. 상한선은 모델별이므로 모델을 전환하면 사용 가능한 수준이 변경될 수 있습니다. 여러 역할이 동일한 모델을 부여하는 경우 가장 제한이 적은 상한선이 적용됩니다. Claude Code v2.1.195 이상이 필요합니다.

노력 제한은 조직 모델 제한과 함께 전달되며 동일한 세션에 도달합니다.

특수 모델 동작

`default` 모델 설정

default의 동작은 계정 유형에 따라 달라집니다:

  • Max, Team Premium, Enterprise, Anthropic API: Opus 5로 기본 설정됨
  • AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform: Opus 5로 기본 설정됨
  • Pro 및 Team Standard: Sonnet 5로 기본 설정됨
  • Microsoft Foundry: Sonnet 4.5로 기본 설정됨

v2.1.219 이전에는 default가 Anthropic API에서 Opus 4.8로, v2.1.154부터 Max, Team Premium, Enterprise 종량제에서 Opus 4.8로, v2.1.207부터 AWS의 Claude Platform, Amazon Bedrock, Google Cloud의 Agent Platform에서 Opus 4.8로 확인되었습니다. v2.1.207 이전에는 default가 AWS의 Claude Platform에서 Opus 4.7로, Amazon Bedrock 및 Google Cloud의 Agent Platform에서 Sonnet 4.5로 확인되었습니다.

관리자가 조직 기본 모델을 설정한 경우, default는 위의 계정 유형 기본값 대신 해당 모델로 확인됩니다. Claude Code v2.1.196 이상이 필요합니다. default는 ANTHROPIC_DEFAULT_MODEL로 설정한 모델로도 확인될 수 있으며, 해당 섹션에 나열된 조건 하에서 확인됩니다.

관리되는 설정이 기본 모델에 대한 허용 목록 적용을 강제하고 계정 유형 기본값이 availableModels에 없는 경우, default는 위의 계정 유형 기본값 대신 강제된 기본값으로 확인됩니다. 둘 다 적용되는 경우, 조직 기본값이 먼저 계정 유형 기본값을 대체하고 강제 적용이 이에 적용됩니다: 허용 목록에 있는 조직 기본값은 유지되고, 목록 외의 값은 강제된 기본값으로 확인됩니다.

Fable 모델은 어떤 플랜이나 제공자에서도 계정 유형 기본값이 아닙니다. /model로 선택하면 사용자 설정에서 선택된 모델로 저장되므로 이후 세션이 이 모델에서 시작됩니다. v2.1.257에서 Claude Code가 저장된 Fable 5 선택에 대해 수행하는 일회성 변경에 대해서는 Fable 작업을 참조하세요.

`opusplan` 모델 설정

opusplan 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:

  • 계획 모드에서: 복잡한 추론 및 아키텍처 결정을 위해 opus 사용
  • 실행 모드에서: 코드 생성 및 구현을 위해 자동으로 sonnet으로 전환

이는 계획을 위한 Opus의 추론과 실행을 위한 Sonnet의 효율성을 결합합니다.

계획 모드 Opus 단계는 opus 모델 설정과 동일한 컨텍스트 윈도우를 사용합니다. Opus가 자동으로 1M 컨텍스트로 업그레이드되는 구독 계층에서 opusplan은 계획 모드에서도 업그레이드를 받습니다. 자동 업그레이드 계층이 아닌 경우 두 단계 모두에 1M 컨텍스트를 강제하려면 모델을 opusplan[1m]으로 설정하세요.

availableModels가 최신 Opus를 제외하지만 ["sonnet", "claude-opus-4-6"]과 같은 이전 버전을 허용하는 경우, opusplan은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외된 경우에만 Sonnet에만 유지됩니다. 계획 모드에서 일반적으로 Sonnet으로 업그레이드되는 Haiku 세션은 마찬가지로 허용된 최신 Sonnet을 사용하고, 모든 Sonnet이 제외된 경우에만 Haiku에만 유지됩니다. v2.1.205 이전에는 허용 목록이 이전 버전을 허용했더라도 업그레이드 제품군의 최신 버전이 제외되면 계획 모드가 세션의 모델에 유지되었습니다.

이전 허용 버전의 대체는 Anthropic API 및 AWS의 Claude Platform에 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Mantle에서는 배포가 제공자별 모델 ID를 사용하므로 업그레이드 모델이 제외되면 계획 모드가 세션의 모델에 유지됩니다.

Claude가 계획 경계에서 전환하는 대신 작업 중간에 두 번째 모델을 참조할 시기를 결정하는 하이브리드 접근 방식은 advisor tool을 참조하세요.

폴백 모델 체인

주 모델이 과부하 상태이거나 사용 불가능하거나 다른 재시도 불가능한 서버 오류를 반환할 때, Claude Code는 요청이 실패하는 대신 폴백 모델로 전환할 수 있습니다. 인증, 청구, 속도 제한, 요청 크기, 전송 오류 및 조직의 정책 확인에 의한 거부는 전환을 트리거하지 않습니다. 이들은 정상적인 재시도 및 오류 처리를 따릅니다.

하나 이상의 폴백 모델을 구성하고 Claude Code는 순서대로 시도하며, 전환할 때 알림을 표시합니다. 전환은 현재 턴에만 지속되므로 다음 메시지는 주 모델을 먼저 다시 시도합니다. Claude Code는 중복 제거 후 체인을 3개 모델로 제한하고 추가 항목을 무시합니다.

--fallback-model 플래그로 한 세션에 대한 체인을 설정하며, 이는 쉼표로 구분된 목록을 허용합니다:

claude --fallback-model sonnet,haiku

세션 전체에 체인을 유지하려면 설정에서 fallbackModel을 배열로 설정하세요:

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

--fallback-model 플래그는 fallbackModel 설정보다 우선합니다. 각 항목은 모델 이름 또는 별칭을 허용하며, "default"는 기본 모델로 확장됩니다.

Claude Code는 시작 시 체인을 확인하지 않으며 /status는 이를 표시하지 않습니다. 전환이 발생할 때 표시되는 알림이 폴백이 구성되었다는 첫 번째 눈에 띄는 신호입니다.

요청이 실패하면 Claude Code는 하나가 이를 수락할 때까지 순서대로 각 항목을 시도합니다. 설정에 고정된 폐기된 모델과 같이 도달할 수 없는 항목도 동일한 방식으로 다음 항목으로 폴백됩니다. Claude Code는 해당 이동을 시작하기 전에 두 가지 종류의 항목을 제거합니다:

  • 허용 목록 외: Claude Code는 체인을 읽을 때 availableModels에서 허용하지 않는 항목을 삭제합니다.
  • 압축 중 더 작은 컨텍스트 윈도우: 체인은 압축도 포함하지만, Claude Code는 주 모델보다 컨텍스트 윈도우가 작은 모델로 폴백하지 않습니다. 요약이 먼저 대화의 일부를 차단하기 때문입니다. 모든 폴백이 더 작으면 압축이 원래 오류를 표시하고 재시도할 수 있습니다.

Claude Code는 subagents에도 체인을 적용합니다. subagent의 요청이 실패하면 Claude Code는 순서대로 구성된 폴백 모델을 시도하고 subagent는 요청을 수락하는 모델에서 계속됩니다. 세션의 모델은 변경되지 않습니다. v2.1.247 이전에는 체인이 포함하는 실패가 subagent를 종료했습니다.

자동 모델 폴백

이 섹션은 Fable 모델 및 Opus 5의 콘텐츠 기반 폴백을 다룹니다. 모델이 과부하 상태이거나 사용 불가능할 때의 가용성 기반 폴백은 폴백 모델 체인을 참조하세요.

Fable 모델 및 Opus 5는 안전 분류기로 실행되며, 대부분 사이버 보안 및 생물학 콘텐츠에 플래그를 지정합니다. 분류기가 요청에 플래그를 지정하고 플래그된 카테고리에 폴백 모델이 있는 경우, Claude Code는 해당 모델에서 요청을 다시 실행하고 기록에 알림을 표시합니다. 이 두 카테고리의 경우 폴백 모델은 거부한 모델에 따라 달라집니다:

  • Fable 5.1 및 Fable 5: 생물학 플래그 요청은 Opus 5에서 다시 실행되고, 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다.
  • Opus 5: 사이버 보안 플래그 요청은 Opus 4.8에서 다시 실행됩니다. 생물학 플래그 요청은 폴백 모델이 없기 때문에 거부로 끝나며, Opus 5는 자체 생물학 분류기를 실행합니다.

Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 Claude Code는 배포를 통해 이러한 대상을 확인하고, ANTHROPIC_DEFAULT_OPUS_MODEL을 설정하면 폴백이 있는 카테고리가 고정된 모델에서 다시 실행됩니다. Bedrock, Agent Platform, Foundry에서 폴백 활성화를 참조하세요.

폴백 후 세션은 폴백 모델에서 계속됩니다. 원래 모델로 돌아가려면 /model을 실행하세요.

카테고리 기반 폴백에는 Claude Code v2.1.219 이상이 필요합니다. v2.1.219 이전에는 모든 플래그된 Fable 5 요청이 제공자의 기본 Opus 모델에서 다시 실행되었고, Opus 5는 폴백 소스가 아니었습니다.

폴백 모델은 availableModels에 대해 확인됩니다. 차단되면 폴백이 발생하지 않습니다. 거부는 정상 오류로 표시되고 세션의 모델은 변경되지 않습니다.

폴백을 트리거한 것 확인

폴백은 세션의 첫 번째 요청에서 트리거될 수 있으며, 이는 비정상적인 것을 보내기 전입니다. 첫 번째 요청은 CLAUDE.md 콘텐츠 및 git 상태와 같은 작업 공간 컨텍스트를 전달하기 때문입니다. 보안 또는 생물학 자료를 포함하는 저장소는 해당 컨텍스트만으로 분류기를 트리거할 수 있습니다.

사용자 정의가 트리거인지 확인하려면 claude --safe-mode로 세션을 시작하세요. 이는 CLAUDE.md, 스킬, MCP 서버, 훅과 같은 사용자 정의를 비활성화합니다. Git 상태 및 디렉토리 이름은 사용자 정의가 아니며 여전히 포함됩니다.

전환 전에 요청

요청이 플래그될 때마다 자동으로 전환하는 대신 어떤 일이 발생할지 결정하려면 /config를 실행하고 메시지가 플래그될 때 모델 전환을 끄거나 설정 파일에서 switchModelsOnFlag를 false로 설정하세요. 플래그된 요청은 세션을 일시 중지하고 두 가지 옵션을 제공합니다: 폴백 모델로 전환하거나 프롬프트를 편집하고 현재 모델에서 재시도합니다.

일부 경우는 다르게 동작합니다:

  • 플래그된 카테고리에 폴백 모델이 없는 경우(예: Opus 5의 생물학 플래그), Claude Code는 프롬프트를 표시하지 않으며 요청은 거부로 끝납니다.
  • 두 모델이 동일한 요청에 플래그를 지정하면 프롬프트를 편집하고 재시도하거나 새 세션을 시작할 수 있습니다.
  • 모바일 웹의 Claude Code 세션에서는 편집 및 재시도가 지원되지 않습니다. 모델을 전환하거나 데스크톱 브라우저 또는 데스크톱 앱에서 세션을 계속하세요.
  • 비대화형 모드 및 프롬프트를 표시할 수 없는 SDK 통합에서 플래그된 요청은 거부로 턴을 종료합니다.
  • 폴백 대상이 availableModels에 의해 차단되면 Claude Code는 프롬프트를 표시하지 않습니다. 플래그된 요청은 거부로 끝나며, 대상이 차단될 때 자동 폴백과 동일합니다.

Bedrock, Agent Platform, Foundry에서 폴백 활성화

Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 모델 ID는 제공자별이므로 자동 폴백은 Claude Code가 관련된 두 모델을 식별할 수 있을 때만 작동합니다:

  • Claude Code는 현재 모델을 폴백 소스로 인식해야 합니다. Fable 5.1 및 Fable 5는 모델 ID에 claude-fable-5가 포함되거나, ANTHROPIC_DEFAULT_FABLE_MODEL의 값과 일치하거나, modelOverrides로 매핑될 때 인식됩니다. Opus 5는 제공자 모델 ID 또는 modelOverrides 매핑으로 인식됩니다.
  • 폴백 모델은 배포에서 확인되어야 합니다. ANTHROPIC_DEFAULT_OPUS_MODEL을 설정하면 플래그된 요청이 폴백이 있는 모든 카테고리에 대해 해당 모델에서 다시 실행됩니다. Opus 5의 생물학 플래그는 여전히 거부로 끝납니다. 설정하지 않으면 사이버 보안 플래그 요청이 제공자의 모델 목록에서 Opus 4.8 항목에서 다시 실행되고, Fable 모델의 생물학 플래그 요청이 Opus 5 항목에서 다시 실행됩니다.

모델을 식별할 수 없으면 Claude Code는 자동으로 전환하지 않습니다. 플래그된 요청은 거부 메시지로 끝나고 /model로 모델을 전환하고 재시도할 수 있습니다. ANTHROPIC_DEFAULT_FABLE_MODEL을 Fable 모델 ID로 설정하면 Fable 인식이 활성화됩니다. ANTHROPIC_DEFAULT_OPUS_MODEL을 Opus 모델 ID로 설정하면 플래그된 카테고리에 폴백 대상이 제공되며, 핀이 Opus 제품군 외의 모델 또는 거부한 모델을 지정하지 않는 한 Claude Code는 전환하지 않으며 거부가 유지됩니다.

보안 연구 및 생물학 워크로드

공격적인 보안 또는 생물학의 워크로드(침투 테스트, Capture the Flag(CTF) 연습, 생물학 인접 코드베이스 포함)는 자주 폴백을 트리거하며, 종종 첫 번째 요청에서 트리거됩니다. Fable 5.1 또는 Fable 5의 실질적인 생물학 작업의 경우, Claude Code는 첫 번째 플래그된 요청에서 세션을 Opus 5로 이동하고, 이후 생물학 플래그 요청은 Opus 5에서 거부로 끝나며, Opus 5는 생물학 폴백이 없기 때문입니다. Opus 5에서는 첫 번째 플래그된 요청부터 이러한 거부를 받습니다.

이는 이러한 도메인에 대한 예상 라우팅이며 계정 플래그가 아닙니다. 조직이 이 작업을 위해 Fable 클래스 기능이 필요한 경우 Anthropic 계정 팀에 신뢰할 수 있는 액세스 프로그램에 대해 문의하세요.

노력 수준 조정

노력 수준은 적응형 추론을 제어하며, 이를 통해 모델은 작업 복잡성에 따라 각 단계에서 생각할지 여부와 얼마나 생각할지 결정할 수 있습니다. 낮은 노력은 간단한 작업에 더 빠르고 저렴하지만, 높은 노력은 복잡한 문제에 더 깊은 추론을 제공합니다.

사용 가능한 노력 수준은 모델에 따라 다릅니다. 여기에 나열되지 않은 모델은 노력을 지원하지 않습니다:

모델 수준
Fable 5.1 및 Fable 5 low, medium, high, xhigh, max
Opus 5, Sonnet 5, Opus 4.8, Opus 4.7 low, medium, high, xhigh, max
Opus 4.6 및 Sonnet 4.6 low, medium, high, max

활성 모델이 지원하지 않는 수준을 설정하면 Claude Code는 설정한 수준 이하의 지원되는 최고 수준으로 폴백합니다. 예를 들어 xhigh는 Opus 4.6에서 high로 실행됩니다. 조직은 모델에 사용 가능한 수준을 제한할 수도 있습니다. 조직 노력 제한을 참조하세요.

ultracode 설정이 꺼져 있으면 Claude Code는 세션의 노력 수준을 이 순서로 확인하며, 적용되는 첫 번째를 사용합니다:

  1. 명시적 선택: CLAUDE_CODE_EFFORT_LEVEL 환경 변수, --effort로 시작, 또는 세션의 /effort (비대화형 /effort는 더 좁은 효과를 가짐)
  2. 모델의 기본 노력, Fable 5, Opus 4.8, Opus 4.7에서: 이러한 모델 중 하나를 처음 실행할 때부터 Claude Code는 설정이 다른 수준을 확인하더라도 해당 모델의 기본 노력을 세션 전체에 유지합니다. Opus 5 및 Fable 5.1은 이러한 유지가 없습니다. 설정한 수준이 유지를 종료하는지 여부는 설정 방법에 따라 다릅니다. 예를 들어:
    • 유지 종료: /effort 슬라이더에서 Enter로 대화형으로 수준을 확인하거나 /model 선택기에서 또는 /effort 후에 입력한 수준으로, 또는 연결된 장치의 원격 제어 노력 제어에서 수준을 선택
    • 이후 세션을 위해 유지 유지: 시작 시 --effort, 또는 /effort 슬라이더 또는 /model 선택기에서 s
  3. 설정: 모델에 대해 저장한 수준 또는 effortLevel 키, 설정 파일 간 우선순위는 modelSettings에 명시됨
  4. 모델의 기본 노력: 노력을 지원하는 모든 모델에서 high, Opus 4.7은 xhigh로 기본값, 조직이 조직 기본 모델에 대한 기본 노력 수준을 설정할 때 해당 모델을 실행할 때 해당 수준이 기본값

기계에서 대화형 세션에서 low, medium, high, xhigh를 설정할 때 확인 방법으로 지속 기간을 선택합니다:

  • /effort 슬라이더 또는 /model 선택기에서 Enter, 또는 /effort 후에 입력한 수준: 수준을 기본값으로 저장하고 이후 세션에 적용
  • /effort 슬라이더 또는 /model 선택기에서 s: 이 세션에만 수준을 적용합니다. Claude Code v2.1.257 이상이 필요합니다.

Claude Code는 사용자 설정의 modelSettings 키 아래 모델별로 수준을 저장하므로 각 모델은 자체 저장된 수준을 유지합니다.

max는 가장 깊은 추론 수준입니다. CLAUDE_CODE_EFFORT_LEVEL 환경 변수를 통해 설정하지 않는 한 Claude Code는 max를 현재 세션에만 적용합니다.

-p 실행에서 /effort로 수준을 설정할 때 Claude Code는 이를 해당 세션에만 적용하고 기본값으로 저장하지 않습니다. Fable 5, Opus 4.8, Opus 4.7에서 해당 수준은 모델의 기본 노력에 대한 유지를 종료하거나 세션에 대해 재정의하지도 않습니다. 해당 유지가 적용되는 동안 비대화형 /effort는 Not applied를 보고하므로 대신 시작 시 --effort를 전달하세요.

/effort 메뉴는 또한 ultracode를 제공합니다. Ultracode는 모델 노력 수준이 아닌 Claude Code 설정입니다: 모델에 xhigh를 보내고 추가로 Claude가 실질적인 작업에 대해 동적 워크플로우를 조율하도록 합니다. 지속적으로 설정할 수 있는 위치는 ultracode 설정을 참조하세요.

다음 중 하나를 통해 ultracode를 켤 수 있습니다:

  • /effort: /effort ultracode를 실행하거나 메뉴에서 선택
  • --effort 플래그: claude --effort ultracode로 시작하여 xhigh 노력으로 세션을 시작하고 ultracode를 켭니다.
  • ultracode 설정: 설정 파일에서 "ultracode": true를 설정하거나 --settings를 사용하거나 Agent SDK 제어 요청에서 설정합니다. applyFlagSettings() 요청도 effortLevel: "ultracode"를 허용합니다.
  • /model 선택기: 모델을 선택하는 동안 화살표 키로 노력 슬라이더를 ultracode로 이동합니다. Claude Code는 해당 모델을 기본값으로 저장할 때도 현재 세션에 대해 켭니다.

--effort 플래그 또는 Agent SDK effortLevel 값에 ultracode를 전달하려면 Claude Code v2.1.203 이상이 필요합니다. v2.1.203 이전에는 --effort ultracode가 Unknown --effort value 'ultracode'를 인쇄했고 세션이 기본 노력으로 시작되었습니다.

지속된 effortLevel 설정 및 CLAUDE_CODE_EFFORT_LEVEL 환경 변수는 ultracode를 허용하지 않습니다. CLAUDE_CODE_EFFORT_LEVEL이 xhigh 이외의 수준으로 설정되면 요청이 해당 수준에서 실행되고 ultracode의 워크플로우 조율은 비활성 상태로 유지됩니다. Ultracode를 선택하면 환경 변수가 세션의 노력을 재정의한다는 경고가 표시됩니다.

Ultracode를 사용할 수 없을 때(예: 워크플로우가 꺼져 있을 때), --effort ultracode는 xhigh 노력만 설정합니다.

노력 수준 선택

각 수준은 토큰 지출을 기능에 대해 교환합니다. 기본값은 대부분의 코딩 작업에 적합합니다. 다른 균형을 원할 때 조정하세요.

수준 사용 시기
low 짧고 범위가 정해진 지연 시간에 민감하지만 지능에 민감하지 않은 작업을 위해 예약
medium 일부 지능을 교환할 수 있는 비용에 민감한 작업의 토큰 사용 감소
high 토큰 사용과 지능의 균형. Opus 4.7을 제외한 모든 모델의 기본값
xhigh 더 높은 토큰 지출로 더 깊은 추론. Opus 4.7의 기본값
max 까다로운 작업의 성능을 개선할 수 있지만 수익 감소를 보일 수 있으며 과도한 생각이 발생하기 쉽습니다. 광범위하게 채택하기 전에 테스트하세요.
ultracode 각 실질적인 작업에 대해 xhigh 메시지별 추론으로 동적 워크플로우를 계획하는 Claude Code 설정

노력 척도는 모델별로 보정되므로 동일한 수준 이름이 모델 전체에서 동일한 기본 값을 나타내지 않습니다.

일회성 깊은 추론을 위해 ultrathink 사용

프롬프트의 어디든 ultrathink를 포함하여 해당 턴에서 더 깊은 추론을 요청하세요. 세션 노력 설정을 변경하지 않습니다. Claude Code는 키워드를 인식하고 컨텍스트 내 지시를 추가합니다. API로 전송된 노력 수준은 변경되지 않습니다. Claude Code는 "think", "think hard", "think more"와 같은 다른 구문을 일반 프롬프트 텍스트로 전달하고 키워드로 인식하지 않습니다.

노력 수준 설정

다음 중 하나를 통해 노력을 변경할 수 있습니다:

  • /effort: 인터랙티브 슬라이더를 열려면 인수 없이 /effort를 실행하거나, 직접 설정하려면 수준 이름 뒤에 /effort를 실행하거나, 활성 모델에 대해 저장된 수준을 지우려면 /effort auto를 실행하세요. Claude가 작업 중일 때 실행할 수 있으며, Claude Code가 캐시 경고를 표시하면 확인한 후 Claude Code는 새 수준을 턴의 다음 요청에 적용합니다.
  • /model에서: 모델을 선택할 때 좌우 화살표 키를 사용하여 노력 슬라이더를 조정합니다.
  • --effort 플래그: Claude Code를 시작할 때 단일 세션에 대해 설정하려면 수준 이름을 전달합니다.
  • 환경 변수: CLAUDE_CODE_EFFORT_LEVEL을 수준 이름 또는 auto로 설정합니다.
  • 설정: modelSettings에서 모델별 수준을 설정하거나, effortLevel을 low, medium, high, xhigh로 설정하여 모델 없는 모델의 기본값으로 설정합니다. max는 두 키에서 허용되지 않으며, ultracode는 자체 ultracode 키를 가집니다.
  • 연결된 장치에서: 원격 제어 세션에서 전화 또는 브라우저의 노력 제어에서 수준을 선택합니다. 수준은 현재 세션에만 적용되지만 모델의 기본 노력에 대한 유지도 종료합니다. Claude Code v2.1.234 이상이 필요합니다.
  • 스킬 및 subagent frontmatter: 스킬 또는 subagent markdown 파일에서 effort를 설정하여 해당 스킬 또는 subagent가 실행될 때 노력 수준을 재정의합니다.

Frontmatter 노력은 해당 스킬 또는 subagent가 활성화될 때 적용되며, 세션 수준을 재정의하지만 환경 변수는 재정의하지 않습니다.

관리되는 설정의 effortLevel 키는 시작 기본값이지 강제가 아닙니다: 사용자는 /effort 또는 --effort로 세션에 대해 변경할 수 있으며, 관리되는 값은 새 세션에서 기본값으로 다시 주장합니다.

노력 슬라이더는 지원되는 모델이 선택되면 /model에 나타납니다. 현재 노력 수준은 또한 모델 이름 옆의 세션 헤더에 표시됩니다. 예를 들어 "with low effort"이므로 /model을 열지 않고 어떤 설정이 활성화되어 있는지 확인할 수 있습니다. 바닥글은 또한 시작 시 및 변경 시 노력 수준을 간단히 표시합니다.

적응형 추론 및 고정 생각 예산

적응형 추론은 각 단계에서 생각을 선택 사항으로 만들므로 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 생각을 예약할 수 있습니다. 현재 수준이 생성하는 것보다 Claude가 더 자주 또는 덜 자주 생각하기를 원하면 프롬프트 또는 CLAUDE.md에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다.

Fable 모델, Sonnet 5, Opus 4.7 이상은 항상 적응형 추론을 사용합니다. 고정 생각 예산 모드 및 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING은 이들에게 적용되지 않습니다.

Opus 4.6 및 Sonnet 4.6에서 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1을 설정하여 MAX_THINKING_TOKENS로 제어되는 이전 고정 생각 예산으로 되돌릴 수 있습니다. 환경 변수를 참조하세요.

확장 생각

확장 생각은 Claude가 응답하기 전에 내보내는 추론입니다. 적응형 추론을 지원하는 모델에서 노력 수준은 얼마나 많은 생각이 발생하는지에 대한 주요 제어입니다. 아래 설정은 생각을 켜거나 끄고 표시 방법을 제어합니다. Anthropic API에서 생각이 꺼져 있으면 Claude Code는 해당 조합을 허용하지 않는 Opus 5와 같은 모델에 더 높은 수준 대신 노력 high를 보냅니다.

제어 설정 방법
현재 세션 토글 macOS에서 Option+T 또는 Windows 및 Linux에서 Alt+T 누르기
전역 기본값 설정 /config를 실행하고 생각 모드를 토글합니다. ~/.claude/settings.json에 alwaysThinkingEnabled로 저장됨
환경 변수를 통해 비활성화 MAX_THINKING_TOKENS=0을 설정하여 Anthropic API에서 Fable 모델을 제외한 생각을 끕니다. 타사 제공자에서 Claude Code는 thinking 매개변수를 생략하고 적응형 추론 모델은 여전히 생각할 수 있습니다. 다른 값은 고정 생각 예산에만 적용됩니다.

Fable 모델에서 생각을 끌 수 없습니다. 세션 토글, alwaysThinkingEnabled, MAX_THINKING_TOKENS=0은 효과가 없으며 Fable 모델은 노력 수준에 따라 단계별로 얼마나 생각할지 결정합니다.

Claude Code는 기본적으로 생각 출력을 축소합니다. 자세한 모드를 토글하고 회색 기울임꼴 텍스트로 추론을 보려면 Ctrl+O를 누르세요. Anthropic API의 대화형 세션은 기본적으로 수정된 생각 블록을 받으므로 확장할 때 전체 요약을 사용 가능하게 하려면 설정에서 showThinkingSummaries: true를 설정하세요. 축소되거나 수정되었을 때도 생성된 모든 생각 토큰에 대해 청구됩니다.

확장 컨텍스트

Fable 5.1, Fable 5, Sonnet 5, Opus 4.6 이상, Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 1백만 토큰 컨텍스트 윈도우를 지원합니다.

가용성은 모델 및 플랜에 따라 다릅니다. Anthropic API에서 Fable 5.1, Fable 5, Sonnet 5, Opus 4.7 이상은 기본적으로 1M 윈도우로 실행됩니다.

Max, Team, Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. Sonnet 4.6 with 1M 컨텍스트는 자동 업그레이드의 일부가 아니며 Max를 포함한 모든 구독 플랜에서 사용 크레딧이 필요합니다.

플랜 1M 컨텍스트가 있는 Opus 1M 컨텍스트가 있는 Sonnet 4.6
Max, Team, Enterprise 구독에 포함됨 사용 크레딧 필요
Pro 사용 크레딧 필요 사용 크레딧 필요
API 및 종량제 전체 액세스 전체 액세스

Claude Code는 Anthropic API에 직접 연결할 때만 이러한 플랜 요구 사항을 확인합니다. ANTHROPIC_BASE_URL을 LLM 게이트웨이로 지정하고 저장된 claude.ai 로그인이 활성 자격증으로 유지되면 Claude Code는 계정의 사용 크레딧을 확인하지 않습니다. /model의 [1m] 옵션은 사용 가능하게 유지되고 게이트웨이가 요청 성공 여부를 결정합니다. v2.1.229 이전에는 Claude Code가 계정의 사용 크레딧을 확인할 수 없을 때 해당 구성에서 /model sonnet[1m]을 거부했습니다.

1M 컨텍스트를 끄려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요. Claude Code는 모델 선택기에서 1M 모델 변형을 제거합니다. Sonnet 5 및 Fable 모델과 같은 기본 1M 윈도우가 있는 모델에서 모델을 200K 컨텍스트 윈도우로 취급합니다:

  • 자동 압축이 켜져 있으면 세션은 자동 압축을 통해 200K 경계에서 압축합니다. 자동 압축 윈도우를 200K 위로 설정해도 유지가 해제되지 않습니다. Claude Code는 해당 윈도우를 모델의 컨텍스트 윈도우로 제한하기 때문입니다.
  • 자동 압축이 꺼져 있으면 세션은 압축 대신 200K 경계에서 컨텍스트 제한 오류로 중지됩니다.

v2.1.223 이전에는 Claude Code가 Sonnet 5, Opus 4.8, Opus 5 세션만 200K로 유지했습니다. 환경 변수를 참조하세요.

1M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 확장 컨텍스트가 구독에 포함된 플랜의 경우 사용량은 구독으로 계속 적용됩니다. 확장 컨텍스트에 사용 크레딧을 통해 액세스하는 플랜의 경우 토큰은 사용 크레딧으로 청구됩니다.

계정이 1M 컨텍스트를 지원하면 최신 버전의 Claude Code에서 /model 선택기에 옵션이 나타납니다. 보이지 않으면 세션을 다시 시작해 보세요.

모델 별칭 또는 전체 모델 이름과 함께 [1m] 접미사를 사용할 수도 있습니다:

# opus[1m] 또는 sonnet[1m] 별칭 사용
/model opus[1m]
/model sonnet[1m]

# 또는 전체 모델 이름에 [1m] 추가
/model claude-opus-4-8[1m]

Sonnet 5 컨텍스트 윈도우

Anthropic API에서 Sonnet 5는 항상 1M 컨텍스트 윈도우로 실행됩니다. 200K 변형이 없고, 선택할 [1m] 접미사가 없으며, 어떤 플랜에서도 사용 크레딧이 필요하지 않습니다. 세션은 윈도우가 채워지기 전에 자동 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. CLAUDE_CODE_AUTO_COMPACT_WINDOW를 설정하여 다른 임계값을 선택하세요.

두 가지 구성이 윈도우를 200K로 예산합니다:

  • LLM 게이트웨이: ANTHROPIC_BASE_URL이 게이트웨이를 가리킬 때 Claude Code는 1M 지원을 확인할 수 없습니다. 전체 윈도우를 사용하려면 모델 선택기에서 Sonnet 5 (1M context)를 선택하세요. 이는 sonnet[1m]으로 매핑됩니다.
  • CLAUDE_CODE_DISABLE_1M_CONTEXT=1: 기본 1M 윈도우가 있는 모든 모델의 세션을 200K 윈도우로 유지합니다. 확장 컨텍스트에서 유지가 강제되는 방법을 참조하세요. 컨텍스트를 제한해야 하는 배포에 유용합니다.

컨텍스트 윈도우 및 자동 압축

자동 압축 윈도우는 Claude Code가 대화를 압축하기 전에 컨텍스트 윈도우가 얼마나 찬 상태인지를 나타냅니다. 압축 메커니즘별로 유지되고 삭제되는 항목에 대해서는 압축 후 유지되는 항목을 참조하십시오.

자동 압축 윈도우 설정

자동 압축 윈도우는 세 가지 위치에서 설정할 수 있습니다.

  • 이 세션 및 이후 세션의 경우: /autocompact를 값과 함께 실행합니다(예: /autocompact 500k). Claude Code는 이를 사용자 설정에 autoCompactWindow로 저장하고 현재 세션에 적용합니다. 관리 설정과 같은 더 높은 우선순위의 설정 범위가 키를 설정하면 명령은 값을 저장하지만 세션은 해당 범위의 윈도우를 유지하며 명령이 이를 알립니다. /autocompact auto를 실행하여 모델에 맞게 조정된 윈도우로 돌아갑니다.
  • 한 번의 실행의 경우: Claude Code를 시작할 때 --autocompact를 전달합니다. 플래그는 저장된 설정을 변경하지 않고 해당 실행에 대해 저장된 설정을 재정의하며, claude --autocompact auto는 저장된 설정에 값이 있더라도 조정된 윈도우에서 세션을 실행합니다. /autocompact와 달리 플래그는 관리 설정과 같은 더 높은 우선순위의 설정 범위에 의해 선점되지 않습니다.
  • 스크립트 및 클라우드 환경에서: CLAUDE_CODE_AUTO_COMPACT_WINDOW를 설정합니다. 설정되어 있는 동안 명령, 플래그 및 설정보다 우선하며, /autocompact는 윈도우를 변경하는 대신 재정의를 보고합니다.

명령과 플래그는 다음 형식 중 하나로 100K에서 1M 토큰 범위의 윈도우 크기를 허용합니다.

  • 일반 토큰 수(예: 200000)
  • k 또는 M 접미사(예: 500k 또는 1M)
  • 100에서 1000 사이의 숫자(천 단위를 의미하므로 200은 200,000을 설정함)

환경 변수는 일반 토큰 수만 허용합니다. Claude Code는 윈도우를 모델의 컨텍스트 윈도우로 제한합니다.

기본 자동 압축 임계값

자동 압축 윈도우를 설정하지 않으면 Claude Code는 다음 세션을 제외하고 대화가 모델의 컨텍스트 제한에 도달할 때 압축합니다.

  • 클라우드 세션은 대화가 모델 제한에 접근할 때 압축합니다.
  • Sonnet 4.6 및 Opus 4.6(확장 컨텍스트 없음)은 200K 경계에서 압축하며, Opus 4.8 및 Opus 5도 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 200K 컨텍스트 윈도우로 실행할 때 압축합니다.
  • CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하면 Sonnet 5 및 Fable 모델과 같이 기본 1M 윈도우가 있는 모델은 200K 경계에서 압축합니다.
  • Sonnet 5, Fable 모델, Anthropic API의 Opus 4.7 이상과 같이 기본 1M 윈도우로 실행되는 모델은 윈도우가 채워지기 전에 압축되며, 기본적으로 약 967K 토큰에서 압축됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 타사 배포를 위한 모델 고정에서 해당 윈도우로 실행되는 모델을 나타냅니다. Sonnet 5를 200K로 예산하는 구성의 경우 Sonnet 5 컨텍스트 윈도우를 참조하십시오.
  • Claude Code가 인식하지 못하는 모델 ID(예: LLM 게이트웨이 별칭)의 세션은 Claude Code가 ID에 대해 가정하는 컨텍스트 윈도우에서 압축합니다. 게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정을 참조하십시오.

게이트웨이 또는 사용자 정의 모델 ID의 윈도우 수정

LLM 게이트웨이 또는 기타 사용자 정의 배포에서 Claude Code는 모델 ID가 모델의 실제 윈도우와 다른 컨텍스트 윈도우를 가정할 수 있습니다(ID가 Claude 모델로 확인되는지 여부와 관계없이). CLAUDE_CODE_MAX_CONTEXT_TOKENS를 Claude Code가 대신 가정해야 하는 윈도우로 설정합니다.

변수가 적용되는 방식은 ID에 따라 다릅니다. Claude Code는 ID가 claude-로 시작하지 않을 때(대소문자 관계없이) 또는 Google Cloud의 Agent Platform에서 사용되는 @YYYYMMDD 날짜와 같이 Claude Code가 ID를 읽을 때 제거하는 접미사를 가질 때 ID를 공급자 또는 사용자 정의 철자로 취급합니다. v2.1.259 이전에는 Claude Code가 제거된 접미사를 계산하지 않았으므로 날짜 접미사가 있는 인식되지 않은 claude- ID는 베어 claude- 이름으로 취급되었습니다.

인식되지 않은 공급자 또는 사용자 정의 철자, [1m]이 있는 동일한 철자, 그리고 다른 모든 ID는 세 가지 별도의 경우입니다.

  • Claude Code가 공급자 또는 사용자 정의 철자를 인식하는 모델로 확인할 수 없고 ID에 [1m]이 포함되지 않으면 변수가 직접 적용되고 선제적 압축은 선언된 윈도우에서 계속됩니다.

  • Claude Code가 공급자 또는 사용자 정의 철자를 인식하는 모델로 확인할 수 없고 ID에 [1m]이 포함되면(대소문자 관계없이) Claude Code는 이에 대해 1M 윈도우를 가정하고 변수는 자체적으로 적용되지 않습니다. 선제적 압축을 유지하면서 윈도우를 수정하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1도 설정합니다. 해당 변수가 설정되면 Claude Code는 ID를 [1m] 없는 동일한 철자처럼 크기를 조정하므로 CLAUDE_CODE_MAX_CONTEXT_TOKENS는 해당 태그 없는 철자에 적용될 때 적용됩니다.

    선언된 윈도우가 200K 이상이면 Claude Code는 200K 제한이 적용되지 않음을 나타내는 시작 경고를 표시합니다. 경고는 이 구성에서 예상됩니다.

  • ID가 Claude Code가 인식하는 모델로 확인되거나 ID가 Claude Code가 제거할 접미사가 없는 베어 claude- 이름인 경우(대소문자 관계없이) 변수는 DISABLE_COMPACT도 설정할 때만 적용되며, 이는 모든 압축을 비활성화합니다.

    예를 들어 anthropic/claude-opus-4-8, us.anthropic.claude-…-v1:0 또는 날짜가 지정된 claude-sonnet-4-5@20250929와 같이 Claude Code가 알고 있는 Claude 모델 이름을 포함하는 ID는 해당 모델로 확인됩니다. 여기에는 [1m]도 포함하는 ID가 포함됩니다. Claude Code는 CLAUDE_CODE_DISABLE_1M_CONTEXT가 설정되어 있어도 claude-opus-4-8[1m]을 Opus 4.8로 확인합니다.

Claude Code가 인식하지 못하는 모델 ID의 경우 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1을 설정하여 Claude Code가 Claude Code가 인식하는 너무 긴 오류로 API가 대화를 거부한 후에만 압축하도록 합니다. Claude Code는 게이트웨이가 오류를 다시 작성하여 Claude Code가 인식하지 못하는 표현으로 변경할 때 해당 복구를 실행하지 않습니다.

현재 모델 확인

현재 사용 중인 모델을 두 가지 위치에서 확인할 수 있습니다:

  • 상태 줄에서(구성된 경우)
  • /status에서, 계정 정보도 표시합니다

사용자 정의 모델 옵션 추가

ANTHROPIC_CUSTOM_MODEL_OPTION을 사용하여 기본 제공 별칭을 대체하지 않고 /model 선택기에 단일 사용자 정의 항목을 추가합니다. 이는 Claude Code가 기본적으로 나열하지 않는 모델 ID를 테스트하는 데 유용합니다. LLM 게이트웨이 배포의 경우, Claude Code는 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1이 설정되어 있을 때 게이트웨이의 /v1/models 엔드포인트에서 선택기를 자동으로 채울 수 있으므로, 이 변수는 검색이 비활성화되었거나 원하는 모델을 반환하지 않을 때만 필요합니다. 게이트웨이 모델 검색을 참조하십시오.

여러 모델을 나열하려면 대신 자신의 순서대로 선택한 레이블 아래에 modelPicker를 설정합니다. 해당 항목은 해당 라인업이 기본 제공 항목을 대체할 때 선택기가 유지하는 행을 나타냅니다.

이 예시는 게이트웨이 라우팅된 Opus 배포를 선택 가능하게 하기 위해 세 가지 변수를 모두 설정합니다. Claude Code는 시작 시 환경 변수를 읽으므로, claude를 시작하기 전에 내보내기를 실행하거나 기존 세션을 다시 시작하여 변수를 적용합니다:

export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-5"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

ANTHROPIC_CUSTOM_MODEL_OPTION_NAME 및 ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION은 선택 사항입니다:

  • 이름을 생략하면 Claude Code가 ID를 인식할 때 항목에 모델의 이름이 표시되고, 그렇지 않으면 모델 ID가 표시됩니다.
  • 설명을 생략하면 Claude Code는 Custom model (<model-id>)를 사용합니다.

Claude Code는 기본 제공 항목 다음에 사용자 정의 항목을 나열하며, 추가하는 모든 modelPicker 행은 그 다음에 나타납니다.

Claude Code는 ANTHROPIC_CUSTOM_MODEL_OPTION에 설정된 모델 ID에 대한 유효성 검사를 건너뜁니다. 따라서 API 엔드포인트가 허용하는 모든 문자열을 사용할 수 있습니다.

availableModels이 설정되어 있을 때는 사용자 정의 모델 ID를 허용 목록에도 포함시켜야 합니다. 그렇지 않으면 Claude Code는 선택기에서 사용자 정의 항목을 필터링하고 다른 제외된 모델처럼 --model 선택을 거부합니다.

my-gateway/claude-opus-5와 같이 패밀리 이름을 포함하는 사용자 정의 ID는 해당 패밀리의 특정 항목으로 계산되며 와일드카드를 비활성화하므로, 선택 가능하게 유지하려는 버전도 나열해야 합니다. 병합 동작을 참조하십시오.

환경 변수

다음 환경 변수를 사용하여 별칭이 매핑되는 모델 이름을 제어합니다. 각 값은 전체 모델 이름이거나 API 제공자에 해당하는 식별자여야 합니다. 세션이 시작되는 모델을 선택하려면 ANTHROPIC_DEFAULT_MODEL을 설정합니다. 이 표에서는 이를 생략합니다.

환경 변수 설명
ANTHROPIC_DEFAULT_FABLE_MODEL fable에 사용할 모델이며, Claude Code가 타사 제공자에서 자동 모델 폴백을 위해 Fable 모델로 인식하는 모델 ID입니다.
ANTHROPIC_DEFAULT_OPUS_MODEL opus에 사용할 모델이거나 Plan Mode가 활성화되었을 때 opusplan에 사용할 모델입니다.
ANTHROPIC_DEFAULT_SONNET_MODEL sonnet에 사용할 모델이거나 Plan Mode가 활성화되지 않았을 때 opusplan에 사용할 모델입니다.
ANTHROPIC_DEFAULT_HAIKU_MODEL haiku에 사용할 모델이거나 백그라운드 기능입니다.
CLAUDE_CODE_SUBAGENT_MODEL subagents, agent team 팀원, 그리고 다른 방식으로 모델이 할당되지 않은 workflow 에이전트의 기본 모델입니다. haiku와 같은 별칭이나 전체 모델 이름을 허용합니다. 호출별 모델이나 정의의 model 필드(예: inherit)가 우선합니다. 이를 변경하려면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE를 설정합니다.

참고: ANTHROPIC_SMALL_FAST_MODEL은 ANTHROPIC_DEFAULT_HAIKU_MODEL을 위해 더 이상 사용되지 않습니다.

타사 배포를 위한 모델 고정

Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 또는 Claude Platform on AWS를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다.

고정하지 않으면 Claude Code는 fable, opus, sonnet, haiku와 같은 모델 별칭을 사용하며, 이는 각 제공자에 대한 기본 제공 기본 모델 ID로 확인됩니다. 해당 기본값은 최신 Anthropic 릴리스보다 뒤떨어질 수 있으며, 가리키는 모델이 사용자 계정에서 아직 활성화되지 않았을 수 있습니다. 기본값을 사용할 수 없으면 Amazon Bedrock 및 Google Cloud의 Agent Platform 사용자는 공지를 보고 해당 세션에 대해 이전 버전의 기본 모델로 폴백되거나, 기본값이 Opus 모델이고 사용 가능한 Opus 버전이 없을 때 기본 Sonnet 모델로 폴백됩니다. Microsoft Foundry 사용자는 Microsoft Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.

Amazon Bedrock 및 Google Cloud의 Agent Platform에서 사용자가 특정 Sonnet 또는 Opus 버전(예: --model, ANTHROPIC_MODEL, 또는 model 설정 사용)으로 세션을 시작하면 해당 버전을 일치하는 별칭의 세션 기본값으로 고정합니다. 시작 확인은 대체하는 기본 제공 기본값을 건너뛰고 폴백 공지를 표시하지 않습니다. v2.1.211 이전에는 세션 모델이 명시적으로 구성되었을 때도 확인이 실행되고 공지를 표시할 수 있었습니다.

제공자에 대한 버전별 모델 ID와 함께 다음 환경 변수를 사용합니다:

제공자 예시
Amazon Bedrock export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-8'
Google Cloud의 Agent Platform export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
Microsoft Foundry export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'

ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 Models overview를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다.

고정된 모델에 대해 확장 컨텍스트를 활성화하려면 ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, 또는 ANTHROPIC_DEFAULT_FABLE_MODEL의 모델 ID에 [1m]을 추가합니다:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'

[1m] 접미사를 사용하면 1M 컨텍스트 윈도우가 고정된 별칭의 모든 사용에 적용되며, opusplan의 plan-mode Opus 단계와 별칭을 이름으로 지정하는 model frontmatter를 가진 subagents를 포함합니다.

  • Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다.
  • 기본 모델이 1M 컨텍스트를 지원할 때만 [1m]을 추가합니다.
  • 접미사는 모델별이 아닌 변수별로 읽혀집니다. Amazon Bedrock, Google Cloud의 Agent Platform 및 Microsoft Foundry에서 한 변수의 [1m] 없는 모델 ID는 다른 변수가 접미사와 함께 동일한 모델을 설정하더라도 200K 컨텍스트를 사용합니다. Sonnet 5는 항상 이러한 제공자에서 1M 윈도우로 실행되며 접미사가 필요하지 않습니다.

고정된 모델 표시 및 기능 사용자 정의

타사 제공자에서 모델을 고정하면 /model 선택기의 행은 Claude Code가 고정된 ID를 인식하면 모델의 이름을 기본값으로 표시하고, 그렇지 않으면 원본 ID를 표시합니다:

  • 인식됨: Claude Code가 알고 있는 모델의 정확한 ID(예: Anthropic API ID 또는 제공자 또는 게이트웨이의 형식)이며, [1m] 접미사 포함 여부와 관계없습니다. us.anthropic.claude-sonnet-4-5-20250929-v1:0을 고정하면 행은 Sonnet 4.5로 읽힙니다.
  • 인식되지 않음: 애플리케이션 추론 프로필 ARN이나 Claude Code가 모르는 모델 버전과 같은 다른 ID이며, modelOverrides 항목이 모델을 해당 정확한 문자열에 매핑하지 않는 한입니다. Microsoft Foundry에서 배포 이름은 사용자 정의이므로 Claude Code는 매핑되었는지 여부와 관계없이 고정된 ID를 인식하지 못하며, 행은 기본값으로 배포 이름을 표시합니다.

행이 모델의 이름을 표시할 때 기본 설명에는 고정된 ID가 포함되어 어떤 ID가 고정되었는지 여전히 볼 수 있습니다.

Claude Code는 또한 고정된 모델이 지원하는 기능을 인식하지 못할 수 있습니다. 각 고정된 모델에 대한 동반 환경 변수로 표시 이름과 설명을 직접 설정하고 기능을 선언할 수 있습니다.

이러한 변수는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry와 같은 타사 제공자에서 적용됩니다. _NAME 및 _DESCRIPTION 변수는 ANTHROPIC_BASE_URL이 LLM gateway를 가리킬 때도 적용됩니다. api.anthropic.com에 직접 연결할 때는 영향을 주지 않습니다.

환경 변수 설명
ANTHROPIC_DEFAULT_OPUS_MODEL_NAME /model 선택기에서 고정된 Opus 모델의 표시 이름입니다. 설정되지 않으면 Claude Code가 고정된 ID를 인식하면 행은 모델의 이름을 표시하고, 그렇지 않으면 고정된 ID를 표시합니다.
ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION /model 선택기에서 고정된 Opus 모델의 표시 설명입니다. 설정되지 않으면 행은 Custom Opus model로 시작하는 기본 설명을 표시합니다.
ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES 고정된 Opus 모델이 지원하는 기능의 쉼표로 구분된 목록입니다.

동일한 _NAME, _DESCRIPTION, _SUPPORTED_CAPABILITIES 접미사는 ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_CUSTOM_MODEL_OPTION에 사용 가능합니다.

Claude Code는 모델 ID를 알려진 패턴과 비교하여 노력 수준 및 확장 사고와 같은 기능을 활성화합니다. Amazon Bedrock ARN 또는 사용자 정의 배포 이름과 같은 제공자별 ID는 종종 이러한 패턴과 일치하지 않아 지원되는 기능이 비활성화됩니다. _SUPPORTED_CAPABILITIES를 설정하여 Claude Code에 모델이 실제로 지원하는 기능을 알립니다:

기능 값 활성화
effort 노력 수준 및 /effort 명령
xhigh_effort xhigh 노력 수준
max_effort max 노력 수준
thinking 확장 사고
adaptive_thinking 작업 복잡도에 따라 동적으로 사고를 할당하는 적응형 추론
interleaved_thinking 도구 호출 간의 사고

_SUPPORTED_CAPABILITIES가 설정되면 나열된 기능이 활성화되고 나열되지 않은 기능은 일치하는 고정된 모델에 대해 비활성화됩니다. 변수가 설정되지 않으면 Claude Code는 모델 ID를 기반으로 한 기본 제공 감지로 폴백합니다.

이 예시는 Opus를 Amazon Bedrock 사용자 정의 모델 ARN에 고정하고, 친화적인 이름을 설정하며, 기능을 선언합니다:

export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'
export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'
export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.7 routed through a Bedrock custom endpoint'
export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,xhigh_effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

버전별 모델 ID 재정의

Claude Code를 임베드하고 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정하는 플랫폼에서 호스트의 모델 구성이 관리 모델 설정보다 우선하며, 호스트가 자신의 것을 제공하지 않는 한 관리 availableModels 허용 목록은 계속 적용됩니다. 관리 설정 우선순위의 예외는 호스트가 재정의하는 키와 변수를 나타냅니다.

위의 패밀리 수준 환경 변수는 패밀리 별칭당 하나의 모델 ID를 구성합니다. 동일한 패밀리 내의 여러 버전을 서로 다른 제공자 ID에 매핑해야 하는 경우 대신 modelOverrides 설정을 사용합니다.

modelOverrides는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 /model 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다.

이를 통해 엔터프라이즈 관리자는 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 Amazon Bedrock 추론 프로필 ARN, Google Cloud의 Agent Platform 버전 이름 또는 Microsoft Foundry 배포 이름으로 라우팅할 수 있습니다.

설정 파일에서 modelOverrides를 설정합니다:

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",
    "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  }
}

키는 Models overview에 나열된 Anthropic 모델 ID여야 합니다. 날짜가 지정된 모델 ID의 경우 날짜 접미사를 정확히 표시된 대로 포함합니다. 알 수 없는 키는 무시됩니다.

[claude-code:unrecognized_model] 진단 라인을 게이트웨이 별칭과 같은 ID에 대해 중지하려면 해당 ID를 값으로 하는 항목을 추가합니다.

재정의는 /model 선택기의 각 항목을 지원하는 기본 제공 모델 ID를 대체합니다. Amazon Bedrock에서 modelOverrides 항목은 Claude Code가 시작 시 자동으로 발견하는 모든 추론 프로필보다 우선합니다. Claude Code는 Amazon Bedrock 추론 프로필 ARN이나 Microsoft Foundry 배포 이름과 같이 이미 제공자 네이티브인 값을 제공자에게 그대로 전달합니다.

재정의는 --model, ANTHROPIC_MODEL 환경 변수, 또는 ANTHROPIC_DEFAULT_*_MODEL 환경 변수를 통해 Anthropic 모델 ID를 직접 전달할 때도 적용됩니다. Amazon Bedrock, Google Cloud의 Agent Platform, Mantle에서 modelOverrides 항목이 없는 Anthropic 모델 ID는 제공자가 해당 버전을 지원할 때 /model 선택기 행과 동일한 제공자별 ID로 확인됩니다. Mantle은 버전의 부분 집합을 지원합니다. 해당 부분 집합 외의 Anthropic 모델 ID의 경우 Claude Code는 modelOverrides 항목이 이를 포함하지 않는 한 원본 ID를 Mantle에 보냅니다. v2.1.200 이전에는 --model 및 환경 변수 값이 재정의 맵을 거치지 않고 제공자에게 그대로 도달했습니다.

modelOverrides는 availableModels과 함께 작동합니다. 허용 목록은 재정의 값이 아닌 Anthropic 모델 ID에 대해 평가되므로 availableModels의 "opus"와 같은 항목은 Opus 버전이 ARN에 매핑되어도 계속 일치합니다. enforceAvailableModels이 관리 설정에서 설정되면 강제된 기본값은 관리 설정에서만 modelOverrides를 통해 확인됩니다. 추론 프로필 ARN에 고정된 버전과 같은 관리자의 매핑이 강제된 기본값에서 인정됩니다. 사용자 또는 프로젝트 설정의 재정의는 이에 영향을 주지 않습니다.

availableModels이 관리 설정에서 설정되면 --model 또는 위의 환경 변수를 통해 직접 전달된 Anthropic 모델 ID에는 관리 설정의 modelOverrides만 적용됩니다. Claude Code는 사용자 또는 프로젝트 설정의 해당 ID에 대한 재정의를 무시하며, 관리 목록이 제외하는 ID를 어떤 설정 소스의 modelOverrides를 통해서도 확인하지 않습니다. 이 관리 소스 제한은 Claude Code v2.1.200 이상이 필요합니다. 차단된 ID가 처리되는 방식은 모델 선택 제한을 참조하세요.

Prompt caching 구성

Claude Code는 성능을 최적화하고 비용을 절감하기 위해 prompt caching을 자동으로 사용합니다. 전역적으로 또는 특정 모델 계층에 대해 prompt caching을 비활성화할 수 있습니다:

환경 변수 설명
DISABLE_PROMPT_CACHING 모든 모델에 대해 prompt caching을 비활성화하려면 1로 설정합니다. 모델별 설정보다 우선합니다.
DISABLE_PROMPT_CACHING_HAIKU Haiku 모델에 대해서만 prompt caching을 비활성화하려면 1로 설정합니다.
DISABLE_PROMPT_CACHING_SONNET Sonnet 모델에 대해서만 prompt caching을 비활성화하려면 1로 설정합니다.
DISABLE_PROMPT_CACHING_OPUS Opus 모델에 대해서만 prompt caching을 비활성화하려면 1로 설정합니다.
DISABLE_PROMPT_CACHING_FABLE Fable 모델에 대해서만 prompt caching을 비활성화하려면 1로 설정합니다.

메인 대화와 subagents에 대해 캐시 TTL을 별도로 선택하려면 TTL을 직접 선택을 참조하세요. 캐시 미스를 트리거하는 것이 무엇인지 알아보려면 Claude Code가 prompt caching을 사용하는 방법을 참조하세요.