SpyBara
Go Premium

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

This page contains 69 additions and 31 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59

Claude Code gateway 相容性指南

保持 LLM gateway 與 Claude Code 相容：它呼叫的端點、必須轉發的標頭和請求體欄位，以及移除它們時會破壞什麼。

本頁面記錄了 Claude Code 發送給 gateway 的請求，包括它呼叫的端點、gateway 必須轉發的標頭和請求體欄位，以及當 gateway 不這樣做時哪些功能會停止運作。本文件是為配置 gateway 產品以與 Claude Code 搭配運作的操作人員編寫的。

Claude apps gateway（Anthropic 的自託管 gateway）在 GET /protocol 提供自己的端點參考，涵蓋該 gateway 的登入、推論、受管設定、模型發現和遙測端點。這是一份與本指南分開的文件。

本頁面涵蓋：

本頁面使用兩個術語來描述您的 gateway 對每個標頭和請求體欄位的處理方式：

  • 轉發不變：逐位元組傳遞給上游
  • 使用：gateway 可能會讀取它以進行路由、歸屬或追蹤，不需要轉發它

任何未標記為轉發不變的內容都可以由您使用或忽略。

API 格式

Gateway 必須向 Claude Code 用戶端公開以下至少一種 API 格式。用戶端選擇一種格式，並使用下表「選擇者」欄中的變數將 Claude Code 指向您的 gateway。

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 路由到它們，但 gateway 在任一前面實現上述 Anthropic Messages 列。在 AWS 上的 Claude Platform 前面的 gateway 還必須轉發 anthropic-workspace-id 標頭，該平台在每個請求上都需要。

可選端點和啟動流量

令牌計數端點是唯一可選的：當它們不存在時，Claude Code 會改為通過推理端點回退到計數上下文使用情況。推理請求發佈到 /v1/messages?beta=true，因此請匹配路徑，而不是完整 URL。Google Cloud 的 Agent Platform 方法後綴附加到發佈者模型路徑，如 /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict。

Gateway 也會看到最佳努力的啟動流量，它可以拒絕而不會破壞任何東西。Anthropic Messages 格式的 gateway 會收到 HEAD /api/hello 連接預熱探測，當配置了 HTTP 代理或用戶端憑證時，Claude Code 會跳過此探測。Amazon Bedrock 格式的 gateway 會收到 GET /inference-profiles?type=SYSTEM_DEFINED 請求，以及當配置的模型是推理設定檔時，GET /inference-profiles/{profile} 查詢。

快速模式可用性檢查永遠不會出現在 gateway 日誌中：它直接呼叫 api.anthropic.com 而不是遵循 ANTHROPIC_BASE_URL，因此在阻止直接出站到 api.anthropic.com 的網路上，快速模式可能會報告連線錯誤，而通過 gateway 的推理仍然可以正常工作。WebFetch 網域安全檢查也直接呼叫 api.anthropic.com。在代理和 LLM gateway 後面使用快速模式涵蓋了恢復它的變數。

串流

串流推理回應。Claude Code 在接收時讀取串流，因此如果您的 gateway 在轉發完整回應之前進行緩衝，Claude Code 會停滯。

當用戶端使用 Amazon Bedrock 格式時，轉發 InvokeModelWithResponseStream 回應體及其 Content-Type: application/vnd.amazon.eventstream 標頭不做修改，並且不要將串流轉換為伺服器發送事件。請參閱在 gateway 或代理後面的串流錯誤。

也要轉發保活 ping。在通過 ANTHROPIC_BASE_URL 或 ANTHROPIC_AWS_BASE_URL 的連線上，Claude Code 計算您的 gateway 轉發的每一位元組，包括 SSE ping 事件和註解行，並在預設情況下中止 300 秒無聲的串流。上游的 ping 是長思考暫停期間唯一的流量，因此如果您的 gateway 移除或緩衝它們，Claude Code 會在這些暫停期間中止串流；自動重試涵蓋了根據回應進度有多遠而中止的串流報告的內容。完全不發送 ping 的上游（例如 Amazon Bedrock 的二進位事件串流）在這些暫停期間沒有任何東西可轉發。從這樣的上游進行轉換時，在無聲間隙期間發出您自己的 ping 事件。通過 ANTHROPIC_BEDROCK_BASE_URL、ANTHROPIC_VERTEX_BASE_URL 或 ANTHROPIC_FOUNDRY_BASE_URL 到達的 gateway 不受此位元組級監視程式的包裝，即使它們轉發 Anthropic Messages 格式；在那裡，5 分鐘空閒逾時會改為中止無聲串流，在 ANTHROPIC_BEDROCK_BASE_URL 連線上，您可以使用 CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK 新增位元組監視程式。

與上游的格式不匹配

用戶端使用的格式決定了您的 gateway 接收的內容。常見的失敗模式是用戶端發送給您的 gateway 的格式與其後面的上游提供者接受的格式不匹配。

  • 當用戶端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式時，Claude Code 只發送那些提供者接受的完整功能集的子集
  • 當用戶端使用 Anthropic Messages 格式時，Claude Code 發送完整集合，即使您的 gateway 轉發到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

橋接該差異是您的 gateway 的工作。功能傳遞描述了當它不這樣做時會發生什麼。

請求標頭

Claude Code 在 API 請求上包含這些標頭。標頭名稱在線路上不區分大小寫。轉發 anthropic-version 和 anthropic-beta 不變，加上當上游是 AWS 上的 Claude Platform 時的 anthropic-workspace-id；其餘的 gateway 可以使用以進行路由、歸屬和追蹤，不需要轉發。

標頭 描述
Authorization、x-api-key 開發人員的 gateway 認證，根據他們設定的認證變數在一個或兩個標頭中
anthropic-version API 版本，目前為 2023-06-01。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式請求也攜帶 anthropic_version 請求體欄位，其值是提供者方言字串，而不是此標頭的值
anthropic-beta 請求的逗號分隔功能值。逐字轉發標頭；不要將個別值列入允許清單，因為該集合隨 Claude Code 版本而變化。當開發人員使用 claude.ai 登入進行驗證時（當設定 ANTHROPIC_BASE_URL 而沒有 gateway 認證變數時可能），此標頭也會攜帶上游需要的 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 在版本中獲得功能，它們作為新的 anthropic-beta 值、新的請求體欄位以及偶爾新的 anthropic-* 或 x-claude-code-* 標頭到達。

轉發到 Anthropic 格式上游時，傳遞 anthropic-* 請求標頭和請求體欄位不變，而不是將您今天看到的列入允許清單。固定到觀察清單的 gateway 會移除下一個功能的標頭或欄位，並在引入它的版本上破壞它。

例外是非 Anthropic 上游（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform），其中橋接架構差異是 gateway 的工作；請參閱功能傳遞。

系統提示歸屬區塊

Claude Code 在系統提示前面加上一個簡短的歸屬區塊，其中包含用戶端版本和從對話衍生的指紋。api.anthropic.com 端點在處理前移除該區塊，因此它不會影響第一方提示快取；任何其他上游都會將其作為提示的一部分接收。

該移除是位置性的，因此只有在 gateway 轉發 system 陣列保持不變時才有效。若要在不遺失其他系統內容的情況下將區塊排除在提示之外：

  • 完全按照接收的方式轉發 system 陣列，將區塊保持在最前面：在前面加上另一個系統區塊、重新排序陣列或將其轉換為單一字串會破壞移除，區塊隨後會到達模型和提示快取鍵。
  • 將區塊保持在自己的陣列項目中：端點將以歸屬標頭開頭的合併區塊視為完整的歸屬並刪除合併到其中的所有內容，包括系統提示的其餘部分。
  • 如果您的 gateway 必須重新塑造系統內容，請設定 CLAUDE_CODE_ATTRIBUTION_HEADER=0 以便 Claude Code 省略該區塊。Anthropic 和雲提供者的 Claude 端點讀取該區塊以進行歸屬，因此要省略它，請在用戶端而不是在 gateway 中移除或移動它。

該變數存在是為了 gateway 和第三方快取相容性，而不是作為隱私控制：在直接連線上，完整請求無論如何都已經進入 Anthropic API。當以下兩項都成立時，Claude Code 會在 auto mode 分類器請求上保留該區塊，即使您將變數設定為 0：

  • 請求進入 api.anthropic.com，ANTHROPIC_BASE_URL 未設定或命名該主機，且未選擇第三方提供者。
  • 作用中的認證不是 Anthropic 設定檔或聯盟認證。

分類器請求會跳過 Claude Code 系統提示的其餘部分，因此在這些請求上，該區塊是請求體中唯一識別它們為 Claude Code 流量的標記。當任一條件失敗時，通過 LLM gateway、在第三方提供者上，或使用作用中的設定檔或聯盟認證，設定 0 也會從分類器請求中移除該區塊。在 v2.1.229 之前，此例外不存在：設定 0 會從這些分類器請求中移除該區塊，當 API 拒絕未識別的請求時，auto mode 在它發送給分類器的每個動作上都會失敗。

從 Claude Code v2.1.181 開始，當請求通過自訂基礎 URL 路由時，該區塊在對話的生命週期內是穩定的，因此以完整請求體為鍵的 gateway 端提示快取可以在不禁用它的情況下工作，且您的 gateway 轉發到的任何提供者都會接收穩定的提示前綴。在 v2.1.181 之前，該區塊包含每個請求的令牌，在請求的開始處改變了系統提示。在這些版本上，當您的 gateway 執行以下任一操作時，請設定 CLAUDE_CODE_ATTRIBUTION_HEADER=0：

  • 實現以請求體為鍵的提示快取。
  • 將請求轉發到第三方提供者，例如 Amazon Bedrock、Microsoft Foundry 或 Google Cloud 的 Agent Platform，採用 Anthropic Messages 格式或提供者自己的格式，其中變化的前綴會減少該提供者上的提示快取重複使用。

功能傳遞

Claude Code 將 ANTHROPIC_BASE_URL gateway 視為 Anthropic 格式端點，並向其發送它發送給 api.anthropic.com 的測試版標頭和請求體欄位，除了為直接連接保留的一小組診斷和預設值，例如下面涵蓋的細粒度工具串流預設。該集合因版本而異，因此不要依賴其內容。

添加請求體欄位的功能將它們與測試版標頭配對，該對一起傳遞。移除標頭同時傳遞請求體的 gateway，或將 Anthropic 格式請求體轉發到具有不同架構的上游，會產生硬 400 錯誤；只有當兩個部分一起不存在時，功能才會安靜地關閉。重寫或編輯請求體以進行內容檢查的 gateway 會以與移除相同的方式破壞配對，因此請在不修改的情況下檢查。該表注意了功能偏離配對的位置。

細粒度工具串流是直接連接預設值之一：每當請求通過自訂基礎 URL 路由時，它預設為關閉，當開發人員設定 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1 時，gateway 會接收它。

功能 標頭和請求體對 破壞時的症狀 補救
自適應推理 無測試版標頭。Claude Code 為 Claude 4.6 及更新版本發送 thinking: {"type": "adaptive"}，並將它不識別的模型名稱（如 gateway 別名）視為接收該欄位的目前模型 當上游模型組建不接受它時，命名 thinking 欄位或 adaptive 標籤的 400 升級上游。在 Opus 4.6 和 Sonnet 4.6 上，開發人員可以改為設定 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1
上下文管理 上下文管理測試版標頭與 context_management 請求體欄位配對 400 搭配 Extra inputs are not permitted。常見於 gateway 接受 Anthropic 格式請求但將其轉發到 Amazon Bedrock 時 轉發兩者，或 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
擴展上下文和交錯思考 僅測試版標頭，無請求體欄位 當標頭被移除時無聲地不可用；上游永遠不會看到功能請求 逐字轉發 anthropic-beta
測試版工具欄位 工具相關的測試版標頭與工具架構欄位（如 strict 和 defer_loading）配對 當請求體在沒有其標頭的情況下通過時，命名無法識別的工具架構欄位的 400 轉發兩者，或 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
努力和結構化輸出 output_config 請求體欄位攜帶努力、結構化輸出格式和任務預算設定；每個都與其自己的測試版標頭配對 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 output_config 的 400，通常是 Extra inputs are not permitted 一起轉發欄位及其標頭
提示詞快取 無測試版配對。Claude Code 將 cache_control 標記附加到 system 區塊和 messages 項目，包括在對話中途附加的 role: "system" 項目 無錯誤：對話在每個回合上都計費為未快取的輸入，在 usage 中可見為高 input_tokens 且很少或沒有快取活動 無論在何處出現，都逐字轉發 cache_control，並且不要將區塊形式的 system 或訊息內容轉換為純字串
令牌計數 無測試版配對；使用 count_tokens 端點 Claude Code 回退到通過訊息端點計數上下文使用情況 公開端點，以便令牌計數不會消耗推理請求

ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 變數僅在提供者配置中聲明模型功能：CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY 和 CLAUDE_CODE_USE_MANTLE。它們在 ANTHROPIC_BASE_URL gateway 後面沒有效果。

自動重試和錯誤轉發

當上游拒絕 thinking 欄位、思考簽名、中途對話系統訊息或這些訊息之一上的 cache_control 標記時，Claude Code 會重試請求並為對話的其餘部分禁用被拒絕的功能。Claude Code 不會重試上下文管理或工具架構欄位拒絕；這些 400 錯誤會到達開發人員。

重試邏輯與上游的錯誤措辭相匹配，因此不修改地轉發錯誤回應體。在自己的信封中包裝上游錯誤的 gateway 會破壞恢復路徑，即使它保留了狀態碼，除非信封的訊息攜帶穩定的 capability_rejected: 令牌。Claude 應用程式 gateway 為雲端提供者的錯誤措辭替換這些令牌，例如 capability_rejected: prompt_too_long。

禁用預發佈功能

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 停止 Claude Code 在每個提供者上發送預發佈功能及其請求體欄位，包括上下文管理和測試版工具欄位。該變數不影響自適應推理，後者由模型而不是測試版選擇。它永遠不會抑制訂閱驗證所需的 OAuth 功能。

在 Claude Code v2.1.227 或更新版本上，您的組織可以通過受管設定在此變數下保持 MCP 工具搜尋開啟。Claude Code 在該覆蓋就位時發送的內容取決於您如何連接：

  • 在直接連接上，或通過設定了 ANTHROPIC_BASE_URL 的 gateway，Claude Code 繼續發送工具搜尋測試版標頭、defer_loading 工具欄位和 tool_reference 區塊，並移除其餘部分
  • 在雲端提供者上，或通過 Claude 應用程式 gateway 登入，覆蓋沒有效果

Claude Code 發送的功能集在版本中增長。有關目前的測試版標頭字串，請參閱測試版標頭參考；針對新的 Claude Code 版本測試您的 gateway，而不是固定到觀察清單。

模型發現

當 ANTHROPIC_BASE_URL 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 可以在啟動時查詢 gateway 的 /v1/models 端點，並將返回的模型添加到 /model 選擇器。如果您或您的管理員在 modelPicker 陣容中設定 replaceBuiltInOptions，Claude Code 會從選擇器中隱藏發現的模型。

開發人員通過在自己的環境中或通過受管設定設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 來啟用它。預設情況下發現是關閉的，以便由共享 API 金鑰支持的 gateway 不會向每個使用者公開金鑰可以存取的每個模型。

發現何時運行

發現僅適用於 Anthropic Messages 格式。當以下情況時不運行：

  • 設定了任何 CLAUDE_CODE_USE_* 提供者變數，即使也設定了 ANTHROPIC_BASE_URL
  • ANTHROPIC_BASE_URL 未設定或指向 api.anthropic.com

當非必要流量被關閉時，發現仍會運行，因為請求只會進入您的 gateway。在 v2.1.257 之前，當非必要流量被關閉時，發現不會運行。

請求和回應

請求是 GET /v1/models?limit=1000，超時時間為 3 秒，任何重定向都被視為失敗，因此認證不會洩露給重定向目標。回應緩慢或重定向 /v1/models 的 gateway，即使是 http 到 https，也會無聲地失敗發現；在配置的基礎 URL 處直接提供端點。

Claude Code 使用以下兩個認證標頭發送發現請求，並省略其值無法解析的標頭。發送兩個標頭需要 Claude Code v2.1.248 或更新版本。較早的版本在設定 ANTHROPIC_AUTH_TOKEN 時僅發送 Authorization，否則僅發送 x-api-key。

  • Authorization：ANTHROPIC_AUTH_TOKEN 作為持有人令牌，否則 apiKeyHelper 值作為持有人令牌。在這種情況下，Claude Code 會等待幫助程式返回後再發送請求。
  • 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 時保留條目，不區分大小寫，並忽略其餘的。提供者前綴的 ID（例如 vertex_ai/claude-sonnet-4-6 或 bedrock/anthropic.claude-sonnet-4-5）通過篩選器；不包含任何一個子字符串的 ID 則不通過。在 v2.1.223 之前，Claude Code 僅在其 id 以 claude 或 anthropic 開頭時保留條目，這隱藏了提供者前綴的 ID。

選擇器條目和快取

選擇器是當開發人員在 Claude Code 中運行 /model 時打開的互動式模型清單。每個發現的條目在 gateway 發送與 id 不同的條目時使用 display_name 作為其名稱。否則，當 Claude Code 識別 id 時，條目會顯示模型的名稱，當它不識別時顯示 id。例如，具有 id my-gateway-claude-sonnet-4-6 且沒有 display_name 的條目顯示為 Sonnet 4.6。

發現僅添加 availableModels 受管設定 允許的模型。

每個條目也會顯示模型的 description，折疊為一行。沒有 description 的條目改為讀取「來自 gateway」。在 v2.1.257 之前，每個發現的條目都讀取「來自 gateway」。

當發現的 ID 與選擇器中已有的列匹配時，它不會獲得自己的列：

  • 相同 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 也會獲得自己的「來自 gateway」列。

結果被快取到 ~/.claude/cache/gateway-models.json，或在 Windows 上 %USERPROFILE%\.claude\cache\gateway-models.json，並在每次啟動時刷新。如果您設定 CLAUDE_CONFIG_DIR，快取會改為位於該目錄下。如果請求失敗或 gateway 未實現 /v1/models，選擇器會回退到上次啟動的快取清單或內建模型清單。如果您的 gateway 在不匹配發現篩選器的別名下提供 Claude 模型，開發人員可以使用模型配置變數手動添加這些別名。

有關 gateway 文件集的其餘部分和基礎 API 參考：