모델 구성

모델 구성 (Model configuration)

Claude Code가 사용할 모델은 기본값이 있으며, 세션마다 변경할 수 있습니다. 모델은 settings.json의 model 키, /model 픽커, --model 플래그, 또는 ANTHROPIC_MODEL 환경변수로 지정합니다. 조직은 availableModels로 사용 가능한 모델을 제한할 수 있고, 모델별 기본 설정은 modelOverrides로 담습니다. 이 페이지는 모델 선택·노력 수준(effort)·대체 모델을 다룹니다.

출처: 공식문서

본문

모델 설정하기

기본 모델은 Anthropic의 Claude 시리즈(opu·sonnet·haiku) 중 세션 컨텍스트에 따라 결정됩니다. 모델을 바꾸는 방법:

  • /model: 세션 안에서 픽커로 변경. s를 누르면 이 세션에만 적용되고 기본값으로 저장하지 않습니다.
  • model 설정 키: ~/.claude/settings.json(모든 프로젝트) 또는 .claude/settings.json(팀) 등 설정 파일의 "model": "claude-sonnet-5" 형태. 세션 시작 시 읽히므로 /model로 세션 중 변경합니다.
  • --model <model>: 세션 시작 플래그.
  • ANTHROPIC_MODEL: 셸 환경변수로, 어떤 파일의 model 키보다 우선합니다. model 키를 안 잡은 파일만 있는 경우엔 ANTHROPIC_DEFAULT_MODEL이 적용됩니다.
  • modelOverrides: 모델별 설정(예 특정 모델의 model_settings·enable_thinking 등)을 담는 객체.

사용 가능한 모델은 availableModels 설정으로 제한할 수 있고, enforceAvailableModels: true로 설정하면 Default 옵션도 그 목록을 따릅니다. 관리 설정이 availableModels를 정의하면 유저·프로젝트·로컬이 추가한 항목은 무시됩니다.

노력 수준 (Effort levels)

/effort(인자 없이)로 슬라이더를 열어 모델의 추론 깊이를 조정합니다. 수준(낮은→높은): minimal, low, medium, high, xhigh. 선택한 수준은 해당 모델의 기본값으로 저장되고, 다음 세션에서 그 모델을 쓰면 적용됩니다. s를 누르면 이 세션에만 적용합니다. 설정 키 effortLevel("effortLevel": "high" 등)과 --effort 플래그로도 지정합니다. 조직은 maxEffortLevel로 상한을 제한할 수 있습니다(가장 낮은 상한이 적용, v2.1.267+).

각 모델은 고유한 프롬프트 캐시를 가지므로, 세션 중 모델을 바꾸면 첫 요청이 전체 대화를 캐시 없이 다시 읽습니다(see Switching models).

대체 모델 (Fallback)

fallbackModel 설정으로 기본 모델이 실패할 때(rate limit·중단 등) 사용할 대체 모델을 지정합니다. 순서가 의미 있는 사슬이라, 가장 높은 우선순위 파일의 전체 값을 사용합니다.

연결·타사 모델

API 키·엔드포인트 구성을 통해 Anthropic 호환 API나 게이트웨이(OpenRouter, Amazon Bedrock, Google Vertex AI, Microsoft Foundry 등)를 연결할 수 있습니다. ANTHROPIC_BASE_URL·ANTHROPIC_AUTH_TOKEN 같은 환경변수로 커스텀 엔드포인트를 가리킵니다.

더 알아보기