모델 별칭 & 1M 컨텍스트

Claude Code는 요청이 shunt에 도달하기 전에 짧은 별칭(opus, sonnet, haiku, fable, opusplan)을 클라이언트 측에서 해석합니다. 해석에 사용하는 표는 CLI 바이너리에 컴파일되어 있으며, 두 분기는 세션이 연결된 방식을 기준으로 동작합니다. ANTHROPIC_BASE_URL이 shunt를 가리키면 두 분기가 모두 달라집니다. 따라서 같은 /model opus도 api.anthropic.com에 연결할 때와 다른 모델을 선택할 수 있습니다.

shunt는 이 과정에 영향을 줄 수 없습니다. shunt가 요청을 확인할 때는 이미 선택이 끝났습니다. 대신 shunt는 결과를 다시 매핑할 수 있습니다. 의도한 티어 복구를 참고하세요.

두 가지 게이트

이 페이지에서 설명하는 차이는 모두 다음 두 게이트에서 비롯됩니다.

두 번째 게이트는 호스트가 정확히 일치하는지 확인합니다. Anthropic에 패스스루 자격 증명을 그대로 전달하는 shunt 인스턴스를 포함해 base URL이 api.anthropic.com이 아니면 모두 이 게이트를 통과하지 못합니다.

별칭 해석

opus와 sonnet에는 배포별 오버라이드가 있습니다. fable과 haiku에는 없으므로 어디서나 같은 방식으로 해석됩니다.

게이트웨이 열이 예상과 다릅니다. 게이트웨이 세션에서 opus는 두 릴리스 이전, sonnet은 한 릴리스 이전 버전으로 고정됩니다. 이 고정값은 확인한 릴리스(2.1.217~2.1.220)에서 바뀌지 않았고, 달라진 것은 다른 열입니다. Claude Code 2.1.219에서 비게이트웨이 opus 기본값이 Opus 4.8에서 Opus 5로 바뀌었습니다. 이에 따라 4.8과 4.7의 차이가 5와 4.7의 차이로 벌어져 고정값이 눈에 띄게 되었습니다.

Anthropic은 서드 파티 프로바이더(Bedrock, Vertex, Foundry)에 해당하는 표를 문서화했지만 게이트웨이 행은 나열하지 않습니다. 따라서 이 차이를 놓치기 쉽습니다.

[1m]은 shunt에 도달하지 않음

이 접미사는 모델 id의 일부가 아니라 클라이언트 측 힌트입니다. Claude Code는 접미사를 제거한 뒤 요청을 전송하고 대신 beta 헤더로 표현합니다.

POST /v1/messages?beta=true
{"model": "claude-opus-5", ...}
anthropic-beta: claude-code-20250219,context-1m-2025-08-07,...

따라서 shunt는 통신 과정에서 claude-opus-5[1m]을 확인하지 못합니다. 대신 claude-opus-5와 context-1m-2025-08-07을 확인합니다. (shunt는 라우트 매칭과 availableModels 적용 전에 후행 [1m]/[1M]도 제거합니다. 따라서 직접 작성한 클라이언트에서 힌트가 실제로 도달해도 올바르게 라우팅됩니다.)

1M 컨텍스트가 자동으로 적용되지 않음

Claude Code는 명시적인 [1m], context-1m beta 헤더, 이 배포에서 모델이 기본적으로 1M을 지원하는지 순서로 컨텍스트 윈도우 크기를 정합니다. 마지막 확인에는 api.anthropic.com 호스트 게이트를 통과해야 합니다. 다른 base URL 뒤에서는 이 확인에 실패하므로 기본적으로 1M을 지원하는 모델도 200K 기본값으로 폴백합니다.

Anthropic도 같은 제약을 설명합니다. “ANTHROPIC_BASE_URL이 게이트웨이를 가리키면 Claude Code는 1M 지원을 확인할 수 없습니다.” (확장 컨텍스트)

shunt 뒤에서는 항상 접미사를 쓰는 것이 실용적인 규칙입니다. /model opus[1m], /model fable[1m]을 사용하거나 고정값에 접미사를 포함하세요.

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-5[1m]'

알아 두어야 할 세부 사항은 두 가지입니다.

• 확인한 모든 릴리스(2.1.217~2.1.220)에서 접미사 없는 별칭은 [1m]을 자동으로 적용한 적이 없습니다. 업그레이드 후 1M이 더 이상 표시되지 않는다면 별칭 처리 변경이 아니라 위에서 설명한 윈도우 확인이 원인입니다.
• claude-fable-5의 카탈로그 항목에는 [1m] 변형이 없습니다. 이 모델은 기본적으로 1M만 지원합니다. api.anthropic.com에서 입력한 fable[1m]은 조용히 fable로 축약됩니다. shunt 뒤에서는 전체 윈도우를 사용하는 유일한 방법이므로 접미사를 유지합니다.

여기서 CLAUDE_CODE_MAX_CONTEXT_TOKENS는 우회 방법이 아닙니다. 노력 & 컨텍스트에서 설명한 대로 claude-로 시작하지 않는 id에만 적용됩니다.

선택기에서 Fable이 사라짐

Fable도 같은 호스트 확인을 거칩니다. 배포가 firstParty이고 base URL이 api.anthropic.com이 아니면 Claude Code는 /model에서 모든 Fable 항목을 필터링하고, 설정된 claude-fable-5가 없다고 보고합니다. 이때 settings.json의 "model": "claude-fable-5[1m]"은 조용히 Opus로 폴백합니다.

게이트웨이 로그인 세션에는 이 필터가 적용되지 않으므로 Fable을 계속 선택할 수 있습니다. base URL 경로에서 Fable을 사용하는 방법은 두 가지가 더 있습니다.

# Bypasses the availability check entirely
export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5

명시적인 --model fable / /model fable도 해석됩니다. 가용성 게이트는 id의 직접 해석이 아니라 선택기와 저장된 기본값을 제어하기 때문입니다. 이 동작은 2.1.217~2.1.220에서 바뀌지 않았습니다.

의도한 티어 복구

shunt는 클라이언트가 선택하는 모델을 바꿀 수 없지만 요청이 통과할 때 모델을 다시 쓸 수 있습니다. 사용자가 게이트웨이 로그인을 사용하고 opus/sonnet 별칭을 현재 티어에 연결하려면 고정된 id를 다시 매핑하세요.

[[routes]]
model = "claude-opus-4-7"        # what a gateway session sends for `opus`
provider = "anthropic"
upstream_model = "claude-opus-5" # what you want it to actually run

[[routes]]
model = "claude-sonnet-4-6"
provider = "anthropic"
upstream_model = "claude-sonnet-5"

선별한 [[models]] 항목에는 영향을 주지 않습니다. 디스커버리된 id는 선택기에서 그대로 선택되며 별칭 표를 거치지 않습니다.

버전 기록

설치된 각 CLI 바이너리에서 별칭 표를 추출하고 요청 캡처와 결과를 대조하여 확인했습니다.

Opus 5에는 Claude Code 2.1.219 이상이 필요합니다. 2.1.217~2.1.218에서는 어떤 배포에서도 opus 별칭으로 Opus 5를 사용할 수 없습니다.