모델 구성

사용 가능한 모델

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

모델 별칭
모델 이름
- Anthropic API: 전체 모델 이름
- Bedrock: 추론 프로필 ARN
- Foundry: 배포 이름
- Vertex: 버전 이름

ANTHROPIC_BASE_URL은 요청이 전송되는 위치를 변경하며, 어느 모델이 응답하는지는 변경하지 않습니다. Claude를 LLM 게이트웨이를 통해 라우팅하려면 LLM 게이트웨이 구성을 참조하세요.

모델 별칭

모델 별칭은 정확한 버전 번호를 기억할 필요 없이 모델 설정을 선택하는 편리한 방법을 제공합니다:

모델 별칭	동작
`default`	모델 재정의를 제거하고 계정 유형에 따른 권장 모델로 되돌리는 특수 값입니다. 자체로는 모델 별칭이 아닙니다
`best`	현재 사용 가능한 가장 강력한 모델을 사용하며, 현재 `opus`와 동일합니다
`sonnet`	일일 코딩 작업을 위해 최신 Sonnet 모델을 사용합니다
`opus`	복잡한 추론 작업을 위해 최신 Opus 모델을 사용합니다
`haiku`	간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다
`sonnet[1m]`	긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 사용하는 Sonnet을 사용합니다
`opus[1m]`	긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 사용하는 Opus를 사용합니다
`opusplan`	Plan Mode 중에 `opus`를 사용한 후 실행을 위해 `sonnet`으로 전환하는 특수 모드입니다

Anthropic API 및 Claude Platform on AWS에서 opus는 Opus 4.7로, sonnet은 Sonnet 4.6으로 확인됩니다. Bedrock, Vertex 및 Foundry에서 opus는 Opus 4.6으로, sonnet은 Sonnet 4.5로 확인됩니다. 더 새로운 모델은 전체 모델 이름을 명시적으로 선택하거나 ANTHROPIC_DEFAULT_OPUS_MODEL 또는 ANTHROPIC_DEFAULT_SONNET_MODEL을 설정하여 해당 제공자에서 사용할 수 있습니다. 별칭은 제공자에 대한 권장 버전을 가리키며 시간이 지남에 따라 업데이트됩니다. 특정 버전으로 고정하려면 전체 모델 이름(예: claude-opus-4-7)을 사용하거나 ANTHROPIC_DEFAULT_OPUS_MODEL과 같은 해당 환경 변수를 설정합니다.

Opus 4.7은 Claude Code v2.1.111 이상이 필요합니다. claude update를 실행하여 업그레이드하세요.

모델 설정

다음과 같은 여러 방법으로 모델을 구성할 수 있으며, 우선순위 순서대로 나열되어 있습니다:

세션 중 - /model <alias|name>을 사용하여 즉시 전환하거나, 인수 없이 /model을 실행하여 선택기를 엽니다. 선택기는 대화에 이전 출력이 있을 때 확인을 요청합니다. 다음 응답이 캐시된 컨텍스트 없이 전체 기록을 다시 읽기 때문입니다.
시작 시 - claude --model <alias|name>으로 실행합니다.
환경 변수 - ANTHROPIC_MODEL=<alias|name>을 설정합니다.
설정 - model 필드를 사용하여 설정 파일에서 영구적으로 구성합니다.

/model 선택은 사용자 설정에 저장되며 재시작 후에도 유지됩니다. v2.1.117부터 프로젝트의 .claude/settings.json이 다른 모델을 고정하는 경우, Claude Code는 선택 항목을 .claude/settings.local.json에도 작성하므로 재시작 후 해당 프로젝트에서 계속 적용됩니다. 관리되는 설정이 우선순위를 가지며 다음 실행 시 다시 적용됩니다. 시작 시 활성 모델이 자신의 선택이 아닌 프로젝트 또는 관리되는 설정에서 나온 경우, 시작 헤더는 어느 설정 파일이 이를 설정했는지 표시합니다. /model을 실행하여 현재 세션에 대해 재정의합니다. 사용 예시:

# Opus로 시작
claude --model opus

# 세션 중에 Sonnet으로 전환
/model sonnet

설정 파일 예시:

{
    "permissions": {
        ...
    },
    "model": "opus"
}

모델 선택 제한

엔터프라이즈 관리자는 관리 또는 정책 설정에서 availableModels을 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다. availableModels이 설정되면 사용자는 /model, --model 플래그 또는 ANTHROPIC_MODEL 환경 변수를 통해 목록에 없는 모델로 전환할 수 없습니다.

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

기본 모델 동작

모델 선택기의 Default 옵션은 availableModels의 영향을 받지 않습니다. 항상 사용 가능하며 사용자의 구독 계층을 기반으로 한 시스템의 런타임 기본값을 나타냅니다. availableModels: []인 경우에도 사용자는 자신의 계층에 대한 Default 모델로 Claude Code를 사용할 수 있습니다.

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

model 설정은 초기 선택이지 강제가 아닙니다. 세션이 시작될 때 활성화되는 모델을 설정하지만 사용자는 여전히 /model을 열고 Default를 선택할 수 있으며, 이는 model이 설정된 것과 관계없이 계층에 대한 시스템 기본값으로 확인됩니다. 모델 경험을 완전히 제어하려면 세 가지 설정을 함께 사용합니다:

availableModels: 사용자가 전환할 수 있는 명명된 모델을 제한합니다
model: 세션이 시작될 때 활성화되는 초기 모델 선택을 설정합니다
ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL: Default 옵션과 sonnet, opus, haiku 별칭이 확인되는 대상을 제어합니다

이 예시는 사용자를 Sonnet 4.5에서 시작하고, 선택기를 Sonnet과 Haiku로 제한하며, Default가 최신 릴리스가 아닌 Sonnet 4.5로 확인되도록 고정합니다:

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

env 블록이 없으면 선택기에서 Default를 선택하는 사용자는 최신 Sonnet 릴리스를 받게 되어 model 및 availableModels의 버전 고정을 우회합니다.

병합 동작

availableModels이 사용자 설정 및 프로젝트 설정과 같은 여러 수준에서 설정되면 배열이 병합되고 중복이 제거됩니다. 엄격한 허용 목록을 적용하려면 가장 높은 우선순위를 가지는 관리 또는 정책 설정에서 availableModels을 설정합니다.

Mantle 모델 ID

Bedrock Mantle 엔드포인트가 활성화되면 availableModels의 anthropic.으로 시작하는 항목이 /model 선택기에 사용자 정의 옵션으로 추가되고 Mantle 엔드포인트로 라우팅됩니다. 이는 타사 배포를 위한 모델 고정에 설명된 별칭 전용 일치에 대한 예외입니다. 설정은 여전히 선택기를 나열된 항목으로 제한하므로 표준 별칭과 함께 모든 Mantle ID를 포함합니다.

특수 모델 동작

`default` 모델 설정

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

Max 및 Team Premium: Opus 4.7로 기본값 설정
Pro, Team Standard, Enterprise 및 Anthropic API: Sonnet 4.6으로 기본값 설정
Bedrock, Vertex 및 Foundry: Sonnet 4.5로 기본값 설정

Claude Code는 Opus의 사용 임계값에 도달하면 자동으로 Sonnet으로 폴백할 수 있습니다.

2026년 4월 23일에 Enterprise 종량제 및 Anthropic API 사용자의 기본 모델이 Opus 4.7로 변경됩니다. 다른 기본값을 유지하려면 서버 관리 설정에서 ANTHROPIC_MODEL 또는 model 필드를 설정하세요.

`opusplan` 모델 설정

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

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

이는 계획을 위한 Opus의 우수한 추론과 실행을 위한 Sonnet의 효율성이라는 두 가지 장점을 모두 제공합니다. Plan Mode Opus 단계는 표준 200K 컨텍스트 윈도우로 실행됩니다. 확장 컨텍스트에 설명된 자동 1M 업그레이드는 opus 모델 설정에 적용되며 opusplan으로 확장되지 않습니다.

노력 수준 조정

노력 수준은 적응형 추론을 제어하며, 작업 복잡도에 따라 모델이 각 단계에서 생각할지 여부와 얼마나 생각할지를 결정하도록 합니다. 낮은 노력은 간단한 작업의 경우 더 빠르고 저렴하며, 높은 노력은 복잡한 문제에 대해 더 깊은 추론을 제공합니다. 노력은 Opus 4.7, Opus 4.6 및 Sonnet 4.6에서 지원됩니다. 사용 가능한 수준은 모델에 따라 다릅니다:

모델	수준
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로 실행됩니다. v2.1.117부터 기본 노력은 Opus 4.7에서 xhigh이고 Opus 4.6 및 Sonnet 4.6에서 high입니다. Opus 4.7을 처음 실행할 때 Claude Code는 이전에 Opus 4.6 또는 Sonnet 4.6에 대해 다른 노력 수준을 설정했더라도 xhigh를 적용합니다. 전환 후 다른 수준을 선택하려면 /effort를 다시 실행하세요. low, medium, high 및 xhigh는 세션 전체에 유지됩니다. max는 토큰 지출에 제약이 없어 가장 깊은 추론을 제공하며 현재 세션에만 적용됩니다. 단, CLAUDE_CODE_EFFORT_LEVEL 환경 변수를 통해 설정된 경우는 예외입니다.

노력 수준 선택

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

수준	사용 시기
`low`	지능 민감도가 낮은 짧고 범위가 지정된 지연 시간 민감 작업을 위해 예약
`medium`	일부 지능을 절충할 수 있는 비용 민감 작업의 토큰 사용량 감소
`high`	토큰 사용량과 지능의 균형을 맞춥니다. 지능 민감 작업의 최소값으로 사용하거나 `xhigh`에 비해 토큰 지출을 줄이기 위해 사용
`xhigh`	대부분의 코딩 및 에이전트 작업에 최고의 결과. Opus 4.7에서 권장 기본값
`max`	까다로운 작업의 성능을 개선할 수 있지만 수익 감소를 보일 수 있으며 과도한 생각에 취약합니다. 광범위하게 채택하기 전에 테스트하세요

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

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

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

노력 수준 설정

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

/effort: 인수 없이 /effort를 실행하여 대화형 슬라이더를 열거나, 수준 이름 뒤에 /effort를 실행하여 직접 설정하거나, /effort auto를 실행하여 모델 기본값으로 재설정
/model에서: 모델을 선택할 때 좌우 화살표 키를 사용하여 노력 슬라이더 조정
--effort 플래그: Claude Code를 시작할 때 단일 세션에 대한 수준 이름을 전달
환경 변수: CLAUDE_CODE_EFFORT_LEVEL을 수준 이름 또는 auto로 설정
설정: 설정 파일에서 effortLevel을 low, medium, high 또는 xhigh로 설정합니다. max는 세션 전용이며 여기서는 허용되지 않습니다
Skill 및 subagent frontmatter: skill 또는 subagent markdown 파일에서 effort를 설정하여 해당 skill 또는 subagent가 실행될 때 노력 수준을 재정의

환경 변수가 모든 다른 방법보다 우선하고, 그 다음 구성된 수준, 그 다음 모델 기본값입니다. Frontmatter 노력은 해당 skill 또는 subagent가 활성화될 때 적용되어 세션 수준을 재정의하지만 환경 변수는 재정의하지 않습니다. 노력 슬라이더는 지원되는 모델이 선택되면 /model에 나타납니다. 현재 노력 수준은 로고 및 스피너 옆에도 표시되므로(예: “with low effort”), /model을 열지 않고도 어떤 설정이 활성화되어 있는지 확인할 수 있습니다.

적응형 추론 및 고정 사고 예산

적응형 추론은 각 단계에서 사고를 선택 사항으로 만들므로 Claude는 일상적인 프롬프트에 더 빠르게 응답하고 이점을 얻는 단계를 위해 더 깊은 사고를 예약할 수 있습니다. Claude가 현재 수준이 생성하는 것보다 더 자주 또는 덜 자주 생각하기를 원하면 프롬프트 또는 CLAUDE.md에서 직접 말할 수 있습니다. 모델은 노력 설정 내에서 해당 지침에 응답합니다. Opus 4.7은 항상 적응형 추론을 사용합니다. 고정 사고 예산 모드 및 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING은 이에 적용되지 않습니다. Opus 4.6 및 Sonnet 4.6에서 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1을 설정하여 MAX_THINKING_TOKENS로 제어되는 이전의 고정 사고 예산으로 되돌릴 수 있습니다. 환경 변수를 참조하세요.

확장 사고

확장 사고는 Claude가 응답하기 전에 내보내는 추론입니다. 적응형 추론을 지원하는 모델에서 노력 수준은 얼마나 많은 사고가 발생하는지에 대한 주요 제어입니다. 아래 설정은 사고를 켜거나 끄고 표시 방식을 제어합니다.

제어	설정 방법
현재 세션에 대한 토글	macOS에서 `Option+T` 또는 Windows 및 Linux에서 `Alt+T`를 누릅니다
전역 기본값 설정	`/config`를 실행하고 사고 모드를 토글합니다. `~/.claude/settings.json`에 `alwaysThinkingEnabled`로 저장됩니다
노력에 관계없이 비활성화	`MAX_THINKING_TOKENS=0`을 설정합니다. 다른 값은 고정 사고 예산에만 적용됩니다

사고 출력은 기본적으로 축소됩니다. Ctrl+O를 눌러 자세한 모드를 토글하고 추론을 회색 기울임꼴 텍스트로 봅니다. Anthropic API의 대화형 세션은 기본적으로 편집된 사고 블록을 수신하므로 확장할 때 전체 요약을 사용할 수 있도록 하려면 설정에서 showThinkingSummaries: true를 설정하세요. 축소되거나 편집된 경우에도 생성된 모든 사고 토큰에 대해 요금이 청구됩니다.

확장 컨텍스트

Opus 4.7, Opus 4.6 및 Sonnet 4.6은 대규모 코드베이스를 사용한 긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 지원합니다. 가용성은 모델 및 플랜에 따라 다릅니다. Max, Team 및 Enterprise 플랜에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. 이는 Team Standard 및 Team Premium 시트 모두에 적용됩니다. 1M 컨텍스트를 사용하는 Sonnet은 자동 업그레이드의 일부가 아니며 모든 구독 플랜(Max 포함)에서 추가 사용이 필요합니다.

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

1M 컨텍스트를 완전히 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다. 이는 모델 선택기에서 1M 모델 변형을 제거합니다. 환경 변수를 참조하세요. 1M 컨텍스트 윈도우는 200K를 초과하는 토큰에 대한 프리미엄 없이 표준 모델 가격을 사용합니다. 확장 컨텍스트가 구독에 포함된 플랜의 경우 사용량은 구독으로 계속 적용됩니다. 추가 사용을 통해 확장 컨텍스트에 액세스하는 플랜의 경우 토큰은 추가 사용으로 청구됩니다. 계정이 1M 컨텍스트를 지원하면 최신 버전의 Claude Code에서 모델 선택기(/model)에 옵션이 나타납니다. 표시되지 않으면 세션을 다시 시작해 보세요. 모델 별칭 또는 전체 모델 이름과 함께 [1m] 접미사를 사용할 수도 있습니다:

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

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

현재 모델 확인

현재 사용 중인 모델을 여러 방법으로 확인할 수 있습니다:

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

사용자 정의 모델 옵션 추가

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

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

사용자 정의 항목은 /model 선택기의 맨 아래에 나타납니다. ANTHROPIC_CUSTOM_MODEL_OPTION_NAME 및 ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION은 선택 사항입니다. 생략하면 모델 ID가 이름으로 사용되고 설명은 기본값으로 Custom model (<model-id>)입니다. Claude Code는 ANTHROPIC_CUSTOM_MODEL_OPTION에 설정된 모델 ID에 대한 유효성 검사를 건너뜁니다. 따라서 API 엔드포인트가 허용하는 모든 문자열을 사용할 수 있습니다.

환경 변수

다음 환경 변수를 사용할 수 있으며, 이는 별칭이 매핑되는 모델 이름을 제어하기 위해 전체 모델 이름(또는 API 제공자에 해당하는 이름)이어야 합니다.

환경 변수	설명
`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에 사용할 모델

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

타사 배포를 위한 모델 고정

Bedrock, Vertex AI, Foundry 또는 Claude Platform on AWS를 통해 Claude Code를 배포할 때 사용자에게 롤아웃하기 전에 모델 버전을 고정합니다. 고정하지 않으면 Claude Code는 최신 버전으로 확인되는 모델 별칭(sonnet, opus, haiku)을 사용합니다. Anthropic이 새 모델을 출시할 때 새 버전이 아직 사용자 계정에서 활성화되지 않으면 Bedrock 및 Vertex AI 사용자는 공지를 보고 해당 세션에 대해 이전 버전으로 폴백되며, Foundry 사용자는 Foundry에 동등한 시작 확인이 없기 때문에 오류를 봅니다.

초기 설정의 일부로 세 가지 모델 환경 변수를 모두 특정 버전 ID로 설정합니다. 고정하면 사용자가 새 모델로 이동할 시기를 제어할 수 있습니다.

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

제공자	예시
Bedrock	`export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-7'`
Vertex AI	`export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'`
Foundry	`export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'`

ANTHROPIC_DEFAULT_SONNET_MODEL 및 ANTHROPIC_DEFAULT_HAIKU_MODEL에 대해 동일한 패턴을 적용합니다. 모든 제공자의 현재 및 레거시 모델 ID는 모델 개요를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 다시 배포합니다. 고정된 모델에 대해 확장 컨텍스트를 활성화하려면 ANTHROPIC_DEFAULT_OPUS_MODEL 또는 ANTHROPIC_DEFAULT_SONNET_MODEL의 모델 ID에 [1m]을 추가합니다:

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

[1m] 접미사는 opusplan을 포함한 해당 별칭의 모든 사용에 1M 컨텍스트 윈도우를 적용합니다. Claude Code는 모델 ID를 제공자에게 보내기 전에 접미사를 제거합니다. Opus 4.7 또는 Sonnet 4.6과 같이 기본 모델이 1M 컨텍스트를 지원할 때만 [1m]을 추가합니다.

settings.availableModels 허용 목록은 타사 제공자를 사용할 때도 적용됩니다. 필터링은 제공자별 모델 ID가 아닌 모델 별칭(opus, sonnet, haiku)과 일치합니다.

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

타사 제공자에서 모델을 고정하면 제공자별 ID가 /model 선택기에 그대로 나타나고 Claude Code는 모델이 지원하는 기능을 인식하지 못할 수 있습니다. 각 고정된 모델에 대한 동반 환경 변수로 표시 이름과 기능을 선언할 수 있습니다. 이러한 변수는 Bedrock, Vertex AI 및 Foundry와 같은 타사 제공자에서 적용됩니다. _NAME 및 _DESCRIPTION 변수는 ANTHROPIC_BASE_URL이 LLM gateway를 가리킬 때도 적용됩니다. api.anthropic.com에 직접 연결할 때는 영향을 주지 않습니다.

환경 변수	설명
`ANTHROPIC_DEFAULT_OPUS_MODEL_NAME`	`/model` 선택기에서 고정된 Opus 모델의 표시 이름입니다. 설정되지 않으면 모델 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_CUSTOM_MODEL_OPTION에 사용 가능합니다. Claude Code는 모델 ID를 알려진 패턴과 비교하여 노력 수준 및 확장 사고와 같은 기능을 활성화합니다. 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를 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 재정의

위의 패밀리 수준 환경 변수는 패밀리 별칭당 하나의 모델 ID를 구성합니다. 동일한 패밀리 내의 여러 버전을 서로 다른 제공자 ID에 매핑해야 하는 경우 대신 modelOverrides 설정을 사용합니다. modelOverrides는 개별 Anthropic 모델 ID를 Claude Code가 제공자의 API에 보내는 제공자별 문자열에 매핑합니다. 사용자가 /model 선택기에서 매핑된 모델을 선택하면 Claude Code는 기본 제공 기본값 대신 구성된 값을 사용합니다. 이를 통해 엔터프라이즈 관리자는 거버넌스, 비용 할당 또는 지역 라우팅을 위해 각 모델 버전을 특정 Bedrock 추론 프로필 ARN, Vertex AI 버전 이름 또는 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"
  }
}

키는 모델 개요에 나열된 Anthropic 모델 ID여야 합니다. 날짜가 지정된 모델 ID의 경우 날짜 접미사를 정확히 표시된 대로 포함합니다. 알 수 없는 키는 무시됩니다. 재정의는 /model 선택기의 각 항목을 지원하는 기본 제공 모델 ID를 대체합니다. Bedrock에서 재정의는 Claude Code가 시작 시 자동으로 발견하는 모든 추론 프로필보다 우선합니다. ANTHROPIC_MODEL, --model 또는 ANTHROPIC_DEFAULT_*_MODEL 환경 변수를 통해 직접 제공하는 값은 제공자에게 그대로 전달되며 modelOverrides로 변환되지 않습니다. modelOverrides는 availableModels과 함께 작동합니다. 허용 목록은 재정의 값이 아닌 Anthropic 모델 ID에 대해 평가되므로 availableModels의 "opus"와 같은 항목은 Opus 버전이 ARN에 매핑되어도 계속 일치합니다.

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`로 설정

이러한 환경 변수는 prompt caching 동작에 대한 세밀한 제어를 제공합니다. 전역 DISABLE_PROMPT_CACHING 설정은 모델별 설정보다 우선하므로 필요할 때 모든 캐싱을 빠르게 비활성화할 수 있습니다. 모델별 설정은 특정 모델 디버깅 또는 다양한 캐싱 구현을 가질 수 있는 클라우드 제공자와 작업할 때와 같이 선택적 제어에 유용합니다.

설정 및 권한

모델 및 응답

인터페이스

사용 가능한 모델

모델 별칭

모델 설정

모델 선택 제한

기본 모델 동작

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

병합 동작

Mantle 모델 ID

특수 모델 동작

`default` 모델 설정

`opusplan` 모델 설정

노력 수준 조정

노력 수준 선택

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

노력 수준 설정

적응형 추론 및 고정 사고 예산

확장 사고

확장 컨텍스트

현재 모델 확인

사용자 정의 모델 옵션 추가

환경 변수

타사 배포를 위한 모델 고정

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

버전별 모델 ID 재정의

Prompt caching 구성

설정 및 권한

모델 및 응답

인터페이스

Documentation Index

​사용 가능한 모델

​모델 별칭

​모델 설정

​모델 선택 제한

​기본 모델 동작

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

​병합 동작

​Mantle 모델 ID

​특수 모델 동작

​default 모델 설정

​opusplan 모델 설정

​노력 수준 조정

​노력 수준 선택

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

​노력 수준 설정

​적응형 추론 및 고정 사고 예산

​확장 사고

​확장 컨텍스트

​현재 모델 확인

​사용자 정의 모델 옵션 추가

​환경 변수

​타사 배포를 위한 모델 고정

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

​버전별 모델 ID 재정의

​Prompt caching 구성

사용 가능한 모델

모델 별칭

모델 설정

모델 선택 제한

기본 모델 동작

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

병합 동작

Mantle 모델 ID

특수 모델 동작

`default` 모델 설정

`opusplan` 모델 설정

노력 수준 조정

노력 수준 선택

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

노력 수준 설정

적응형 추론 및 고정 사고 예산

확장 사고

확장 컨텍스트

현재 모델 확인

사용자 정의 모델 옵션 추가

환경 변수

타사 배포를 위한 모델 고정

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

버전별 모델 ID 재정의

Prompt caching 구성