18. 모델 설정
별칭·모델 전환·사용 모델 제한·배포 환경 고정 등 모델 설정 레퍼런스
모델 설정
opusplan과 같은 모델 별칭을 포함한 Claude Code 모델 설정에 대해 알아보세요
사용 가능한 모델
Claude Code의 model 설정에는 다음 중 하나를 구성할 수 있습니다:
- 모델 별칭
- 모델 이름
- Anthropic API: 전체 모델 이름
- Bedrock: 추론 프로필 ARN
- Foundry: 배포 이름
- Vertex: 버전 이름
모델 별칭
모델 별칭은 정확한 버전 번호를 기억하지 않고도 모델 설정을 편리하게 선택할 수 있는 방법을 제공합니다:
| 모델 별칭 | 동작 |
|---|---|
default | 계정 유형에 따른 권장 모델 설정 |
sonnet | 일상적인 코딩 작업을 위해 최신 Sonnet 모델(현재 Sonnet 4.6)을 사용합니다 |
opus | 복잡한 추론 작업을 위해 최신 Opus 모델(현재 Opus 4.6)을 사용합니다 |
haiku | 간단한 작업을 위해 빠르고 효율적인 Haiku 모델을 사용합니다 |
sonnet[1m] | 긴 세션을 위해 100만 토큰 컨텍스트 윈도우가 적용된 Sonnet을 사용합니다 |
opusplan | 플랜 모드에서는 opus를 사용하고, 실행 시에는 sonnet으로 전환하는 특수 모드입니다 |
별칭은 항상 최신 버전을 가리킵니다. 특정 버전을 고정하려면 전체 모델 이름(예: claude-opus-4-6)을 사용하거나 ANTHROPIC_DEFAULT_OPUS_MODEL과 같은 해당 환경 변수를 설정하세요.
모델 설정하기
모델을 여러 방법으로 설정할 수 있으며, 우선순위 순서는 다음과 같습니다:
- 세션 중 -
/model <alias|name>을 사용하여 세션 도중 모델을 전환합니다 - 시작 시 -
claude --model <alias|name>으로 실행합니다 - 환경 변수 -
ANTHROPIC_MODEL=<alias|name>을 설정합니다 - 설정 파일 - 설정 파일의
model필드에서 영구적으로 설정합니다.
사용 예시:
# Start with Opus
claude --model opus
# Switch to Sonnet during session
/model sonnet
설정 파일 예시:
{
"permissions": {
...
},
"model": "opus"
}
모델 선택 제한
엔터프라이즈 관리자는 관리 또는 정책 설정의 availableModels를 사용하여 사용자가 선택할 수 있는 모델을 제한할 수 있습니다.
availableModels가 설정되면 사용자는 /model, --model 플래그, Config 도구 또는 ANTHROPIC_MODEL 환경 변수를 통해 목록에 없는 모델로 전환할 수 없습니다.
{
"availableModels": ["sonnet", "haiku"]
}
기본 모델 동작
모델 선택기의 Default 옵션은 availableModels의 영향을 받지 않습니다. 항상 사용 가능한 상태로 유지되며 사용자의 구독 등급에 따른 시스템 런타임 기본값을 나타냅니다.
availableModels: []로 설정하더라도 사용자는 해당 등급의 Default 모델로 Claude Code를 계속 사용할 수 있습니다.
사용자가 실행하는 모델 제어
모델 경험을 완전히 제어하려면 availableModels와 model 설정을 함께 사용하세요:
- availableModels: 사용자가 전환할 수 있는 모델을 제한합니다
- model: 명시적 모델 오버라이드를 설정하며, Default보다 우선합니다
이 예시는 모든 사용자가 Sonnet 4.6을 실행하고 Sonnet과 Haiku 중에서만 선택할 수 있도록 보장합니다:
{
"model": "sonnet",
"availableModels": ["sonnet", "haiku"]
}
병합 동작
availableModels가 사용자 설정과 프로젝트 설정 등 여러 수준에서 설정된 경우, 배열이 병합되고 중복이 제거됩니다. 엄격한 허용 목록을 적용하려면 최우선 순위를 가지는 관리 또는 정책 설정에서 availableModels를 설정하세요.
특수 모델 동작
default 모델 설정
default의 동작은 계정 유형에 따라 다릅니다:
- Max 및 Team Premium: 기본값은 Opus 4.6
- Pro 및 Team Standard: 기본값은 Sonnet 4.6
- Enterprise: Opus 4.6을 사용할 수 있지만 기본값은 아닙니다
Claude Code는 Opus 사용 임계치에 도달하면 자동으로 Sonnet으로 대체할 수 있습니다.
opusplan 모델 설정
opusplan 모델 별칭은 자동화된 하이브리드 접근 방식을 제공합니다:
- 플랜 모드에서 - 복잡한 추론 및 아키텍처 결정에
opus를 사용합니다 - 실행 모드에서 - 코드 생성 및 구현을 위해 자동으로
sonnet으로 전환합니다
이를 통해 양쪽의 장점을 모두 활용할 수 있습니다: 계획 수립에는 Opus의 뛰어난 추론 능력을, 실행에는 Sonnet의 효율성을 사용합니다.
노력 수준 조정
노력 수준은 적응형 추론을 제어하며, 작업 복잡도에 따라 사고 과정을 동적으로 할당합니다. 낮은 노력 수준은 단순한 작업에서 더 빠르고 저렴하며, 높은 노력 수준은 복잡한 문제에 대해 더 깊은 추론을 제공합니다.
low, medium, high 세 가지 수준을 사용할 수 있습니다. Opus 4.6은 Max 및 Team 구독자에게 기본적으로 medium 노력 수준을 적용합니다.
노력 수준 설정:
/model에서: 모델을 선택할 때 좌/우 화살표 키로 노력 슬라이더를 조절합니다- 환경 변수:
CLAUDE_CODE_EFFORT_LEVEL=low|medium|high를 설정합니다 - 설정 파일: 설정 파일에서
effortLevel을 설정합니다
노력 수준은 Opus 4.6과 Sonnet 4.6에서 지원됩니다. 지원되는 모델이 선택되면 /model에서 노력 슬라이더가 나타납니다. 현재 노력 수준은 로고와 스피너 옆에도 표시되므로(예: "with low effort"), /model을 열지 않고도 어떤 설정이 활성 상태인지 확인할 수 있습니다.
Opus 4.6과 Sonnet 4.6에서 적응형 추론을 비활성화하고 이전의 고정 사고 예산으로 되돌리려면 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1을 설정하세요. 비활성화되면 이러한 모델은 MAX_THINKING_TOKENS로 제어되는 고정 예산을 사용합니다. 환경 변수를 참조하세요.
확장 컨텍스트
Opus 4.6과 Sonnet 4.6은 대규모 코드베이스를 다루는 긴 세션을 위해 100만 토큰 컨텍스트 윈도우를 지원합니다.
참고: 100만 토큰 컨텍스트 윈도우는 현재 베타 단계입니다. 기능, 가격 및 가용성이 변경될 수 있습니다.
확장 컨텍스트는 다음에서 사용할 수 있습니다:
- API 및 종량제 사용자: 100만 컨텍스트에 대한 전체 접근
- Pro, Max, Teams 및 Enterprise 구독자: 추가 사용량이 활성화된 경우 사용 가능
100만 컨텍스트를 완전히 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요. 이렇게 하면 모델 선택기에서 100만 모델 변형이 제거됩니다. 환경 변수를 참조하세요.
100만 모델을 선택해도 즉시 요금이 변경되지는 않습니다. 세션은 컨텍스트가 200K 토큰을 초과할 때까지 표준 요금을 적용합니다. 200K 토큰을 초과하면 전용 속도 제한과 함께 장문 컨텍스트 가격이 적용됩니다. 구독자의 경우 200K를 초과하는 토큰은 구독을 통해서가 아니라 추가 사용량으로 청구됩니다.
계정이 100만 컨텍스트를 지원하는 경우, 최신 버전의 Claude Code에서 모델 선택기(/model)에 옵션이 나타납니다. 보이지 않는 경우 세션을 재시작해 보세요.
모델 별칭이나 전체 모델 이름과 함께 [1m] 접미사를 사용할 수도 있습니다:
# Use the sonnet[1m] alias
/model sonnet[1m]
# Or append [1m] to a full model name
/model claude-sonnet-4-6[1m]
현재 모델 확인
현재 사용 중인 모델을 여러 방법으로 확인할 수 있습니다:
- 상태 표시줄에서 (설정된 경우)
/status에서 확인 가능하며, 계정 정보도 함께 표시됩니다.
환경 변수
다음 환경 변수를 사용할 수 있으며, 별칭이 매핑되는 모델 이름을 제어하기 위해 전체 모델 이름(또는 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 | 서브에이전트에 사용할 모델입니다 |
참고: ANTHROPIC_SMALL_FAST_MODEL은 더 이상 사용되지 않으며
ANTHROPIC_DEFAULT_HAIKU_MODEL로 대체되었습니다.
서드파티 배포를 위한 모델 고정
Bedrock, Vertex AI 또는 Foundry를 통해 Claude Code를 배포할 때는 사용자에게 배포하기 전에 모델 버전을 고정하세요.
고정하지 않으면 Claude Code는 최신 버전으로 해석되는 모델 별칭(sonnet, opus, haiku)을 사용합니다. Anthropic이 새 모델을 출시하면 새 버전이 활성화되지 않은 계정의 사용자가 조용히 실패하게 됩니다.
주의: 초기 설정 시 세 가지 모델 환경 변수를 모두 특정 버전 ID로 설정하세요. 이 단계를 건너뛰면 Claude Code 업데이트로 인해 별도의 조치 없이도 사용자 환경이 손상될 수 있습니다.
제공자별로 버전 특정 모델 ID와 함께 다음 환경 변수를 사용하세요:
| 제공자 | 예시 |
|---|---|
| Bedrock | export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1' |
| Vertex AI | export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6' |
| Foundry | export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6' |
ANTHROPIC_DEFAULT_SONNET_MODEL과 ANTHROPIC_DEFAULT_HAIKU_MODEL에도 동일한 패턴을 적용하세요. 모든 제공자의 현재 및 레거시 모델 ID에 대해서는 모델 개요를 참조하세요. 사용자를 새 모델 버전으로 업그레이드하려면 이러한 환경 변수를 업데이트하고 재배포하세요.
참고:
settings.availableModels허용 목록은 서드파티 제공자를 사용할 때도 적용됩니다. 필터링은 제공자별 모델 ID가 아닌 모델 별칭(opus,sonnet,haiku)을 기준으로 매칭합니다.
프롬프트 캐싱 설정
Claude Code는 성능 최적화와 비용 절감을 위해 자동으로 프롬프트 캐싱을 사용합니다. 전역적으로 또는 특정 모델 등급에 대해 프롬프트 캐싱을 비활성화할 수 있습니다:
| 환경 변수 | 설명 |
|---|---|
DISABLE_PROMPT_CACHING | 모든 모델에 대해 프롬프트 캐싱을 비활성화하려면 1로 설정합니다 (모델별 설정보다 우선) |
DISABLE_PROMPT_CACHING_HAIKU | Haiku 모델에 대해서만 프롬프트 캐싱을 비활성화하려면 1로 설정합니다 |
DISABLE_PROMPT_CACHING_SONNET | Sonnet 모델에 대해서만 프롬프트 캐싱을 비활성화하려면 1로 설정합니다 |
DISABLE_PROMPT_CACHING_OPUS | Opus 모델에 대해서만 프롬프트 캐싱을 비활성화하려면 1로 설정합니다 |
이 환경 변수들은 프롬프트 캐싱 동작에 대한 세밀한 제어를 제공합니다. 전역 DISABLE_PROMPT_CACHING 설정은 모델별 설정보다 우선하므로, 필요할 때 모든 캐싱을 빠르게 비활성화할 수 있습니다. 모델별 설정은 특정 모델을 디버깅하거나 캐싱 구현이 다를 수 있는 클라우드 제공자와 작업할 때 등 선택적 제어에 유용합니다.