읽는 시간: 7분 | 난이도: 중급자

Claude Code는 다양한 모델을 지원하며, 작업의 복잡도와 요구사항에 맞게 모델을 선택하고 설정할 수 있습니다. 편리한 모델 별칭부터 세밀한 노력 수준 조정, 확장 컨텍스트 창까지 다양한 설정 옵션을 제공합니다.

사용 가능한 모델

model 설정에는 다음 두 가지를 지정할 수 있습니다:

• 모델 별칭: 정확한 버전 번호를 기억하지 않아도 되는 편리한 방법
• 전체 모델 이름: Anthropic API의 전체 모델명, Bedrock의 추론 프로필 ARN, Foundry의 배포 이름, Vertex의 버전 이름

모델 별칭

별칭은 항상 최신 버전을 가리킵니다. 특정 버전에 고정하려면 전체 모델 이름(예: claude-opus-4-6)을 사용하거나 ANTHROPIC_DEFAULT_OPUS_MODEL과 같은 환경 변수를 설정하세요.

모델 설정 방법

다음 방법들이 우선순위 순서대로 적용됩니다:

1. 세션 중: /model <별칭|이름>으로 세션 도중에 모델 전환
2. 시작 시: claude --model <별칭|이름>으로 실행
3. 환경 변수: ANTHROPIC_MODEL=<별칭|이름> 설정
4. 설정 파일: settings.json의 model 필드에 영구 설정

사용 예시:

# Opus로 시작
claude --model opus

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

설정 파일 예시:

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

특수 모델 동작

default 모델 설정

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

Opus 사용량 한도에 도달하면 Claude Code가 자동으로 Sonnet으로 대체될 수 있습니다.

opusplan 모델 설정

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

• 플랜 모드에서: 복잡한 추론과 아키텍처 결정에 opus 사용
• 실행 모드에서: 코드 생성과 구현에 자동으로 sonnet으로 전환

이 방식은 계획 단계에서 Opus의 우수한 추론 능력과 실행 단계에서 Sonnet의 효율성을 함께 활용합니다.

노력 수준 조정 (Effort Level)

노력 수준은 Opus 4.6의 적응형 추론을 제어합니다. 작업 복잡도에 따라 동적으로 사고를 할당합니다.

노력 수준 설정 방법:

• /model 내에서: 모델 선택 시 좌우 방향키로 노력 슬라이더 조정
• 환경 변수: CLAUDE_CODE_EFFORT_LEVEL=low|medium|high
• 설정 파일: effortLevel 설정

노력 수준은 현재 Opus 4.6에서 지원됩니다. 지원 모델 선택 시 /model에 노력 슬라이더가 나타납니다.

확장 컨텍스트 (Extended Context)

Opus 4.6과 Sonnet 4.6은 큰 코드베이스와의 긴 세션을 위한 100만 토큰 컨텍스트 창을 지원합니다.

참고: 100만 토큰 컨텍스트 창은 현재 베타 버전입니다. 기능, 가격, 가용성은 변경될 수 있습니다.

이용 가능 대상:

• API 및 종량제 사용자: 100만 토큰 컨텍스트 전체 접근
• Pro, Max, Teams, Enterprise 구독자: 추가 사용량(extra usage) 활성화 시 이용 가능

100만 토큰 컨텍스트를 완전히 비활성화하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하세요.

100만 토큰 모델 선택 방법:

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

# 또는 전체 모델명에 [1m] 접미사 추가
/model claude-sonnet-4-6[1m]

요금 방식: 100만 토큰 모델을 선택해도 즉시 청구 방식이 변경되지 않습니다. 세션이 200K 토큰을 초과하기 전까지는 표준 요금이 적용됩니다. 200K 초과 시 장기 컨텍스트 요금으로 청구됩니다.

모델 선택 제한 (엔터프라이즈)

엔터프라이즈 관리자는 관리 또는 정책 설정에서 availableModels를 사용해 사용자가 선택할 수 있는 모델을 제한할 수 있습니다:

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

availableModels가 설정되면, 사용자는 목록에 없는 모델로 /model, --model 플래그, Config 도구, ANTHROPIC_MODEL 환경 변수를 통해 전환할 수 없습니다.

참고: 모델 선택기의 Default 옵션은 availableModels의 영향을 받지 않습니다. availableModels: []이어도 사용자는 Default 모델로 Claude Code를 사용할 수 있습니다.

모델 경험 완전 제어 — availableModels와 model을 함께 사용하세요:

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

이 설정은 모든 사용자가 Sonnet 4.6으로 실행되고 Sonnet과 Haiku 중에서만 선택할 수 있도록 합니다.

환경 변수

다음 환경 변수는 별칭이 매핑되는 모델 이름을 제어합니다 (전체 모델 이름 또는 API 제공자에 맞는 동등한 값이어야 합니다):

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

서드파티 배포에서 모델 고정

Bedrock, Vertex AI, Foundry를 통해 Claude Code를 배포할 때는 사용자에게 롤아웃하기 전에 모델 버전을 고정하세요.

고정하지 않으면 Claude Code는 최신 버전으로 확인되는 모델 별칭(sonnet, opus, haiku)을 사용합니다. Anthropic이 새 모델을 출시할 때, 새 버전이 활성화되지 않은 계정의 사용자는 자동으로 중단될 수 있습니다.

경고: 초기 설정의 일부로 모든 세 가지 모델 환경 변수를 특정 버전 ID로 설정하세요. 이 단계를 건너뛰면 Claude Code 업데이트가 아무런 조치 없이 사용자를 중단시킬 수 있습니다.

ANTHROPIC_DEFAULT_SONNET_MODEL과 ANTHROPIC_DEFAULT_HAIKU_MODEL에도 동일한 패턴을 적용하세요.

프롬프트 캐싱 설정

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

전역 DISABLE_PROMPT_CACHING 설정은 모델별 설정보다 우선합니다.

현재 모델 확인

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

1. 상태 표시줄에서 (설정된 경우)
2. /status 명령으로 확인 (계정 정보도 함께 표시)

실용적인 설정 예시

개발 환경 설정

일반적인 코딩 작업에는 Sonnet을, 복잡한 아키텍처 결정에는 자동으로 Opus를 사용하는 설정:

{
  "model": "opusplan"
}

비용 최적화 설정

비용을 최소화하면서도 필요한 기능을 유지하는 설정:

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

기업 환경 고정 설정

특정 모델 버전을 강제하는 기업 환경 설정:

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

환경 변수로 모델 버전 고정:

export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-6'

다음 단계

• 상태 표시줄 설정 — 현재 모델을 항상 표시하도록 설정
• 키보드 단축키 — /model 명령에 단축키 바인딩
• 비용 관리 — 토큰 사용량 및 비용 최적화
• 서브에이전트 가이드 — 서브에이전트 모델 설정