모델 시스템

Claude Code의 모델 시스템은 다양한 AI 모델을 통합 인터페이스로 관리합니다. 4개 프로바이더의 모델들을 5개 우선순위 레이어를 통해 선택하고, 1M 컨텍스트 윈도우 같은 확장 기능을 런타임에 구성합니다.

모델 시스템의 핵심 구성 요소:

• ALL_MODEL_CONFIGS: 4개 프로바이더(Anthropic, AWS Bedrock, GCP Vertex, Azure)의 모델 레지스트리
• 선택 우선순위 체인: 5개 레이어를 순서대로 평가하여 최종 모델 결정
• 모델 앨리어스: [1m] 접미사를 포함한 편의 이름 매핑
• 노력 수준: auto/low/medium/high/max의 5단계 추론 제어

ALL_MODEL_CONFIGS는 모든 지원 모델의 구성 정보를 담는 중앙 레지스트리입니다. 각 모델 항목은 프로바이더, 컨텍스트 크기, 토큰 가격, 기능 플래그 등을 포함합니다.

// models/config.ts — 4프로바이더 모델 레지스트리
const ALL_MODEL_CONFIGS: ModelConfig[] = [
  // Anthropic 직접 API
  {
    id: 'claude-opus-4-6',
    provider: 'anthropic',
    contextWindow: 200_000,
    extendedContextWindow: 1_000_000,
    maxOutputTokens: 32_768,
    inputPricePer1M: 15.00,
    outputPricePer1M: 75.00,
    supportsExtendedThinking: true,
  },
  // AWS Bedrock
  {
    id: 'anthropic.claude-opus-4-6-v1:0',
    provider: 'bedrock',
    contextWindow: 200_000,
    // Bedrock는 확장 컨텍스트 미지원
    maxOutputTokens: 32_768,
  },
  // GCP Vertex AI
  {
    id: 'claude-opus-4-6@20250515',
    provider: 'vertex',
    contextWindow: 200_000,
  },
  // Azure (OpenAI 호환)
  {
    id: 'claude-opus-4-6',
    provider: 'azure',
    contextWindow: 200_000,
  },
  // ... 다수의 추가 모델 구성
]

모델 선택은 5개 레이어를 순서대로 평가하여 결정됩니다. 높은 우선순위 레이어에서 모델이 지정되면 하위 레이어는 무시됩니다.

// models/selector.ts — 5레이어 우선순위 체인
function resolveModel(context: ModelContext): ResolvedModel {
  // 레이어 1: CLI 인수 (--model 플래그)
  if (context.cliModel) return resolve(context.cliModel)

  // 레이어 2: 환경 변수 (CLAUDE_MODEL)
  if (process.env.CLAUDE_MODEL) return resolve(process.env.CLAUDE_MODEL)

  // 레이어 3: 프로젝트 설정 (.claude/settings.json)
  if (context.projectConfig?.model) return resolve(context.projectConfig.model)

  // 레이어 4: 글로벌 설정 (~/.claude/settings.json)
  if (context.globalConfig?.model) return resolve(context.globalConfig.model)

  // 레이어 5: 기본값
  return resolve(DEFAULT_MODEL)
}

모델 앨리어스는 긴 모델 ID 대신 편의 이름을 사용할 수 있게 합니다. [1m] 접미사는 1M 컨텍스트 윈도우를 활성화하는 런타임 플래그입니다.

// models/aliases.ts — 앨리어스 매핑 & [1m] 접미사
const MODEL_ALIASES: Record<string, string> = {
  'opus':    'claude-opus-4-6',
  'sonnet':  'claude-sonnet-4-6',
  'haiku':   'claude-haiku-3-5',
}

function resolve(input: string): ResolvedModel {
  // [1m] 접미사 감지 & 제거
  const use1m = input.endsWith('[1m]')
  const modelName = use1m ? input.slice(0, -4) : input

  // 앨리어스 해석
  const modelId = MODEL_ALIASES[modelName] ?? modelName

  // 레지스트리에서 설정 조회
  const config = ALL_MODEL_CONFIGS.find(c => c.id === modelId)

  return {
    ...config,
    contextWindow: use1m && config?.extendedContextWindow
      ? config.extendedContextWindow  // 1M 활성화
      : config?.contextWindow ?? 200_000,
  }
}

1M 컨텍스트 윈도우

[1m] 접미사가 붙으면 모델의 extendedContextWindow(1,000,000 토큰)이 활성화됩니다. 이는 런타임 플래그이므로 모델 자체가 변경되는 것이 아니라, API 요청 시 확장 컨텍스트 헤더가 포함됩니다.

노력 수준(effort level)은 모델의 추론 깊이를 제어합니다. 5단계(auto, low, medium, high, max)로 구분되며, 각 수준은 API의 thinking 파라미터에 매핑됩니다.

// models/effort.ts — 5단계 노력 수준
type EffortLevel = 'auto' | 'low' | 'medium' | 'high' | 'max'

function mapEffortToThinking(effort: EffortLevel): ThinkingConfig {
  switch (effort) {
    case 'low':
      return { type: 'disabled' }
    case 'medium':
      return { type: 'enabled', budget: 2048 }
    case 'high':
      return { type: 'enabled', budget: 8192 }
    case 'max':
      return { type: 'enabled', budget: 32768 }
    case 'auto':
    default:
      return { type: 'auto' }
  }
}

빠른 모드 (Fast Mode)

빠른 모드는 노력 수준을 low로 강제하여 추론(thinking)을 비활성화합니다. 간단한 질문이나 빠른 코드 편집에 적합하며, 응답 지연 시간과 토큰 비용을 크게 줄입니다.

엔터프라이즈 환경에서는 사용 가능한 모델을 허용 목록으로 제한할 수 있습니다. 3단계 매칭과 축소 규칙이 적용됩니다.

// models/allowlist.ts — 3단계 매칭 & 축소 규칙
function isModelAllowed(modelId: string, allowlist: AllowlistConfig): boolean {
  // 단계 1: 정확한 ID 매칭
  if (allowlist.exact.includes(modelId)) return true

  // 단계 2: 프로바이더 와일드카드 매칭
  const provider = getProvider(modelId)
  if (allowlist.providers.includes(provider)) return true

  // 단계 3: 패턴 글로브 매칭
  return allowlist.patterns.some(p => globMatch(modelId, p))
}

// 축소 규칙: 허용되지 않은 모델이 요청되면
// 같은 프로바이더의 허용된 모델 중 가장 유사한 것으로 축소
function shrinkToAllowed(modelId: string, allowlist: AllowlistConfig): string {
  if (isModelAllowed(modelId, allowlist)) return modelId

  const provider = getProvider(modelId)
  const allowed = allowlist.exact.filter(id => getProvider(id) === provider)
  return findClosestModel(modelId, allowed) ?? DEFAULT_MODEL
}

서브에이전트 모델 상속

서브에이전트(태스크나 도구 실행을 위해 생성되는 하위 Claude 인스턴스)는 부모 에이전트의 모델 설정을 상속합니다. 이는 허용 목록 정책이 서브에이전트에도 일관되게 적용되도록 보장합니다.

모델 이름이 변경되거나 새 버전이 출시될 때, 사용자 구성에 저장된 이전 모델 ID를 자동으로 업그레이드하는 마이그레이션이 실행됩니다.

// models/migration.ts — 6개 마이그레이션 함수
const MODEL_MIGRATIONS: Migration[] = [
  { from: 'claude-3-opus',     to: 'claude-opus-4-6' },
  { from: 'claude-3-sonnet',   to: 'claude-sonnet-4-6' },
  { from: 'claude-3.5-sonnet', to: 'claude-sonnet-4-6' },
  { from: 'claude-opus-4-5',   to: 'claude-opus-4-6' },
  { from: 'claude-sonnet-4-5', to: 'claude-sonnet-4-6' },
  { from: 'opus',              to: 'opus[1m]' },
]

function migrateModelId(modelId: string): string {
  const migration = MODEL_MIGRATIONS.find(m => m.from === modelId)
  if (migration) {
    console.warn(`모델 "${modelId}" → "${migration.to}"로 마이그레이션됨`)
    return migration.to
  }
  return modelId
}

검증 & 폐기

마이그레이션 테이블에 없는 인식되지 않는 모델 ID는 경고를 출력하고 기본 모델로 폴백합니다. 폐기된 모델은 deprecated: true 플래그가 설정되며, 사용 시 경고 메시지가 표시됩니다.