Gateway 协议参考 - Claude Code Docs

本页面记录了 Claude Code 发送到 gateway 的请求，包括它调用的端点、gateway 必须转发的请求头和请求体字段，以及当 gateway 不转发这些内容时哪些功能会停止工作。本页面是为配置 gateway 产品以与 Claude Code 配合工作的运营人员编写的。

要为您的组织推出现有或第三方 gateway，请参阅推出 LLM gateway
如果您是使用给定凭证向 gateway 验证 Claude Code 的个人开发者，请参阅将 Claude Code 连接到 LLM gateway

本页面涵盖：

API 格式和每种格式要提供的端点
请求头：哪些必须到达上游，哪些您的 gateway 可以使用
系统提示归属块及其与提示缓存的交互方式
功能传递：当请求头或请求体字段被删除时会破坏什么
模型发现

本页面对您的 gateway 处理每个请求头和请求体字段的方式使用两个术语：

转发不变：将其逐字节传递到上游
使用：gateway 可能会读取它用于路由、归属或跟踪，不需要转发它

任何未标记为转发不变的内容都可以由您使用或忽略。

API 格式

gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式由客户端的配置决定：下表”选择者”列中的变量指向您的 gateway 使用该格式。

格式	选择者	端点	转发不变
Anthropic Messages	`ANTHROPIC_BASE_URL`	`/v1/messages`、`/v1/messages/count_tokens`（可选）	`anthropic-beta` 和 `anthropic-version` 请求头
Bedrock InvokeModel	`ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1`	`/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream`	`anthropic_beta` 和 `anthropic_version` 请求体字段
Vertex 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 路由到它们，但 fronting 任一方的 gateway 实现上面的 Anthropic Messages 行。fronting AWS 上的 Claude Platform 的 gateway 还必须转发 anthropic-workspace-id 请求头，该平台在每个请求上都需要。

可选端点和启动流量

令牌计数端点是唯一可选的：当它们不存在时，Claude Code 在本地估计上下文使用情况。推理请求发送到 /v1/messages?beta=true，因此请匹配路径，而不是完整 URL。Vertex 方法后缀附加到发布者模型路径，如 /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict。 gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西：一个 HEAD / 连接探针，以及在 Bedrock 格式 gateway 上的 GET /inference-profiles?type=SYSTEM_DEFINED 请求。

流式传输

推理响应必须流式传输。Claude Code 在服务器发送事件到达时使用它们，因此缓冲完整响应然后中继它们的 gateway 会使客户端停滞。

与上游的格式不匹配

客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。

当客户端使用 Bedrock 或 Vertex 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集
当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Bedrock 或 Vertex 上游

弥合这种差异是您的 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`。Bedrock 和 Vertex 格式请求也携带 `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 上游，如 Bedrock 或 Vertex，其中弥合架构差异是 gateway 的工作；请参阅功能传递。

系统提示归属块

Claude Code 在系统提示前面加上一个短的归属块，其中包含客户端版本和从对话派生的指纹。api.anthropic.com 端点在处理前删除该块，因此它不会影响第一方提示缓存；任何其他上游都会将其作为提示的一部分接收。Anthropic 和云提供商的 Claude 端点读取它以进行归属，因此要省略它，请设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 而不是在 gateway 中删除它。从 Claude Code v2.1.181 开始，当请求通过自定义基础 URL 路由时，该块在对话的生命周期内是稳定的，因此以完整请求体为键的 gateway 端提示缓存可以在不禁用它的情况下工作。在 v2.1.181 之前，该块包含每个请求的令牌；在这些版本上，如果您的 gateway 实现了这样的缓存，请设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0。

功能传递

Claude Code 将 ANTHROPIC_BASE_URL gateway 视为 Anthropic 格式端点，并向其发送它发送到 api.anthropic.com 的 beta 请求头和请求体字段，除了为直接连接保留的一小组诊断和默认值。添加请求体字段的功能将它们与 beta 请求头配对，该对一起传递。删除请求头同时传递请求体的 gateway，或将 Anthropic 格式请求体转发到具有不同架构的上游，会产生硬 400 错误；只有当两个部分一起缺失时，功能才会安静地关闭。重写或编辑请求体以进行内容检查的 gateway 会以与删除相同的方式破坏配对，因此在不修改的情况下检查。该表注明了功能偏离配对的位置。细粒度工具流式传输是直接连接默认值之一：每当请求通过自定义基础 URL 路由时，它默认关闭，当开发者设置 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1 时，gateway 会接收它。

功能	请求头和请求体对	破坏时的症状	补救
自适应推理	无 beta 请求头。Claude Code 为 Claude 4.6 及更高版本发送 `thinking: {"type": "adaptive"}`，并将它不识别的模型名称（如 gateway 别名）视为接收该字段的当前模型	当上游模型构建不接受它时，命名 `thinking` 字段或 `adaptive` 标签的 `400`	升级上游。在 Opus 4.6 和 Sonnet 4.6 上，开发者可以改为设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`
上下文管理	上下文管理 beta 请求头与 `context_management` 请求体字段配对	`400` 带有 `Extra inputs are not permitted`。常见于 gateway 接受 Anthropic 格式请求但将其转发到 Bedrock 时	转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
扩展上下文和交错思考	仅 Beta 请求头，无请求体字段	当请求头被删除时无声地不可用；上游永远不会看到功能请求	逐字转发 `anthropic-beta`
Beta 工具字段	工具相关的 beta 请求头与工具架构字段（如 `strict` 和 `defer_loading`）配对	当请求体通过而没有其请求头时，命名无法识别的工具架构字段的 `400`	转发两者，或 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
努力和结构化输出	`output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对	在 Bedrock 和 Vertex 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted`	一起转发字段及其请求头
令牌计数	无 beta 配对；使用 `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 后面没有效果。

自动重试和错误转发

Claude Code 在某些上游拒绝后自动重试，并为对话的其余部分禁用被拒绝的功能。thinking 字段的拒绝、思考签名的拒绝和中途对话系统消息的拒绝都以这种方式恢复。上下文管理和工具架构字段拒绝不重试；这些 400 错误到达开发者。重试逻辑与上游的错误措辞匹配，因此原封不动地转发错误响应体。将上游错误包装在自己的信封中的 gateway 会破坏恢复路径，即使它保留了状态代码。

禁用预发布功能

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 阻止 Claude Code 在每个提供商上发送预发布功能及其请求体字段，包括上下文管理和 beta 工具字段。它不影响自适应推理，后者由模型而不是 beta 选择，它永远不会抑制订阅身份验证所需的 OAuth 功能。 Claude Code 发送的功能集随版本增长。有关当前 beta 请求头字符串，请参阅 beta 请求头参考；针对新的 Claude Code 版本测试您的 gateway，而不是固定到观察列表。

模型发现

当 ANTHROPIC_BASE_URL 指向公开 Anthropic Messages 格式的 gateway 时，Claude Code 可以在启动时查询 gateway 的 /v1/models 端点，并将返回的模型添加到 /model 选择器。开发者通过在自己的环境中或通过托管设置设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 来启用它。发现默认关闭，以便由共享 API 密钥支持的 gateway 不会向每个用户公开密钥可以访问的每个模型。这需要 Claude Code v2.1.129 或更高版本。

发现何时运行

发现仅适用于 Anthropic Messages 格式。在以下情况下不运行：

设置了任何 CLAUDE_CODE_USE_* 提供商变量，即使也设置了 ANTHROPIC_BASE_URL
ANTHROPIC_BASE_URL 未设置或指向 api.anthropic.com
非必要流量被禁用，通过 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 或组织策略

请求和响应

请求是 GET /v1/models?limit=1000，超时为 3 秒，任何重定向都被视为失败，因此凭证不会泄露到重定向目标。响应缓慢或重定向 /v1/models 的 gateway，即使是 http 到 https，也会无声地失败发现；在配置的基础 URL 处直接提供端点。发现请求恰好发送一个凭证请求头：

设置时 ANTHROPIC_AUTH_TOKEN 作为承载令牌
否则解析的 API 密钥，包括 apiKeyHelper 值，在 x-api-key 请求头中

这与推理请求不同，后者在两个请求头中发送帮助程序值。验证 /v1/models 的 gateway 必须为帮助程序部署接受 x-api-key。来自 ANTHROPIC_CUSTOM_HEADERS 的任何请求头也包括在内。 Claude Code 从响应的 data 数组中的每个条目读取 id 和可选的 display_name，并忽略其 id 不以 claude 或 anthropic 开头的条目：

{
  "data": [
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6" },
    { "id": "claude-opus-4-7" }
  ]
}

选择器条目和缓存

选择器是当开发者在 Claude Code 中运行 /model 时打开的交互式模型列表。每个发现的条目都标记为”来自 gateway”，并在提供时使用 display_name。仅当发现的 ID 与选择器中已有的行完全匹配时，或当发现的和现有的 ID 都解析为 Fable 时，才会跳过发现的 ID。内置行按别名（如 sonnet）键入，因此发现的 ID（如 claude-sonnet-4-6）在内置条目旁边添加自己的”来自 gateway”行。availableModels 托管设置限制了发现可以添加的内容。结果被缓存到 ~/.claude/cache/gateway-models.json，或在 Windows 上 %USERPROFILE%\.claude\cache\gateway-models.json，并在每次启动时刷新。如果请求失败或 gateway 未实现 /v1/models，选择器会回退到上次启动的缓存列表或内置模型列表。如果您的 gateway 在不匹配发现过滤器的别名下提供 Claude 模型，开发者可以使用模型配置变量手动添加这些别名。有关 gateway 文档集的其余部分和基础 API 参考：

LLM gateway 概述：gateway 是什么以及它如何与 claude.ai 订阅交互
为您的组织推出 LLM gateway：使用此契约的管理员检查清单
将 Claude Code 连接到 LLM gateway：每个开发者的配置和故障排除表
Beta 请求头参考：当前的 anthropic-beta 值集
Messages API：Anthropic 格式 gateway 实现的 API 格式

​API 格式

​Foundry 和 AWS 上的 Claude Platform

​可选端点和启动流量

​流式传输

​与上游的格式不匹配

​请求头

​作为开放列表转发

​系统提示归属块

​功能传递

​自动重试和错误转发

​禁用预发布功能

​模型发现

​发现何时运行

​请求和响应

​选择器条目和缓存

​相关资源

API 格式

Foundry 和 AWS 上的 Claude Platform

可选端点和启动流量

流式传输

与上游的格式不匹配

请求头

作为开放列表转发

系统提示归属块

功能传递

自动重试和错误转发

禁用预发布功能

模型发现

发现何时运行

请求和响应

选择器条目和缓存

相关资源