SpyBara
Go Premium

llm-gateway-protocol.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 62 additions and 62 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sat 3 23:57 Mon 5 23:58 Tue 6 23:59 Thu 8 22:58 Tue 13 23:57 Wed 14 22:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57

Claude Code 게이트웨이 호환성 가이드

Claude Code와 호환되는 LLM 게이트웨이 유지: 호출하는 엔드포인트, 전달해야 할 헤더 및 본문 필드, 그리고 제거될 때 중단되는 기능.

이 페이지는 Claude Code가 게이트웨이로 전송하는 요청을 문서화하며, 호출하는 엔드포인트, 게이트웨이가 전달해야 할 헤더 및 본문 필드, 그리고 전달하지 않을 때 작동을 멈추는 기능을 포함합니다. 이 문서는 Claude Code와 함께 작동하도록 게이트웨이 제품을 구성하는 운영자를 위해 작성되었습니다.

Claude 앱 게이트웨이는 Anthropic의 자체 호스팅 게이트웨이이며, GET /protocol에서 자체 엔드포인트 참조를 제공하며, 해당 게이트웨이의 로그인, 추론, 관리 설정, 모델 검색 및 원격 분석 엔드포인트를 다룹니다. 이는 이 가이드와는 별개의 문서입니다.

[!NOTE]

이 페이지는 다음을 다룹니다:

이 페이지는 게이트웨이가 각 헤더 및 본문 필드로 수행하는 작업에 대해 두 가지 용어를 사용합니다:

  • 변경 없이 전달: 바이트 단위로 업스트림에 전달
  • 사용: 게이트웨이가 라우팅, 속성 또는 추적을 위해 읽을 수 있으며 전달할 필요가 없음

변경 없이 전달로 표시되지 않은 모든 것은 사용하거나 무시할 수 있습니다.

API 형식

게이트웨이는 Claude Code 클라이언트에 다음 API 형식 중 최소 하나 이상을 노출해야 합니다. 클라이언트는 형식을 선택하고 아래 표의 선택됨 열에 있는 변수를 사용하여 Claude Code를 게이트웨이로 지정합니다.

Google Cloud의 Agent Platform은 Google Cloud의 Claude 엔드포인트이며, 이전의 Vertex AI입니다. 변수 이름은 VERTEX 표기법을 유지합니다.

형식 선택됨 엔드포인트 변경 없이 전달
Anthropic Messages ANTHROPIC_BASE_URL /v1/messages, /v1/messages/count_tokens (선택사항) anthropic-beta 및 anthropic-version 요청 헤더
Amazon Bedrock InvokeModel ANTHROPIC_BEDROCK_BASE_URL과 CLAUDE_CODE_USE_BEDROCK=1 /model/{model}/invoke, /model/{model}/invoke-with-response-stream, /model/{model}/count-tokens (선택사항) anthropic_beta 및 anthropic_version 요청 본문 필드
Google Cloud의 Agent Platform rawPredict ANTHROPIC_VERTEX_BASE_URL과 CLAUDE_CODE_USE_VERTEX=1 :rawPredict, :streamRawPredict, count-tokens:rawPredict (선택사항) anthropic-beta 및 anthropic-version 요청 헤더, 그리고 anthropic_version 요청 본문 필드

Foundry 및 AWS의 Claude Platform

Microsoft Foundry 및 AWS의 Claude Platform은 Anthropic Messages 형식을 구현합니다. Claude Code는 자체 변수인 ANTHROPIC_FOUNDRY_BASE_URL 및 ANTHROPIC_AWS_BASE_URL을 통해 이들로 라우팅하지만, 둘 중 하나를 앞에 두는 게이트웨이는 위의 Anthropic Messages 행을 구현합니다. AWS의 Claude Platform을 앞에 두는 게이트웨이는 또한 anthropic-workspace-id 헤더를 전달해야 하며, 해당 플랫폼은 모든 요청에서 이를 요구합니다.

선택사항 엔드포인트 및 시작 트래픽

토큰 계산 엔드포인트는 유일한 선택사항입니다. 이들이 없을 때 Claude Code는 컨텍스트 사용량의 문자 기반 추정으로 폴백합니다.

경로로 일치시킵니다. 전체 URL이 아닙니다:

  • 추론 요청은 /v1/messages?beta=true로 게시됩니다
  • Google Cloud의 Agent Platform 메서드 접미사는 게시자 모델 경로에 첨부됩니다(예: /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict).

게이트웨이는 또한 아무것도 깨지 않고 거부할 수 있는 최선의 노력 시작 트래픽을 봅니다. Anthropic Messages 형식 게이트웨이는 HEAD /api/hello 연결 워밍 프로브를 수신하며, Claude Code는 HTTP 프록시 또는 클라이언트 인증서가 구성되어 있을 때 이를 건너뜁니다. Amazon Bedrock 형식 게이트웨이는 GET /inference-profiles?type=SYSTEM_DEFINED 요청을 수신하고, 구성된 모델이 추론 프로필일 때 GET /inference-profiles/{profile} 조회를 수신합니다.

게이트웨이를 거치는 세션은 HIPAA 구성의 대상이 아닙니다. 개발자의 로그인 및 연결 방식 확인에는 대상이 되는 로그인 및 연결 방법이 나열되어 있습니다. 게이트웨이 뒤의 HIPAA 구성을 참조하세요.

빠른 모드 가용성 확인은 게이트웨이 로그에 나타나지 않습니다. ANTHROPIC_BASE_URL을 따르지 않고 api.anthropic.com을 직접 호출하므로, api.anthropic.com으로의 직접 송신을 차단하는 네트워크에서 빠른 모드는 연결 오류를 보고할 수 있지만 게이트웨이를 통한 추론은 계속 작동합니다. WebFetch 도메인 안전 확인도 api.anthropic.com을 직접 호출합니다. 프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용은 이를 복원하는 변수를 다룹니다.

스트리밍

Claude Code는 각 스트리밍 추론 응답을 도착하는 대로 이벤트 단위로 읽으므로, 게이트웨이가 스트림을 릴레이하는 방식은 사용자가 보는 내용에 영향을 줍니다:

  • 게이트웨이가 응답이 완료될 때까지 버퍼링하면 Claude Code가 정지됩니다.
  • Claude Code는 최종 message_delta 및 message_stop 이벤트까지 각 응답의 전체 이벤트 시퀀스를 순서대로 받기를 기대합니다. 콘텐츠 블록이 시작된 후 최종 message_delta 전에 본문이 깔끔하게 끝나면, Claude Code는 해당 응답을 끊어진 연결로 처리합니다. 위의 응답이 불완전할 수 있습니다는 이때 사용자가 보는 내용을 설명하며, 자동 재시도는 Claude Code가 대신 요청을 다시 발행하는 경우를 설명합니다.
  • Amazon Bedrock 가드레일이 응답을 차단하면, Bedrock이 보내는 이벤트가 content_block_stop이 이미 도착한 콘텐츠 블록을 참조할 수 있으며, Claude Code는 이 이벤트를 보낸 그대로 수신하는 것에 의존합니다. AWS Guardrails는 해당 응답이 어떻게 끝나는지 설명합니다.
  • Claude Code는 스트리밍 유휴 타임아웃보다 오래 바이트가 도달하지 않으면 스트리밍 응답을 중단합니다. 긴 사고 일시 중지 중에는 업스트림의 SSE ping 이벤트가 스트림의 유일한 바이트일 수 있으므로, 이를 제거하거나 버퍼링하는 게이트웨이는 응답 도중에 이 타임아웃을 유발할 수 있습니다. Amazon Bedrock의 이진 이벤트 스트림처럼 핑이 없는 업스트림에서 변환하는 게이트웨이도 자체 ping 이벤트를 내보내지 않는 한 동일한 공백이 생깁니다.
  • Amazon Bedrock InvokeModel 형식에서 Claude Code는 /model/{model}/invoke-with-response-stream 응답을 Bedrock이 반환하는 이진 application/vnd.amazon.eventstream 본문으로 읽으며, 게이트웨이가 이를 서버 전송 이벤트로 변환하거나 해당 Content-Type 헤더를 다시 작성하면 파싱할 수 없습니다. 게이트웨이 또는 프록시 뒤의 스트리밍 오류는 이때 사용자가 보는 내용을 설명합니다.

업스트림과의 형식 불일치

클라이언트가 사용하는 형식은 게이트웨이가 수신하는 것을 결정합니다. 일반적인 실패 모드는 클라이언트가 게이트웨이로 보내는 형식과 뒤의 업스트림 제공자가 허용하는 형식 간의 불일치입니다.

  • 클라이언트가 Amazon Bedrock 또는 Google Cloud의 Agent Platform 형식을 사용할 때, Claude Code는 해당 제공자가 허용하는 전체 기능 집합의 부분 집합만 보냅니다
  • 클라이언트가 Anthropic Messages 형식을 사용할 때, 게이트웨이가 Amazon Bedrock 또는 Google Cloud의 Agent Platform 업스트림으로 전달하더라도 Claude Code는 전체 집합을 보냅니다

그 차이를 연결하는 것은 게이트웨이의 작업입니다. 기능 통과는 그렇지 않을 때 무엇이 깨지는지 설명합니다.

업스트림이 Amazon Bedrock 또는 Google Cloud의 Agent Platform인 경우, 대신 해당 제공자의 형식을 노출하여 연결을 피할 수 있습니다. 게이트웨이를 통해 클라우드 제공자로 라우팅은 해당 형식의 클라이언트 구성을 보여줍니다.

연결 방법이 클라이언트 동작을 변경하는 방식

개발자가 게이트웨이에 연결하는 방식에 따라 Claude Code가 전송하는 모델 ID, anthropic-beta 값, 요청 필드가 결정되며, 적용되는 기본값도 달라집니다. 게이트웨이는 다음 세 가지 클라이언트 동작 중 하나를 확인합니다:

  • Amazon Bedrock 또는 Agent Platform 형식: 개발자가 CLAUDE_CODE_USE_BEDROCK=1을 ANTHROPIC_BEDROCK_BASE_URL과 함께 설정하거나, CLAUDE_CODE_USE_VERTEX=1을 ANTHROPIC_VERTEX_BASE_URL과 함께 설정하여 게이트웨이를 가리킵니다. Claude Code는 해당 제공자의 모델 ID, 요청 필드 및 기본값을 사용합니다.
  • Anthropic Messages 형식: 개발자가 ANTHROPIC_BASE_URL을 게이트웨이로 설정합니다. Claude Code는 게이트웨이를 Claude API로 취급하며 어느 업스트림으로 전달하는지 알 수 없습니다.
  • Claude 앱 게이트웨이 로그인: 개발자가 Claude 앱 게이트웨이에 로그인합니다. 해당 게이트웨이는 Anthropic Messages 형식을 사용하지만 모든 업스트림으로 라우팅할 수 있으므로, Claude Code는 Amazon Bedrock 및 Agent Platform도 허용하는 anthropic-beta 값과 모델 기능 가정만 전송합니다.

연결 방법별 요청 및 기본값

아래 표는 세 가지 연결 방법을 비교하며, 행마다 하나의 동작을 나타냅니다. Microsoft Foundry 및 Claude Platform on AWS는 Anthropic Messages 형식을 사용하지만 Claude Code가 자체 변수를 통해 도달하므로 제외되었습니다. 이들의 경우 Microsoft Foundry 및 Claude Platform on AWS 페이지를 참조하십시오.

동작 Amazon Bedrock 또는 Agent Platform 형식 Anthropic Messages 형식 Claude 앱 게이트웨이 로그인
기본적으로 요청의 모델 ID Amazon Bedrock의 us.anthropic.claude-opus-4-8과 같은 제공자 형식 claude-opus-4-8과 같은 Anthropic ID Anthropic ID
전송되는 anthropic-beta 값 Amazon Bedrock 및 Agent Platform이 허용하는 부분 집합 기능 통과에 설명된 전체 집합, 개발자가 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 설정하지 않은 경우 Amazon Bedrock 및 Agent Platform이 허용하는 부분 집합
Claude Code가 인식하지 못하는 모델 ID(예: 게이트웨이 별칭)에 대한 요청 필드 적응형 추론이 아닌 고정 예산의 사고, 그리고 노력 또는 컨텍스트 관리 필드 없음. Claude Code는 여전히 대화 중간 시스템 메시지를 전송함 Amazon Bedrock 또는 Agent Platform 업스트림이 거부할 수 있는 적응형 추론, 노력 및 컨텍스트 관리를 포함하여 현재 Claude 모델이 Claude API에서 허용하는 모든 것 Amazon Bedrock 또는 Agent Platform 형식과 동일
개발자가 옵트인할 때 1시간 프롬프트 캐시 TTL cache_control의 ttl 필드를 통해 요청되며, 베타 값 없음 ttl 필드와 anthropic-beta의 extended-cache-ttl 값을 통해 요청되며, 이를 전달해야 함 ttl 필드를 통해 요청되며, 베타 값 없음. 1시간 프롬프트 캐시 참조
ANTHROPIC_DEFAULT_HAIKU_MODEL이 하나를 고정하지 않는 한 백그라운드 작업용 모델 기본 Sonnet 모델, 또는 하나가 선택되면 주 모델, Amazon Bedrock 및 Agent Platform 페이지에서 설명하는 대로 주 모델, 또는 ANTHROPIC_API_KEY 또는 apiKeyHelper가 Anthropic Console 키를 제공하고 ANTHROPIC_AUTH_TOKEN이 설정되지 않은 경우 기본 Haiku 모델 주 모델

각 연결이 지원하는 기능과 기본적으로 Anthropic에 전송하는 원격 측정에 대해서는 기능 가용성 및 API 제공자별 기본 동작을 참조하십시오.

인식되지 않는 모델 ID에 대한 설정

두 가지 클라이언트 측 설정은 개발자가 사용하는 연결 방법에 관계없이 Claude Code가 인식하지 못하는 모델 ID에 대해 가정하는 것을 변경합니다:

  • 컨텍스트 윈도우: Claude Code는 200K를 가정하거나, ID에 [1m]이 포함되면 1M을 가정합니다. 실제 윈도우를 선언하려면 게이트웨이 또는 사용자 정의 모델 ID에 대한 윈도우 수정을 참조하십시오.
  • 기능: 게이트웨이 별칭에 뒤에 있는 모델의 기능을 제공하려면, 해당 모델의 Anthropic ID를 배포하는 설정의 modelOverrides 항목으로 별칭에 매핑하십시오. ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 변수가 적용되는 위치에 대해서는 기능 통과를 참조하십시오.

요청 헤더

Claude Code는 API 요청에 이러한 헤더를 포함합니다. 헤더 이름은 전송 중에 대소문자를 구분하지 않습니다. anthropic-version 및 anthropic-beta를 변경 없이 전달하고, 업스트림이 AWS의 Claude Platform일 때 anthropic-workspace-id를 전달합니다. 나머지는 게이트웨이가 라우팅, 속성 및 추적을 위해 사용할 수 있으며 전달할 필요가 없습니다.

헤더 설명
Authorization, x-api-key 개발자의 게이트웨이 자격 증명. 설정한 자격 증명 변수에 따라 하나 또는 두 헤더 모두에 포함됨
anthropic-version API 버전. 현재 2023-06-01. Amazon Bedrock 및 Google Cloud의 Agent Platform 형식 요청은 또한 anthropic_version 본문 필드를 전달하며, 그 값은 이 헤더의 값이 아닌 제공자 방언 문자열입니다.
anthropic-beta 요청에 대한 쉼표로 구분된 기능 값. 헤더를 그대로 전달합니다. 개별 값을 허용 목록에 추가하지 마십시오. Claude Code 릴리스에 따라 집합이 변경되기 때문입니다. 개발자가 claude.ai 로그인으로 인증할 때 (이는 ANTHROPIC_BASE_URL이 게이트웨이 자격 증명 변수 없이 설정될 때 가능함), 이 헤더는 또한 업스트림이 요구하는 OAuth 기능을 전달하며, 이를 제거하면 해당 요청이 401로 실패합니다.
x-claude-code-session-id 현재 Claude Code 세션의 고유 식별자. 요청 본문을 구문 분석하지 않고 한 세션의 모든 요청을 집계하는 데 사용합니다.
x-claude-code-agent-id 요청을 발급한 서브에이전트의 식별자. 세션 내에서 Claude Code가 생성한 에이전트의 요청에만 존재합니다. 세션 ID와 함께 사용하여 병렬 에이전트에 비용을 속성화합니다.
x-claude-code-parent-agent-id 요청하는 에이전트를 생성한 에이전트의 식별자. 중첩된 에이전트에만 존재합니다.

서브에이전트 ID는 각 생성 시마다 새로 생성됩니다. 팀 에이전트 (즉, 에이전트 팀의 명명된 멤버)는 재연결 시 안정적인 이름 기반 ID를 재사용합니다. 두 경우 모두 ID는 사람이나 장치가 아닌 에이전트를 식별하므로, 에이전트 ID 헤더를 사용자 식별자로 취급하지 마십시오.

개발자가 ANTHROPIC_CUSTOM_HEADERS를 설정하면, 해당 헤더도 요청에 나타납니다.

게이트웨이 힌트 헤더

Claude Code는 또한 라우팅 힌트를 전송할 수 있습니다. 게이트웨이 또는 라우터가 요청을 스케줄링, 캐싱 또는 속성화하는 데 사용할 수 있는 요청별 팩트입니다. Claude Code v2.1.273 이상이 필요합니다.

요청이 이를 전달하는지 여부는 Claude Code가 이를 전송하는 위치에 따라 다릅니다.

  • Anthropic API에 직접 연결: 기본적으로 전송됨
  • 사용자 정의 기본 URL: 기본적으로 꺼짐. 알 수 없는 헤더를 거부하는 프록시가 요청을 실패시킬 수 있기 때문입니다. 이를 수신하려면 개발자를 위해 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1을 설정합니다. 예를 들어 관리 설정의 env 블록에서 설정합니다.
  • Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, AWS의 Claude Platform을 포함한 다른 모든 백엔드: CLAUDE_CODE_GATEWAY_HINT_HEADERS=1이 설정되었을 때만 전송됨

CLAUDE_CODE_GATEWAY_HINT_HEADERS를 0으로 설정하면 모든 연결에서 헤더가 중지됩니다.

헤더는 아래 행에 나열된 것만 전달합니다. 고정된 어휘, 도구 이름 및 기간이며, 프롬프트 텍스트나 파일 내용은 절대 아닙니다. 모든 값은 인쇄 가능한 ASCII입니다.

헤더 설명
x-claude-code-request-class 이 요청의 종류: 주 대화의 턴에 대해 main, 서브에이전트의 턴에 대해 subagent, 워크플로우 내에서 실행되는 에이전트에 대해 workflow, 대화를 압축하는 요약 요청에 대해 compaction, 세션 제목, 분류기 및 요약과 같은 측면 요청에 대해 auxiliary. 모든 요청에서 전송됨
x-claude-code-agent-type 요청을 발급한 서브에이전트의 종류: Explore, Plan 또는 general-purpose와 같은 기본 제공 에이전트 타입 이름, 사용자 정의 에이전트에 대해 custom, 에이전트 팀 멤버가 리드의 프로세스에서 실행 중일 때 teammate, 또는 포크에 대해 fork. 서브에이전트 자신의 턴에만 존재합니다. 서브에이전트의 압축 또는 측면 요청은 에이전트 ID를 유지하지만 타입을 전달하지 않습니다. 사용자가 선택한 에이전트 이름은 절대 전송되지 않습니다.
x-claude-code-compaction 압축 중에 대화를 요약하는 요청에 존재합니다. 값은 트리거된 것을 나타냅니다: 컨텍스트 윈도우가 용량에 접근할 때 auto, /compact에 대해 manual, API가 요청을 너무 길다고 거부했을 때 reactive. 유휴 압축의 경우에도 값은 auto입니다. 다른 모든 요청에서는 없습니다.
x-claude-code-context-compacted 압축 후 첫 번째 주 대화 요청에 한 번 존재하며, x-claude-code-compaction과 동일한 값을 가집니다. 이 요청 전의 대화 접두사는 더 이상 사용되지 않으므로, 이를 기반으로 키가 지정된 캐시를 삭제할 수 있습니다.
x-claude-code-prev-tool-durations 이 요청이 전달하는 결과의 도구 호출의 측정된 실행 시간. <name>=<ms>;<name>=<ms> 형식입니다. 예를 들어 Bash=742;Read=9. 도구 호출 배치 후 동일한 대화의 다음 요청에서 전송됩니다. 주 세션 또는 서브에이전트에서 전송됩니다.
x-claude-code-prompt-id 요청이 제공하는 사용자 프롬프트를 식별하는 무작위 UUID입니다. 하나의 프롬프트를 제공하는 요청은 값을 공유하며, 프롬프트가 시작한 서브에이전트의 턴을 포함합니다. 프롬프트에 속하지 않은 요청은 이를 생략합니다. 이를 사용하여 세션의 요청을 프롬프트별로 그룹화합니다. Claude Code v2.1.283 이상이 필요합니다.

x-claude-code-prev-tool-durations를 구문 분석하기 전에 Claude Code가 값을 구성하는 방법과 생략하는 것을 확인합니다.

  • 항목: 실행된 도구 호출당 하나씩, 결과가 수집된 순서대로, 전체 밀리초 단위
  • 상한: Claude Code는 최대 32개 항목과 4 KB를 전송하며, 첫 번째 항목을 유지합니다.
  • 인코딩: 도구 이름은 퍼센트 인코딩되며, %, ;, =, 쉼표, 공백 및 인쇄 가능한 ASCII 외의 모든 문자를 포함합니다.
  • 구문 분석: ;로 분할한 다음 =로 분할하고 각 이름을 디코딩합니다.
  • 부재: 압축 호출, 측면 요청 및 새 프롬프트의 첫 번째 요청은 이를 전달하지 않습니다. 누락된 헤더를 도구를 실행하지 않은 턴으로 읽지 마십시오.
  • 시간: 각각은 권한 프롬프트 및 훅을 제외하며, 병렬 도구 호출은 각각 자신의 시간을 보고하므로, 항목이 요청 간의 간격에 합산되지 않습니다.

개방형 목록으로 전달

헤더 및 본문 필드를 닫힌 목록이 아닌 개방형 목록으로 취급합니다. Claude Code는 릴리스에 따라 기능을 얻으며, 이들은 새로운 anthropic-beta 값, 새로운 요청 본문 필드, 그리고 때때로 새로운 anthropic-* 또는 x-claude-code-* 헤더로 도착합니다.

Anthropic 형식 업스트림으로 전달할 때, 오늘 보는 것들을 허용 목록에 추가하기보다는 anthropic-* 요청 헤더 및 요청 본문 필드를 변경 없이 통과시킵니다. 관찰된 목록에 고정된 게이트웨이는 다음 기능의 헤더 또는 필드를 제거하고 이를 도입하는 릴리스에서 손상시킵니다.

예외는 Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 비 Anthropic 업스트림입니다. 여기서 스키마 차이를 연결하는 것은 게이트웨이의 작업입니다. 기능 통과를 참조하십시오.

응답 헤더

Claude Code는 이러한 응답 헤더를 읽어 정지된 스트림을 감지하고, 재시도 여부 및 시기를 결정하며, 사용량 제한을 표시합니다. 다음 표는 각 헤더에 대해 반환할 내용을 나열합니다. 또한 오류 응답 본문을 수정하지 않고 전달하여 Claude Code의 기능 거부 복구가 업스트림의 오류 표현과 일치할 수 있도록 합니다.

헤더 반환할 내용 및 이유
content-type 스트리밍된 Anthropic Messages 형식 응답에서는 text/event-stream을 반환하고, Amazon Bedrock 형식 응답에서는 application/vnd.amazon.eventstream을 수정하지 않고 반환합니다. 여기서 다른 유형은 요청을 실패시킵니다
retry-after HTTP 날짜가 아닌 정수 초를 반환합니다. Claude Code는 다음 자동 재시도 전에 최소한 그 시간만큼 대기하며, CLAUDE_CODE_RETRY_WATCHDOG 세션 외부에서 60 이상의 값은 재시도를 중지하고 오류를 즉시 표시합니다
x-should-retry 업스트림의 값을 수정하지 않고 그대로 전달합니다. Claude Code는 실패한 요청을 재시도할지 결정할 때 이 헤더를 하나의 입력으로 읽습니다: true는 응답을 재시도 가능으로 표시하고 false는 재시도 불가능으로 표시합니다. 재시도 횟수, 백오프 및 Claude Code가 재시도하는 실패에 대해서는 자동 재시도를 참조하세요
anthropic-ratelimit-unified-* 모든 응답에서 업스트림의 값을 수정하지 않고 전달합니다. Claude Code는 성공한 응답에서 이를 읽어 claude.ai로 로그인한 개발자에게 계획 제한에 대한 사용량을 표시하고, 429에서 계획 제한 또는 지출 한도를 임시 제한과 구분합니다. 사용량 제한을 참조하세요

시스템 프롬프트 속성 블록

Claude Code는 클라이언트 버전과 대화에서 파생된 지문을 포함하는 짧은 속성 블록을 시스템 프롬프트 앞에 추가합니다. api.anthropic.com 엔드포인트는 변경되지 않은 상태로 첫 번째 시스템 블록으로 도착할 때 처리 전에 블록을 제거하므로 자사 프롬프트 캐싱에 영향을 주지 않습니다. 다른 업스트림은 프롬프트의 일부로 수신합니다.

제거는 위치 기반이므로 게이트웨이가 system 배열을 변경되지 않은 상태로 전달할 때만 작동합니다. 다른 시스템 콘텐츠를 잃지 않으면서 블록을 프롬프트에서 제외하려면:

  • 받은 system 배열을 정확히 전달하고 블록을 먼저 유지합니다: 다른 시스템 블록을 앞에 추가하거나, 배열을 재정렬하거나, 단일 문자열로 변환하면 제거가 실패하고 블록이 모델과 프롬프트 캐시 키에 도달합니다.
  • 블록을 자체 배열 항목에 유지합니다: 엔드포인트는 속성 헤더로 시작하는 병합된 블록을 속성 전체로 취급하고 병합된 나머지 시스템 프롬프트를 포함한 모든 것을 삭제합니다.
  • 게이트웨이가 시스템 콘텐츠를 재구성해야 하는 경우, CLAUDE_CODE_ATTRIBUTION_HEADER=0을 설정하여 Claude Code가 블록을 생략하도록 합니다. Anthropic 및 클라우드 제공자의 Claude 엔드포인트는 속성을 위해 블록을 읽으므로, 게이트웨이에서 제거하거나 이동하기보다는 클라이언트에서 생략합니다.

이 변수는 게이트웨이 및 타사 캐싱 호환성을 위해 존재하며, 개인정보 보호 제어로서가 아닙니다: 직접 연결에서 전체 요청은 어느 쪽이든 Anthropic API로 이미 전달됩니다. 이 두 조건이 모두 충족될 때, Claude Code는 변수를 0으로 설정한 경우에도 자동 모드 분류기 요청에서 블록을 유지합니다:

  • 요청이 api.anthropic.com으로 이동하고, ANTHROPIC_BASE_URL이 설정되지 않았거나 해당 호스트를 지정하며 타사 제공자가 선택되지 않았습니다.
  • 활성 자격증명이 Anthropic 프로필 또는 페더레이션 자격증명이 아닙니다.

분류기 요청은 Claude Code의 나머지 시스템 프롬프트를 건너뛰므로, 해당 요청에서 블록은 요청 본문에서 이를 Claude Code 트래픽으로 식별하는 유일한 마커입니다. 조건 중 하나라도 실패하면, LLM 게이트웨이를 통해, 타사 제공자에서, 또는 프로필이나 페더레이션 자격증명이 활성화된 경우, 0을 설정하면 분류기 요청에서도 블록을 제거합니다. v2.1.229 이전에는 이 예외가 존재하지 않았습니다: 0을 설정하면 해당 분류기 요청에서 블록을 제거했고, API가 식별되지 않은 요청을 거부했을 때, 자동 모드는 분류기로 전송한 모든 작업에서 실패했습니다.

Claude Code v2.1.181부터, 요청이 사용자 정의 기본 URL을 통해 라우팅될 때 블록은 대화의 수명 동안 안정적이므로, 전체 요청 본문을 기반으로 하는 게이트웨이 측 프롬프트 캐시는 이를 비활성화하지 않고도 작동하며, 게이트웨이가 전달하는 모든 제공자는 안정적인 프롬프트 접두사를 수신합니다. v2.1.181 이전에는 블록이 요청별 토큰을 포함했으므로 모든 요청에서 시스템 프롬프트의 시작이 변경되었습니다. 해당 버전에서 게이트웨이가 다음 중 하나를 수행하는 경우 CLAUDE_CODE_ATTRIBUTION_HEADER=0을 설정합니다:

  • 요청 본문을 기반으로 하는 프롬프트 캐시를 구현합니다.
  • Amazon Bedrock, Microsoft Foundry 또는 Google Cloud의 Agent Platform과 같은 타사 제공자로 요청을 전달하며, Anthropic Messages 형식 또는 제공자 자체 형식으로, 변경되는 접두사가 해당 제공자에서 프롬프트 캐시 재사용을 감소시킵니다.

기능 통과

Claude Code는 ANTHROPIC_BASE_URL 게이트웨이를 Anthropic 형식 엔드포인트로 취급하고 api.anthropic.com으로 전송하는 베타 헤더 및 요청 본문 필드를 전송합니다. 단, 직접 연결을 위해 예약된 작은 진단 및 기본값 집합은 제외합니다. 이 집합은 릴리스에 따라 다르므로 그 내용에 의존하지 마십시오.

세분화된 도구 스트리밍은 직접 연결 기본값 중 하나입니다. 요청이 사용자 정의 기본 URL을 통해 라우팅될 때마다 기본적으로 꺼져 있으며, 개발자가 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1을 설정할 때 게이트웨이가 이를 수신합니다.

베타 헤더 및 본문 필드 쌍

기능을 추가하는 본문 필드는 베타 헤더와 쌍을 이루며, 쌍은 함께 이동합니다. 헤더를 제거하면서 본문을 통과시키거나, Anthropic 형식 본문을 다른 스키마의 업스트림으로 전달하는 게이트웨이는 400 오류를 생성합니다. 두 절반이 함께 없을 때는 기능이 조용히 꺼집니다.

콘텐츠 검사를 위해 요청 본문을 다시 쓰거나 수정하는 게이트웨이는 제거하는 것과 같은 방식으로 쌍을 손상시키므로, 수정하지 않고 검사합니다. 표는 기능이 쌍에서 벗어나는 경우를 기록합니다.

기능 헤더 및 본문 쌍 손상될 때의 증상 해결 방법
적응형 추론 베타 헤더 없음. Claude Code는 Claude Opus 4.6, Claude Sonnet 4.6, Claude Haiku 5.5, Claude Fable 5 및 이후 모델에 대해 thinking: {"type": "adaptive"}를 전송하고, 게이트웨이 별칭과 같이 인식하지 못하는 모델 이름을 현재 모델로 취급하여 필드를 수신합니다. 업스트림 모델 빌드가 이를 수락하지 않을 때 thinking 필드 또는 adaptive 태그의 이름을 지정하는 400 업스트림을 업그레이드합니다. Opus 4.6 및 Sonnet 4.6에서 개발자는 대신 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1을 설정할 수 있습니다.
컨텍스트 관리 컨텍스트 관리 베타 헤더는 context_management 본문 필드와 쌍을 이룹니다. Extra inputs are not permitted를 포함한 400. 게이트웨이가 Anthropic 형식 요청을 수락하지만 Amazon Bedrock으로 전달할 때 일반적입니다. v2.1.304 이상에서는 Claude Code가 해당 쌍 없이 자체적으로 재시도합니다. 둘 다 전달하거나 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
확장 컨텍스트 및 인터리브된 사고 베타 헤더만, 본문 필드 없음 헤더가 제거될 때 조용히 사용 불가능. 업스트림은 기능 요청을 보지 못합니다. anthropic-beta를 그대로 전달합니다.
베타 도구 필드 도구 관련 베타 헤더는 strict 및 defer_loading과 같은 도구 스키마 필드와 쌍을 이룹니다. 본문이 헤더 없이 통과할 때 인식되지 않는 도구 스키마 필드의 이름을 지정하는 400. defer_loading의 경우 도구 검색 없이 재시도를 참조하십시오. 둘 다 전달하거나 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
노력 및 구조화된 출력 output_config 본문 필드는 노력, 구조화된 출력 형식 및 작업 예산 설정을 전달합니다. 각각은 자체 베타 헤더와 쌍을 이룹니다. Amazon Bedrock 및 Google Cloud의 Agent Platform 업스트림에서 output_config의 이름을 지정하는 400. 종종 Extra inputs are not permitted 필드와 헤더를 함께 전달하거나, 개발자가 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하도록 합니다. 이 변수는 형식 및 작업 예산 설정을 제거하지만 노력은 제거하지 않습니다. 형식만 제거하려면 대신 CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1을 설정할 수 있으며, 이는 v2.1.288 이상이 필요합니다.
대화 중간 시스템 메시지 베타 헤더 없음. Claude Code는 Claude Opus 4.8, 그 이후에 출시된 모델, 인식되지 않는 모델 ID에 대해 일부 리마인더 및 첨부 텍스트를 messages의 role: "system" 항목으로 전송합니다. Unexpected role "system"과 같은 400 Claude Code는 시스템 메시지 없이 재시도합니다. Claude Opus 4.8 이전에 출시된 모델의 별칭에서 시스템 메시지를 중지하려면 배포하는 설정에 modelOverrides 항목을 추가합니다.
턴별로 설정된 노력 Opus 5.5, Sonnet 5.5, Haiku 5.5 및 Fable 5.1에서는 베타 헤더가 role: "system" 항목(시스템 메시지 또는 빈 콘텐츠가 있는 항목)의 output_config.effort와 쌍을 이룹니다. 게이트웨이가 빈 항목에서 필드를 제거할 때 messages.N: system content must contain at least one block을 포함한 400 둘 다 전달하거나, 개발자가 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하여 해당 필드와 빈 항목을 중지하도록 합니다.
프롬프트 캐싱 베타 쌍 없음. Claude Code는 cache_control 마커를 system 블록 및 messages 항목(대화 중간에 추가된 role: "system" 항목 포함)에 첨부합니다. 오류 없음: 대화는 매 턴마다 캐시되지 않은 입력으로 청구되며, usage에서 높은 input_tokens과 거의 또는 전혀 캐시 활동이 없는 것으로 표시됩니다. cache_control을 나타나는 모든 곳에서 그대로 전달하고, 블록 형식 system 또는 메시지 콘텐츠를 일반 문자열로 변환하지 마십시오.
토큰 계산 베타 쌍 없음. count_tokens 엔드포인트를 사용합니다. 오류 없음: Claude Code는 문자 기반 추정으로 돌아가므로 /context는 대략적인 계산을 표시합니다. 정확한 토큰 계산을 위해 엔드포인트를 노출합니다.

ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 변수는 제공자 구성에서만 모델 기능을 선언합니다: CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, 및 CLAUDE_CODE_USE_MANTLE. 이들은 ANTHROPIC_BASE_URL 게이트웨이 뒤에서 효과가 없습니다.

자동 재시도 및 오류 전달

업스트림이 이러한 기능 중 하나를 거부하면, Claude Code는 거부된 부분을 제거하거나 변경하여 요청을 자체적으로 재시도할 수 있습니다:

  • 400이 thinking.type 값 enabled 또는 adaptive가 지원되지 않는다고 알리면, Claude Code는 다른 유형으로 한 번 재시도하고 thinking 필드는 유지합니다. 해당 모델에 대한 이후 요청은 Claude Code가 종료될 때까지 전환된 유형을 유지합니다. v2.1.121 이전에는 Claude Code가 재시도하지 않았으므로 thinking.type.enabled is not supported가 개발자에게 도달했습니다.
  • 업스트림이 messages 내부의 role: "system" 항목을 거부하면, Claude Code는 해당 대화 중간 시스템 메시지 없이 한 번 재시도하고 그 텍스트를 대신 사용자 메시지에 담아 전달합니다. 대화의 이후 요청은 개발자가 /clear를 실행하거나 대화가 압축될 때까지 그 형태를 유지합니다.
  • 업스트림이 대화 중간 시스템 메시지의 cache_control 마커만 거부하면, Claude Code는 시스템 메시지를 유지하고 마커를 옮겨 한 번 재시도합니다. 해당 재시도와 Claude Code가 종료될 때까지의 이후 요청에서 마커는 messages에서 시스템 메시지가 아닌 마지막 항목에 붙습니다.
  • 업스트림이 사고 서명을 거부할 때, 블록이 bound to a different conversation이라는 400을 포함하여, Claude Code는 요청에서 이전 사고 블록을 제거하고, 재시도하며, 이후의 모든 요청에서 이들을 제외합니다. 새로운 응답은 여전히 사고를 포함합니다.
  • 게이트웨이 또는 그 업스트림이 tools의 어드바이저 도구 항목을 인식되지 않는 도구 유형으로 거부할 때, Claude Code는 해당 항목과 그 anthropic-beta 값 없이 요청을 한 번 재시도합니다. 이후 해당 기본 URL에 대한 요청은 Claude Code가 종료될 때까지 어드바이저를 제외하고, /advisor는 그 시간 동안 개발자에게 사용 불가능합니다. Claude Code는 Input tag 뒤에 도구 유형의 이름을 지정하는 400 또는 422 응답으로 이 거부를 인식합니다. 예를 들어 Input tag 'advisor_20260301'입니다. v2.1.280 이전에는 Claude Code가 이 거부를 재시도하지 않았습니다.
  • 업스트림이 output_config.effort를 거부할 때, Claude Code는 노력 없이 요청을 재시도하고 Claude Code가 종료될 때까지 해당 모델에 대한 이후 요청에서 이를 제외합니다. Claude Code는 메시지가 Extra inputs are not permitted와 함께 output_config.effort의 이름을 지정하거나, 모델이 노력 매개변수를 지원하지 않는다고 명시하는 400으로 이 거부를 인식합니다.
  • 업스트림이 context_management 필드 또는 그 anthropic-beta 값을 거부하면, 게이트웨이는 이들이 제외된 요청을 한 번 더 받습니다. 이후 요청에서 게이트웨이가 이들을 다시 받고 업스트림이 다시 거부하면, 같은 재시도가 이어집니다. Claude Code는 메시지로 이 거부를 인식합니다. 예를 들어 context_management: Extra inputs are not permitted를 포함하는 메시지입니다. v2.1.304 이전에는 Claude Code가 이 거부를 재시도하지 않았습니다.
  • 업스트림이 strict와 같이 defer_loading 이외의 베타 도구 필드를 거부하면, 400이 개발자에게 도달합니다. 그 전에 게이트웨이는 도구 검색 필드 없이 요청을 다시 받을 수 있습니다. 이러한 필드의 전송을 중지하려면 개발자가 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하도록 합니다.

bound to a different conversation 거부는 API의 보존된 사고 확인에서 나오며, system, tools, 또는 이전 messages 콘텐츠가 사고를 생성한 요청과 다를 때 실패합니다. 해당 콘텐츠를 다시 쓰는 게이트웨이는 거부 자체를 야기할 수 있습니다. 라이브러리, 프록시, 및 게이트웨이는 변경하지 않고 통과시켜야 할 것을 다룹니다.

이 재시도 로직의 대부분은 업스트림의 오류 표현과 일치하므로 오류 응답 본문을 수정하지 않고 전달합니다. 업스트림 오류를 자체 봉투로 래핑하는 게이트웨이는 상태 코드를 유지하더라도 복구 경로를 손상시킵니다. 단, 봉투의 메시지가 안정적인 capability_rejected: 토큰을 포함하는 경우는 예외입니다. Claude 앱 게이트웨이는 클라우드 제공자의 오류 표현을 위해 해당 토큰으로 대체합니다. 예를 들어 capability_rejected: prompt_too_long입니다.

도구 검색 없이 재시도

v2.1.305 이상에서는 defer_loading 필드와 tool_reference 블록을 포함한 요청이 Claude Code가 원인을 인식하지 못하는 400 또는 422 이후에 이들 없이 다시 도착할 수 있습니다. 재시도가 성공하면 이후 요청에서도 이들이 생략됩니다.

게이트웨이를 변경하지 않아도 개발자의 요청은 계속 작동하며, MCP 도구는 미리 로드됩니다. Claude Code는 나중에 도구 검색을 다시 시도하므로, 게이트웨이는 또 다른 거부된 요청과 그 재시도를 받을 수 있습니다. 모든 요청에서 이 필드를 제외하려면 개발자가 ENABLE_TOOL_SEARCH=false를 설정하도록 합니다. 도구 검색 자체를 위해서는 Claude Code는 게이트웨이가 defer_loading 필드와 tool_reference 블록을 해당 anthropic-beta 값과 함께 전달할 것으로 기대합니다.

사전 릴리스 기능 비활성화

게이트웨이 또는 그 업스트림이 사전 릴리스 anthropic-beta 값이나 이와 쌍을 이루는 본문 필드를 거부하고 두 절반을 모두 전달할 수 없는 경우, 개발자가 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하도록 합니다. 이 변수가 설정되면 Claude Code는 사전 릴리스 기능과 이와 쌍을 이루는 anthropic-beta 값의 전송을 중지하며, 여기에는 다음이 포함됩니다:

  • 컨텍스트 관리 및 해당 context_management 본문 필드
  • strict 및 defer_loading과 같은 베타 도구 스키마 필드. 표준 name, description, input_schema, 및 cache_control 도구 필드는 유지됩니다.
  • 구조화된 출력 output_config.format 필드. Claude Code v2.1.287 이상이 필요합니다.
  • output_config.task_budget 필드
  • MCP 도구 검색. 따라서 조직이 관리형 설정을 통해 이를 켜 두지 않는 한 모든 MCP 도구가 미리 로드됩니다.

이 변수가 모든 anthropic-beta 값을 제거하는 것은 아닙니다. 그대로 유지되는 항목은 다음과 같습니다:

  • 클라우드 제공자도 수락하는 확장 컨텍스트, 인터리브된 사고, 및 노력에 대한 anthropic-beta 값
  • 최상위 output_config.effort 필드. 이를 거부하는 업스트림은 자동 재시도 및 오류 전달에서 다룹니다.
  • 베타 헤더가 없는 적응형 추론 thinking 필드
  • 대화 중간 시스템 메시지를 전달하는 role: "system" 항목
  • 구독 인증이 요구하는 OAuth anthropic-beta 값
  • 개발자가 ANTHROPIC_BETAS 또는 CLAUDE_CODE_EXTRA_BODY를 통해 직접 추가하는 헤더 값 및 본문 필드

Claude Code를 포함하는 호스트 플랫폼이 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정할 때, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS는 Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, 또는 Claude 앱 게이트웨이의 자동 모드 세션이 서버에 분류기 검토를 요청하는 것을 중지하지 않습니다. 해당 검토는 anthropic-beta 값과 safeguards 요청 필드를 추가합니다. 거기서 이를 중지하려면 CLAUDE_CODE_AUTO_MODE_SERVER=0을 설정합니다.

Claude Code v2.1.227 이상에서 조직은 관리 설정을 통해 이 변수 아래에서 MCP 도구 검색을 유지할 수 있습니다. Claude Code가 해당 재정의를 적용하여 전송하는 것은 연결 방식에 따라 다릅니다:

  • HIPAA 구성이 없는 직접 연결 또는 ANTHROPIC_BASE_URL로 설정된 게이트웨이를 통해 연결하는 경우, Claude Code는 도구 검색 베타 헤더, defer_loading 도구 필드, 및 tool_reference 블록을 계속 전송합니다.
  • 클라우드 제공자 또는 Claude 앱 게이트웨이를 통해 로그인한 경우, 재정의는 효과가 없습니다.
  • HIPAA 구성을 받는 세션에서는 재정의가 효과가 없으며 도구 검색은 꺼진 상태로 유지됩니다.

Claude Code가 전송하는 기능 집합은 릴리스에 따라 증가합니다. 현재 베타 헤더 문자열은 베타 헤더 참조를 참조하십시오. 관찰된 목록에 고정하기보다는 새로운 Claude Code 릴리스에 대해 게이트웨이를 테스트합니다.

모델 검색

ANTHROPIC_BASE_URL이 Anthropic Messages 형식을 노출하는 게이트웨이를 가리킬 때, Claude Code는 시작 시 게이트웨이의 /v1/models 엔드포인트를 쿼리하고 반환된 모델을 /model 선택기에 추가할 수 있습니다. 사용자 또는 관리자가 modelPicker 라인업에서 replaceBuiltInOptions을 설정하면, Claude Code는 검색된 모델을 선택기에서 숨깁니다.

개발자는 자신의 환경 또는 관리되는 설정을 통해 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1을 설정하여 이를 활성화합니다. 검색은 기본적으로 꺼져 있으므로 공유 API 키로 지원되는 게이트웨이가 키가 액세스할 수 있는 모든 모델을 모든 사용자에게 표시하지 않습니다.

검색이 실행되는 경우

검색은 Anthropic Messages 형식에만 적용됩니다. 다음의 경우 실행되지 않습니다:

  • ANTHROPIC_BASE_URL도 설정되어 있더라도 CLAUDE_CODE_USE_* 제공자 변수가 설정된 경우
  • ANTHROPIC_BASE_URL이 설정되지 않았거나 api.anthropic.com을 가리키는 경우

비필수 트래픽이 꺼져 있을 때 검색이 계속 실행됩니다. 요청이 게이트웨이로만 이동하기 때문입니다. v2.1.257 이전에는 비필수 트래픽이 꺼져 있는 동안 검색이 실행되지 않았습니다.

요청 및 응답

요청은 3초 타임아웃을 포함한 GET /v1/models?limit=1000이며, 모든 리디렉션은 자격 증명이 리디렉션 대상으로 유출되지 않도록 실패로 취급됩니다. 느리게 응답하거나 /v1/models를 리디렉션하는 게이트웨이 (예: http에서 https로)는 검색을 조용히 실패합니다. 구성된 기본 URL에서 직접 엔드포인트를 제공합니다.

느린 게이트웨이에 더 오래 걸리도록 하려면 CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS를 설정합니다. 이 변수는 Claude Code v2.1.269 이상이 필요합니다.

Claude Code는 아래의 두 자격 증명 헤더로 검색 요청을 전송하고 값이 해결되지 않는 헤더는 생략합니다. 두 헤더를 모두 전송하려면 Claude Code v2.1.248 이상이 필요합니다. 이전 버전은 ANTHROPIC_AUTH_TOKEN이 설정되었을 때만 Authorization을 전송하고, 그렇지 않으면 x-api-key만 전송합니다.

  • Authorization: ANTHROPIC_AUTH_TOKEN을 베어러 토큰으로, 그렇지 않으면 apiKeyHelper 값을 베어러 토큰으로.
  • x-api-key: Claude Code가 해결한 API 키 (예: ANTHROPIC_API_KEY). 도우미 값이 유일한 자격 증명일 때, 이 헤더도 이를 전달하므로 값이 두 헤더 모두에 도착합니다.

Claude Code는 또한 ANTHROPIC_CUSTOM_HEADERS의 모든 헤더를 전송합니다. 사용자 정의 헤더에 비어 있지 않은 값이 있으면, Claude Code는 같은 이름의 기본 제공 헤더 대신 이를 전송하며, 이름은 대소문자를 구분하지 않게 일치합니다.

어느 자격 증명 헤더의 값도 해결되지 않으면, Claude Code는 검색을 건너뛰고 claude --debug 세션의 디버그 로그에 [gatewayDiscovery] skipped 줄을 씁니다. ANTHROPIC_CUSTOM_HEADERS를 통해서만 자격 증명을 제공하면, Claude Code는 여전히 검색을 건너뜁니다.

Claude Code는 응답의 data 배열의 각 항목에서 id, 선택 사항인 display_name, 그리고 선택 사항인 description을 읽습니다:

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code는 id에 claude 또는 anthropic이 문자열의 어디든 포함되어 있으면 항목을 유지하며, 대소문자를 구분하지 않게 일치하고 나머지는 무시합니다. vertex_ai/claude-sonnet-4-6 또는 bedrock/anthropic.claude-sonnet-4-5와 같은 제공자 접두사가 있는 ID는 필터를 통과합니다. 두 부분 문자열을 포함하지 않는 ID는 통과하지 않습니다. v2.1.223 이전에는 Claude Code가 id가 claude 또는 anthropic으로 시작할 때만 항목을 유지했으며, 이는 제공자 접두사가 있는 ID를 숨겼습니다.

선택기 항목 및 캐싱

선택기는 개발자가 Claude Code에서 /model을 실행할 때 열리는 대화형 모델 목록입니다. 각 검색된 항목은 게이트웨이가 id와 다른 항목을 전송할 때 display_name을 이름으로 사용합니다. 그렇지 않으면 항목은 Claude Code가 id를 인식할 때 모델의 이름을 표시하고, 인식하지 못할 때 id를 표시합니다. 예를 들어, id가 my-gateway-claude-sonnet-4-6이고 display_name이 없는 항목은 Sonnet 4.6으로 나타납니다.

검색은 availableModels 관리되는 설정이 허용하는 모델만 추가합니다.

각 항목은 또한 모델의 description을 한 줄로 축소하여 표시합니다. description이 없는 항목은 대신 "게이트웨이에서"를 읽습니다. v2.1.257 이전에는 모든 검색된 항목이 "게이트웨이에서"를 읽었습니다.

검색된 ID는 선택기에 이미 있는 행과 일치할 때 자신의 행을 얻지 않습니다:

  • 같은 ID: 검색된 ID가 기존 행의 ID와 정확히 일치하거나, 두 ID가 같은 Fable 버전의 철자입니다.
  • 기본 제공 별칭과 같은 모델: 검색된 명시적 ID가 기본 제공 별칭이 현재 해결되는 모델의 이름을 지을 때, 선택기는 별칭 행만 표시합니다. 예를 들어, sonnet이 claude-sonnet-5-5로 해결되는 동안, 검색된 claude-sonnet-5-5는 sonnet 행으로 축소되고, 검색된 claude-sonnet-5는 여전히 자신의 행을 얻습니다.

결과는 ~/.claude/cache/gateway-models.json 또는 Windows의 %USERPROFILE%\.claude\cache\gateway-models.json으로 캐시되고 각 시작 시 새로 고쳐집니다. CLAUDE_CONFIG_DIR을 설정하면, 캐시는 대신 해당 디렉토리 아래에 있습니다. 요청이 실패하거나 게이트웨이가 /v1/models를 구현하지 않으면, 선택기는 이전 시작의 캐시된 목록 또는 기본 제공 모델 목록으로 돌아갑니다. 게이트웨이가 검색 필터와 일치하지 않는 별칭 아래에서 Claude 모델을 제공하면, 개발자는 모델 구성 변수를 사용하여 해당 별칭을 수동으로 추가할 수 있습니다.

관련 리소스

게이트웨이 문서 집합의 나머지 부분 및 기본 API 참조: