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

• API 형식 및 각 형식에 대해 제공할 엔드포인트
• 연결 방법별 클라이언트 동작: 모델 ID, anthropic-beta 값, 요청 필드 및 기본값이 형식과 Claude 앱 게이트웨이 로그인 간에 어떻게 다른지
• 요청 헤더: 업스트림에 도달해야 하는 것과 게이트웨이가 사용할 수 있는 것
• 응답 헤더: 정체 감지, 재시도 및 사용량 제한 표시가 작동하도록 반환할 내용
• 시스템 프롬프트 속성 블록 및 프롬프트 캐싱과의 상호 작용
• 기능 통과: 헤더 또는 본문 필드가 제거될 때 중단되는 것
• 모델 검색

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

​

API 형식

​

Foundry 및 AWS의 Claude Platform

​

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

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

​

스트리밍

​

업스트림과의 형식 불일치

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

​

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

• 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 값과 모델 기능 가정만 전송합니다.

​

연결 방법별 요청 및 기본값

​

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

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

​

요청 헤더

​

게이트웨이 힌트 헤더

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

​

개방형 목록으로 전달

​

응답 헤더

​

시스템 프롬프트 속성 블록

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

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

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

​

기능 통과

​

자동 재시도 및 오류 전달

• 업스트림이 thinking 필드, 중간 대화 시스템 메시지, 또는 해당 메시지의 cache_control 마커를 거부할 때, Claude Code는 요청을 재시도하고 거부된 기능을 나머지 대화에 대해 비활성화합니다.
• 업스트림이 사고 서명을 거부할 때, 블록이 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가 이 거부를 재시도하지 않았습니다.
• Claude Code는 컨텍스트 관리 또는 도구 스키마 필드 거부를 재시도하지 않으므로, 해당 400 오류는 개발자에게 도달합니다.

​

사전 릴리스 기능 비활성화

• 직접 연결 또는 ANTHROPIC_BASE_URL로 설정된 게이트웨이를 통해, Claude Code는 도구 검색 베타 헤더, defer_loading 도구 필드, 및 tool_reference 블록을 계속 전송하고 나머지는 제거합니다.
• 클라우드 제공자 또는 Claude 앱 게이트웨이를 통해 로그인한 경우, 재정의는 효과가 없습니다.

​

모델 검색

​

검색이 실행되는 경우

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

​

요청 및 응답

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

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

​

선택기 항목 및 캐싱

• 같은 ID: 검색된 ID가 기존 행의 ID와 정확히 일치하거나, 두 ID가 같은 Fable 버전의 철자입니다.
• 기본 제공 별칭과 같은 모델: 검색된 명시적 ID가 기본 제공 별칭이 현재 해결되는 모델의 이름을 지을 때, 선택기는 별칭 행만 표시합니다. 예를 들어, sonnet이 claude-sonnet-5로 해결되는 동안, 검색된 claude-sonnet-5는 sonnet 행으로 축소되고, 검색된 claude-sonnet-4-6은 여전히 자신의 행을 얻습니다. v2.1.197 이전에는 Claude Code가 이러한 ID를 기본 제공 행으로 접지 않았으므로 claude-sonnet-5도 자신의 “게이트웨이에서” 행을 얻었습니다.

​

관련 리소스

• 게이트웨이 개요: 게이트웨이가 무엇이고 Claude 앱 게이트웨이와 다른 제품 중에서 선택하는 방법
• 다른 LLM 게이트웨이: 조직이 실행하는 게이트웨이를 배포하는 방법 및 claude.ai 구독과 어떻게 상호작용하는지
• 조직을 위해 LLM 게이트웨이 배포: 이 가이드를 사용하는 관리자 체크리스트
• Claude Code를 LLM 게이트웨이에 연결: 개발자별 구성 및 문제 해결 표
• 베타 헤더 참조: 현재 anthropic-beta 값 집합
• Messages API: Anthropic 형식 게이트웨이가 구현하는 API 형식