网关兼容性指南

本页记录 Claude Code 向网关发送的请求：它调用的端点、网关必须转发的头和请求体字段，以及转发不了时哪些功能会失效，面向配置网关的运营者。Claude apps gateway（Anthropic 的自托管网关）在 GET /protocol 提供自己的端点参考（涵盖该网关的登录、推理、托管设置、模型发现和遥测端点），与本页是分开的文档。本页用两个词描述网关对每个头和请求体字段的处理：原样转发（逐字节传给上游）和消费（网关可以为路由、归属或追踪读取它，不必转发）；没标原样转发的都可以由你消费或忽略。

API 格式

网关必须向 Claude Code 客户端暴露至少一种下列 API 格式；客户端选一种格式，并用「选择方式」一列的变量把 Claude Code 指向你的网关：

Google Cloud Agent Platform 是 Google Cloud 的 Claude 端点（原 Vertex AI），其变量名保留 VERTEX 拼写。Microsoft Foundry 和 Claude Platform on AWS 实现的是 Anthropic Messages 格式，Claude Code 通过它们各自的变量（ANTHROPIC_FOUNDRY_BASE_URL、ANTHROPIC_AWS_BASE_URL）路由。

可选端点与启动流量：token 计数端点是唯一可选的，缺失时 Claude Code 回退到基于字符的上下文用量估算。按路径匹配，而不是完整 URL：推理请求 post 到 /v1/messages?beta=true；Agent Platform 的方法后缀附加在发布者模型路径上。网关还会看到可以拒绝而不破坏任何东西的尽力而为的启动流量（Anthropic Messages 格式的网关会收到 HEAD /api/hello 连接预热探测）。快速模式可用性检查从不出现在网关日志里：它直接调用 api.anthropic.com 而不跟随 ANTHROPIC_BASE_URL，所以在阻止直连 api.anthropic.com 的网络上，快速模式可能报告连接错误。

流式

必须流式返回推理响应。Claude Code 在响应到达时就读取流，所以如果你的网关在转发前缓冲完整响应，Claude Code 会停滞。要求：

• 完整交付每个响应的事件序列，不丢弃、重复或重排事件；事件引用其 content_block_start 从未到达的内容块，或其 content_block_stop 已到达的块时，Claude Code 会报错
• 在结束响应体之前，转发到最终的 message_delta 和 message_stop 事件
• 客户端说 Amazon Bedrock 格式时，原样转发 InvokeModelWithResponseStream 响应体及其 Content-Type: application/vnd.amazon.eventstream 头，不要把流转换成服务器发送事件
• 转发保活 ping：Claude Code 默认在五分钟没有任何字节到达时中止流式响应；长时间思考暂停期间，上游的 SSE ping 事件可能是流上仅有的字节

与上游的格式不匹配

客户端说的格式决定网关收到什么。常见的故障模式是客户端发给你网关的格式与你后面的上游提供商接受的格式不匹配：客户端说 Bedrock 或 Agent Platform 格式时，Claude Code 只发送这些提供商接受的那部分能力集；客户端说 Anthropic Messages 格式时，Claude Code 发送完整能力集，即使你的网关转发到 Bedrock 或 Agent Platform 上游。弥合这个差异是网关的工作。如果你的上游是 Bedrock 或 Agent Platform，可以改为暴露该提供商的格式来避免桥接。

连接方式如何改变客户端行为

开发者连接到网关的方式决定 Claude Code 发送哪些模型 ID、anthropic-beta 值和请求字段，以及应用哪些默认值。你的网关会看到三种客户端行为之一：Bedrock 或 Agent Platform 格式（开发者设置 CLAUDE_CODE_USE_BEDROCK=1 加 ANTHROPIC_BEDROCK_BASE_URL，或 CLAUDE_CODE_USE_VERTEX=1 加 ANTHROPIC_VERTEX_BASE_URL，指向你的网关）；Anthropic Messages 格式（开发者把 ANTHROPIC_BASE_URL 设为你的网关，Claude Code 把网关当作 Claude API，无法分辨你转发到哪个上游）；Claude apps gateway 登录（该网关说 Anthropic Messages 格式但可以路由到任何上游，所以 Claude Code 只发送 Bedrock 和 Agent Platform 也接受的 anthropic-beta 值和模型能力假设）。

不识别的模型 ID 的设置：两个客户端设置改变 Claude Code 对不识别的模型 ID（如网关别名）的假设，无论开发者用哪种连接方式：上下文窗口（Claude Code 假设 200K，ID 带 [1m] 时是 1M，要声明真实窗口，见「为网关或自定义模型 ID 校正窗口」）；能力（要给网关别名其背后模型的能力，在你分发的设置里用 modelOverrides 条目把该模型的 Anthropic ID 映射到你的别名）。

请求头

Claude Code 在 API 请求上带有这些头（头名在传输上不区分大小写）。anthropic-version 和 anthropic-beta 要原样转发，当上游是 Claude Platform on AWS 时还要转发 anthropic-workspace-id；其余的网关可以为路由、归属和追踪消费，不必转发。

子智能体 ID 每次派生都重新生成；智能体团队的成员（teammate）在重连间复用基于名字的稳定 ID。两种情况下 ID 标识的都是智能体，不是人或设备，不要把它当用户标识。开发者设置了 ANTHROPIC_CUSTOM_HEADERS 时，这些头也会出现在请求上。

网关提示头

Claude Code 还能发送路由提示头：按请求给出的事实，网关或路由器可据此调度、缓存或归属请求（需要 v2.1.273 及以上）。是否携带取决于连接目标：

• 直连 Anthropic API：默认发送
• 自定义 base URL：默认不发，因为拒绝未知头的代理会让请求失败；要接收，给开发者设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1（比如放进托管设置的 env）
• 其他后端（Bedrock、Google Cloud Agent Platform、Microsoft Foundry、Claude Platform on AWS）：仅在设置 CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 时发送

把它设为 0 则在所有连接上都不发。这些头只携带固定词表、工具名、耗时和随机的提示标识，不含提示文本或文件内容，值都是可打印 ASCII。

解析 x-claude-code-prev-tool-durations 前要知道它的构造：每个已运行的工具调用一项，按收集结果的顺序、以整毫秒计；最多 32 项和 4 KB，保留靠前的项；工具名要对 %、;、=、逗号、空格和非可打印 ASCII 字符做百分号编码，所以先按 ; 分、再按 = 分，然后解码名字；压缩调用、旁路请求和新提示的第一个请求不带它，不能把缺失理解成这一轮没有工具运行；耗时不含权限提示和 hooks，并行工具各报各的时间，所以各项之和不等于两次请求的间隔。

按开放列表转发

把头和请求体字段当作开放列表。Claude Code 的新能力会以新的 anthropic-beta 值、新请求体字段、偶尔新的 anthropic-* 或 x-claude-code-* 头出现。转发到 Anthropic 格式上游时，anthropic-* 请求头和请求体字段要原样透传，不要按今天看到的列表做白名单——钉死在已观察列表上的网关会在引入新能力的那个版本把它的头或字段剥掉而导致失效。例外是 Bedrock、Google Cloud Agent Platform 这类非 Anthropic 上游，弥合 schema 差异是网关的工作。

响应头

Claude Code 读这些响应头来检测流停滞、决定是否以及何时重试、显示用量限制。另外，错误响应体要原样转发，这样 Claude Code 的能力被拒恢复逻辑才能匹配上游的错误措辞。

系统提示的归属块

Claude Code 会在系统提示前加一个简短的归属块，含客户端版本和由对话派生的指纹。当它作为第一个 system 块原样到达时，api.anthropic.com 会在处理前将其剥离，所以不影响第一方的提示缓存；其他上游则不会剥。剥离依赖位置，因此网关必须原样转发 system 数组：

• 保持该块在最前，不要在前面再插别的 system 块、不要重排、不要把数组合并成单个字符串，否则块会进入模型和提示缓存键
• 让它独占一个数组项：端点会把以归属头开头的合并块整体当作归属并丢弃，连同合并进去的系统提示其余部分
• 如果网关必须重塑 system 内容，设 CLAUDE_CODE_ATTRIBUTION_HEADER=0 让 Claude Code 不发该块，而不是在网关里剥离或挪动

该变量是为网关和第三方缓存兼容而存在，不是隐私开关。当请求发往 api.anthropic.com 且凭据不是 Anthropic profile/联合凭据时，auto mode 分类器请求即使设了 0 也保留该块。自 v2.1.181 起，经自定义 base URL 时该块在一次对话内保持稳定，所以按完整请求体建键的网关缓存无需禁用它就能工作；之前的版本里它含会变化的部分，会降低网关缓存和转发给第三方提供商时的缓存命中。

功能透传

Claude Code 把 ANTHROPIC_BASE_URL 网关当作 Anthropic 格式端点，发送与直连 api.anthropic.com 相同的 beta 头和请求体字段，只有少数诊断和默认值只留给直连。新增请求体字段的能力会和 beta 头成对出现，要一起走：网关剥掉头却放行请求体，或把 Anthropic 格式请求体转给 schema 不同的上游，会出现硬性 400；两半同时缺失才会安静地关闭该功能。细粒度工具流默认只在直连时开启，经自定义 base URL 时要开发者设 CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1。

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 字段、对话中途的 system 消息或其 cache_control 标记：重试，并在本次对话剩余部分禁用被拒的能力
• 上游拒绝思考签名（包括 400 且消息说块 bound to a different conversation）：从请求中移除之前的思考块，重试，并在之后的请求里都不带；新响应仍包含思考
• 网关或上游把 tools 里的 advisor 工具项当作未识别工具类型拒绝：去掉该项及其 anthropic-beta 值重试一次；到 Claude Code 退出前对该 base URL 都不再带 advisor，开发者无法使用 /advisor
• 上下文管理或工具 schema 字段被拒：不重试，400 直接到达开发者

bound to a different conversation 来自 API 的保留思考校验，当 system、tools 或之前的 messages 内容与产生该思考的请求不同时失败，所以改写这些内容的网关自己就会引发该拒绝。重试逻辑按上游错误措辞匹配，因此错误响应体要原样转发；把上游错误包进自己信封的网关会破坏恢复路径，除非信封的消息里带稳定的 capability_rejected: 标记。

关闭预发布能力

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 让 Claude Code 不再发送预发布能力及其请求体字段，包括上下文管理和 beta 工具字段。它不影响自适应推理（按模型而不是 beta 选择）。v2.1.227 起，组织可以通过托管设置在该变量下保持 MCP 工具搜索开启：直连或经 ANTHROPIC_BASE_URL 网关时会继续发送工具搜索 beta 头、defer_loading 工具字段和 tool_reference 块，其余被剥；经云提供商或 Claude apps gateway 登录时该覆盖无效。Claude Code 发送的能力集合随版本增长，要用新版本测试网关，而不是钉死在已观察的列表上；当前 beta 头字符串见官方的 beta headers 参考。

模型发现

ANTHROPIC_BASE_URL 指向暴露 Anthropic Messages 格式的网关时，Claude Code 可在启动时查询网关的 /v1/models，把返回的模型加进 /model 选择器。如果你或管理员在 modelPicker 阵容里设了 replaceBuiltInOptions，发现的模型会被隐藏。开发者用 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 开启（在自己的环境或通过托管设置）；默认关闭，以免共享 API key 的网关把 key 能访问的所有模型暴露给每个用户。

何时运行：只适用于 Anthropic Messages 格式；设了任何 CLAUDE_CODE_USE_* 提供商变量（即使同时设了 ANTHROPIC_BASE_URL）不运行，ANTHROPIC_BASE_URL 未设或指向 api.anthropic.com 也不运行。关闭非必要流量时发现仍会运行，因为请求只发给你的网关（v2.1.257 之前不运行）。

请求与响应：请求是 GET /v1/models?limit=1000，默认超时 3 秒，任何重定向都视为失败以免凭据泄漏到重定向目标；响应慢于超时或重定向 /v1/models（哪怕是 http 到 https）都会静默失败，所以要直接在最终地址提供该端点。要给慢网关更久时间，设 CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS（v2.1.269 及以上）。请求同时带两个凭据头，值解析不出的头会省略（同时发两个头需要 v2.1.248 及以上，更早版本在设了 ANTHROPIC_AUTH_TOKEN 时只发 Authorization，否则只发 x-api-key）：

• Authorization：ANTHROPIC_AUTH_TOKEN 作为 bearer token，否则用 apiKeyHelper 的值作为 bearer token
• x-api-key：Claude Code 解析出的 API key（如 ANTHROPIC_API_KEY）；只有 helper 值这一种凭据时，这个头也带它，所以该值会同时出现在两个头里

自定义头（ANTHROPIC_CUSTOM_HEADERS）也会发送；值非空的自定义头会替换同名（不区分大小写）的内置头。两个凭据头都解析不出时跳过发现，并在 claude --debug 的调试日志里写一行 [gatewayDiscovery] skipped；只通过 ANTHROPIC_CUSTOM_HEADERS 提供凭据时同样会跳过。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" }
  ]
}

条目的 id 里含 claude 或 anthropic（不区分大小写）才保留，其余忽略。带提供商前缀的 ID 如 vertex_ai/claude-sonnet-4-6 或 bedrock/anthropic.claude-sonnet-4-5 能通过过滤；两个子串都不含的 ID 不能。选择器条目与缓存的细节，见官方原文。