Claude Code 网关与用量

网关协议参考

4 分钟阅读

网关协议参考

Claude Code 与 LLM 网关之间的 API 契约：需要转发的端点、请求头和正文字段；字段被剥离时会降级的功能；用于成本跟踪的归因请求头；以及模型发现。

本页说明 Claude Code 向网关发送的请求，包括它调用的端点、网关必须转发的请求头和正文字段，以及网关未转发这些内容时哪些功能会停止工作。本页面面向需要配置网关产品以配合 Claude Code 使用的运维人员。

运行中的 Claude 应用网关会通过 GET /protocol 提供这份契约的机器可读版本。它包含相同的转发要求，以及 Claude 应用网关专用的 SSO 登录、托管设置交付和遥测端点。Claude 应用网关与 CLI 使用同一个 claude 二进制文件运行，因此，要启动一个可从中获取规范的实例，最短路径是按照 Claude 应用网关快速入门操作。

要为组织推广部署现有或第三方网关，请参阅推广部署 LLM 网关
如果你是个人开发者，需要使用分配给你的凭证让 Claude Code 通过网关进行身份验证，请参阅将 Claude Code 连接到 LLM 网关

本页涵盖：

API 格式，以及每种格式需要提供的端点
请求头：哪些必须送达上游，哪些可以由网关消费
系统 Prompt 归因块，以及它与 Prompt 缓存的交互方式
功能透传：剥离请求头或正文字段时哪些功能会失效
模型发现

本页使用以下两个术语说明网关应如何处理各请求头和正文字段：

原样转发：逐字节传给上游
消费：网关可以读取它以执行路由、归因或追踪，无需继续转发

未标记为原样转发的内容可由网关自行消费或忽略。

API 格式

网关必须向 Claude Code 客户端公开以下至少一种 API 格式。Claude Code 使用哪种格式，取决于客户端配置：下表“选择方式”列中的变量会让 Claude Code 以相应格式连接网关。Google Cloud's 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`	`anthropic_beta` 和 `anthropic_version` 请求正文字段
Google Cloud's Agent Platform rawPredict	`ANTHROPIC_VERTEX_BASE_URL` 与 `CLAUDE_CODE_USE_VERTEX=1`	`:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选）	`anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求正文字段

Foundry 和 Claude Platform on AWS

Microsoft Foundry 和 Claude Platform on AWS 实现了 Anthropic Messages 格式。Claude Code 通过各自的变量 ANTHROPIC_FOUNDRY_BASE_URL 和 ANTHROPIC_AWS_BASE_URL 路由到它们，但作为其中任一平台前置层的网关，都应实现上表中的 Anthropic Messages 格式。Claude Platform on AWS 的前置网关还必须转发 anthropic-workspace-id 请求头，该平台要求每个请求都携带此请求头。

可选端点和启动流量

只有 Token 计数端点是可选的：没有这些端点时，Claude Code 会在本地估算上下文用量。推理请求会 POST 到 /v1/messages?beta=true，因此，请匹配路径，而不是完整 URL。Google Cloud's Agent Platform 的方法后缀会附加到发布者模型路径，例如 /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict。

网关还会看到一些尽力而为的启动流量，拒绝这些请求不会破坏任何功能：一个 HEAD / 连接探测；对于 Amazon Bedrock 格式的网关，还有一个 GET /inference-profiles?type=SYSTEM_DEFINED 请求。

流式传输

推理响应必须以流式方式传输。Claude Code 会在服务器发送事件到达时立即消费，因此，如果网关先缓冲完整响应再进行中继，客户端就会停滞等待。

与上游的格式不匹配

客户端使用的格式决定了网关接收到的内容。常见故障是客户端发给网关的格式与网关背后上游提供商接受的格式不一致。

客户端使用 Amazon Bedrock 或 Google Cloud's Agent Platform 格式时，Claude Code 只发送这些提供商能够接受的完整能力子集
客户端使用 Anthropic Messages 格式时，Claude Code 会发送完整能力集，即使网关最终转发到 Amazon Bedrock 或 Google Cloud's Agent Platform 上游也是如此

弥合这一差异是网关的职责。功能透传说明网关没有妥善处理时会有哪些功能失效。

请求头

Claude Code 的 API 请求中包含以下请求头。请求头名称在传输过程中不区分大小写。请原样转发 anthropic-version 和 anthropic-beta；上游为 Claude Platform on AWS 时还应转发 anthropic-workspace-id。其余请求头可由网关消费，用于路由、归因和追踪，无需继续转发。

请求头	说明
`Authorization`、`x-api-key`	开发者的网关凭证。根据开发者设置的凭证变量，凭证会出现在其中一个或两个请求头中
`anthropic-version`	API 版本，当前为 `2023-06-01`。Amazon Bedrock 和 Google Cloud's 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 会随着版本迭代获得新能力，这些能力会以新的 anthropic-beta 值、新的请求正文字段，偶尔也会以新的 anthropic-* 或 x-claude-code-* 请求头出现。

转发到 Anthropic 格式的上游时，应原样传递 anthropic-* 请求头和请求正文字段，不要仅允许当前看到的字段。网关如果固定使用曾经观察到的列表，就会剥离下一个新能力的请求头或字段，导致该能力在引入它的版本中失效。

但 Amazon Bedrock 或 Google Cloud's Agent Platform 等非 Anthropic 上游除外：弥合 schema 差异是网关的职责；请参阅功能透传。

系统 Prompt 归因块

Claude Code 会在系统 Prompt 前添加一个简短的归因块，其中包含客户端版本以及从对话派生的指纹。如果此块未经修改、且作为第一个系统块送达，api.anthropic.com 端点会在处理前将其移除，因此它不会影响第一方 Prompt 缓存。其他上游则会把它作为 Prompt 的一部分接收。

移除操作取决于位置，因此只有网关原样转发 system 数组时才会生效。要在不丢失其他系统内容的情况下，使 Prompt 不包含此块：

按收到时的内容原样转发 system 数组，并将该块保持在首位：在它之前添加另一个系统块、重新排列数组，或将数组转换为单个字符串，都会导致移除失败；这样，该块便会送达模型，并计入 Prompt 缓存键。
将该块保留为单独的数组项：如果合并后的块以归因请求头开头，端点会将整个合并块视为归因并丢弃，其中也包括合并进来的系统 Prompt 其余内容。
如果网关必须重塑系统内容，请设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0，让 Claude Code 省略该块。Anthropic 和云提供商的 Claude 端点会读取该块以进行归因，因此，应从客户端省略它，不要在网关中将其剥离或移动。

未经修改便到达端点的请求不受影响。

自 Claude Code v2.1.181 起，通过自定义 base URL 路由请求时，此块在整个对话生命周期内保持稳定，因此，即使网关侧的 Prompt 缓存以完整请求正文为键，也无需禁用此块。v2.1.181 之前，此块包含按请求生成的 Token；在这些版本中，如果网关实现了此类缓存，请设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0。

功能透传

Claude Code 将 ANTHROPIC_BASE_URL 网关视为 Anthropic 格式的端点，并向其发送与发给 api.anthropic.com 相同的测试版请求头和请求正文字段，但少量只用于直连的诊断信息和默认设置除外，例如下面介绍的细粒度工具流式传输默认设置。这组例外随版本而变化，因此不要依赖其中包含哪些内容。

凡是通过正文字段添加的能力，都会配有一个测试版请求头，二者一同传输。网关如果剥离请求头但保留正文，或者把 Anthropic 格式的正文转发到使用其他 schema 的上游，就会产生明确的 400 错误；只有请求头与正文字段同时缺失时，相应功能才会静默关闭。网关为检查内容而重写或隐去请求正文，也会像剥离字段一样破坏这种配对关系，因此，请只检查而不要修改。下表会注明不遵循这种配对关系的功能。

细粒度工具流式传输是仅限直连的默认设置之一：只要请求通过自定义 base URL 路由，该功能默认关闭；开发者设置 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1 后，网关才会收到相关内容。

功能	请求头与正文的配对关系	出现问题时的症状	解决方法
自适应推理	无测试版请求头。对于 Claude 4.6 及更高版本，Claude Code 会发送 `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	同时转发二者，或设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
扩展上下文和交错式思考	只有测试版请求头，没有正文字段	剥离请求头后会静默变为不可用；上游永远不会看到相关能力请求	逐字转发 `anthropic-beta`
测试版工具字段	工具相关测试版请求头与 `strict`、`defer_loading` 等工具 schema 字段配对	正文在没有相应请求头的情况下通过时，返回提及无法识别的工具 schema 字段的 `400`	同时转发二者，或设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
Effort和结构化输出	`output_config` 正文字段包含 Effort、结构化输出格式和任务预算设置；各设置分别与自己的测试版请求头配对	Amazon Bedrock 和 Google Cloud's Agent Platform 上游返回提及 `output_config` 的 `400`，通常包含 `Extra inputs are not permitted`	将字段及其请求头一起转发
Token 计数	不与测试版请求头配对；使用 `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 网关后不生效。

自动重试和错误转发

遇到某些上游拒绝后，Claude Code 会自动重试，并在对话剩余期间禁用被拒绝的能力。对 thinking 字段、thinking signature以及对话中途系统消息的拒绝，都可通过这种方式恢复。上下文管理和工具 schema 字段被拒绝时不会重试；这些 400 错误会直接送达开发者。

重试逻辑会匹配上游错误的措辞，因此，请原样转发错误响应正文。即使网关保留状态码，只要将上游错误包装在自己的 envelope 中，也会破坏恢复路径。

禁用预发布能力

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 会阻止 Claude Code 在所有提供商上发送预发布能力及其正文字段，其中包括上下文管理和测试版工具字段。它不影响自适应推理，因为该功能按模型而不是按测试版选择；它也绝不会抑制订阅身份验证所需的 OAuth 能力。

Claude Code 发送的能力集合会随版本扩大。如需了解当前的测试版请求头字符串，请参阅测试版请求头参考；请针对 Claude Code 的新版本测试网关，不要固定使用曾经观察到的列表。

模型发现

当 ANTHROPIC_BASE_URL 指向公开 Anthropic Messages 格式的网关时，Claude Code 可以在启动时查询网关的 /v1/models 端点，并将返回的模型添加到 /model 选择器。

开发者可以在自己的环境中或通过托管设置，设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 来启用此功能。发现功能默认关闭，以免使用共享 API key 的网关向每位用户公开该 key 可访问的所有模型。此功能需要 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（即使只是从 http 重定向到 https），发现功能也会静默失败；请直接在配置的 base URL 上提供该端点。

发现请求只会发送一个凭证请求头：

设置 ANTHROPIC_AUTH_TOKEN 后，以 bearer Token 形式发送
否则，在 x-api-key 请求头中发送解析后的 API key，其中包括 apiKeyHelper 返回的值

这与推理请求不同：推理请求会在两个请求头中都发送辅助程序返回的值。对 /v1/models 进行身份验证的网关必须在使用辅助程序的部署中接受 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-8" }
  ]
}

选择器条目和缓存

选择器是开发者在 Claude Code 中运行 /model 时打开的交互式模型列表。每个发现的条目都标记为“From gateway”，并在提供 display_name 时使用该名称。availableModels 托管设置会限制发现功能可以添加的内容。

如果发现的 ID 与选择器中现有的某一行完全匹配，或者发现的 ID 与现有 ID 均解析为 Fable，则会跳过该 ID。自 Claude Code v2.1.197 起，如果发现的显式 ID 和某个内置条目解析为同一模型，也会将其合并到该内置条目中。内置行以 sonnet 等别名为键，因此，如果发现的显式 ID 是该别名当前解析到的模型，例如 claude-sonnet-5，它就会合并到 sonnet 行；如果 ID 并非该别名解析到的模型，例如 claude-sonnet-4-6，则仍会在内置条目旁添加一行单独的“From gateway”。

结果会缓存到 ~/.claude/cache/gateway-models.json，在 Windows 上则缓存到 %USERPROFILE%\.claude\cache\gateway-models.json，并在每次启动时刷新。如果请求失败或网关未实现 /v1/models，选择器会回退到上次启动时的缓存列表，或回退到内置模型列表。如果网关使用不符合发现筛选条件的别名提供 Claude 模型，开发者可以通过模型配置变量手动添加这些别名。

网关协议参考

API 格式

Foundry 和 Claude Platform on AWS

可选端点和启动流量

流式传输

与上游的格式不匹配

请求头

作为开放列表转发

系统 Prompt 归因块

功能透传

自动重试和错误转发

禁用预发布能力

模型发现

何时运行发现

请求和响应

选择器条目和缓存

相关资源