Claude Code 网关兼容性指南

• API 格式和每种格式要提供的端点
• 按连接方法的客户端行为：模型 ID、anthropic-beta 值、请求字段和默认值在格式和 Claude apps 网关登录之间的差异
• 请求标头：哪些必须到达上游，哪些您的网关可以使用
• 响应标头：返回什么以使停滞检测、重试和使用限制显示工作
• 系统提示属性块及其与提示缓存的交互方式
• 功能传递：删除标头或正文字段时会破坏什么
• 模型发现

• 转发不变：逐字节将其传递到上游
• 使用：网关可能会读取它以进行路由、属性或跟踪，不需要转发它

​

API 格式

​

Foundry 和 AWS 上的 Claude Platform

​

可选端点和启动流量

• 推理请求发送到 /v1/messages?beta=true
• Google Cloud 的 Agent Platform 方法后缀附加到发布者模型路径，如 /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict

​

流式传输

• 如果您的网关将响应一直缓冲到完整为止，Claude Code 会停滞。
• Claude Code 期望按顺序收到每个响应的完整事件序列，直到最终的 message_delta 和 message_stop 事件。如果正文在内容块已启动之后、但在最终 message_delta 之前正常结束，Claude Code 会将该响应视为连接断开。上述响应可能不完整描述了此时用户看到的内容，自动重试则说明了 Claude Code 何时会改为重新发出请求。
• 当 Amazon Bedrock 护栏拦截回复时，Bedrock 发送的事件可能会引用其 content_block_stop 已经到达的内容块，而 Claude Code 依赖于按原样接收这些事件。AWS Guardrails 描述了该回复如何结束。
• 一旦超过其流式空闲超时时间仍没有任何字节到达，Claude Code 就会中止流式响应。在长时间的思考暂停期间，上游的 SSE ping 事件可能是流上唯一的字节，因此剥离或缓冲这些事件的网关可能会在响应中途触发该超时。从不发送 ping 的上游（如 Amazon Bedrock 的二进制事件流）进行转换的网关也存在同样的间隙，除非它发出自己的 ping 事件。
• 在 Amazon Bedrock InvokeModel 格式下，Claude Code 会将 /model/{model}/invoke-with-response-stream 响应作为 Bedrock 返回的二进制 application/vnd.amazon.eventstream 正文来读取，一旦网关将其转换为服务器发送事件或重写该 Content-Type 头，Claude Code 就无法解析它。网关或代理后面的流式传输错误描述了此时用户看到的内容。

​

与上游的格式不匹配

• 当客户端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集
• 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集，即使您的网关转发到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

​

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

• 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 apps gateway 登录：开发者登录到 Claude apps gateway。该网关使用 Anthropic Messages 格式，但可以路由到任何上游，因此 Claude Code 仅发送 Amazon Bedrock 和 Agent Platform 也接受的 anthropic-beta 值和模型能力假设。

​

按连接方法的请求和默认值

​

未识别模型 ID 的设置

• 上下文窗口：Claude Code 假设 200K，或当 ID 包含 [1m] 时为 1M。要声明真实窗口，请参阅 为网关或自定义模型 ID 更正窗口
• 能力：要给网关别名赋予其后面模型的能力，请使用您分发的设置中的 modelOverrides 条目将该模型的 Anthropic ID 映射到您的别名。有关 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 会重试请求并为对话的其余部分禁用被拒绝的功能
• 当上游拒绝思考签名时，包括带有 400 的拒绝，其消息说该块被 bound to a different conversation，Claude Code 会从请求中删除早期思考块，重试，并将其排除在每个后续请求之外。新响应仍然包括思考
• 当 gateway 或其上游将顾问工具条目在 tools 中拒绝为无法识别的工具类型时，Claude Code 会重试一次请求，不包含该条目及其 anthropic-beta 值。对该基础 URL 的后续请求会将顾问排除在外，直到 Claude Code 退出，在该时间内 /advisor 对开发者不可用。Claude Code 通过 400 或 422 响应识别此拒绝，其消息在 Input tag 之后命名工具类型，例如 Input tag 'advisor_20260301'。在 v2.1.280 之前，Claude Code 没有重试此拒绝
• 当上游拒绝 output_config.effort 时，Claude Code 会在不带努力的情况下重试请求，并在 Claude Code 退出之前，在发往该模型的后续请求中省略它。Claude Code 通过 400 响应识别此拒绝，其消息同时命名 output_config.effort 和 Extra inputs are not permitted，或说明该模型不支持 effort 参数
• Claude Code 不重试上下文管理或工具架构字段拒绝，因此这些 400 错误到达开发者

​

禁用预发布功能

• 上下文管理及其 context_management 请求体字段
• beta 工具 schema 字段，例如 strict 和 defer_loading。标准的 name、description、input_schema 和 cache_control 工具字段会保留
• 结构化输出 output_config.format 字段。需要 Claude Code v2.1.287 或更高版本
• output_config.task_budget 字段
• MCP 工具搜索，因此每个 MCP 工具都会预先加载，除非您的组织通过托管设置保持其开启

• 扩展上下文、交错思考和努力的 anthropic-beta 值，云提供商也接受这些值
• output_config.effort 字段。自动重试和错误转发介绍了上游拒绝它的情况
• 自适应推理的 thinking 字段，它没有 beta 请求头
• 订阅身份验证所需的 OAuth anthropic-beta 值
• 开发者通过 ANTHROPIC_BETAS 或 CLAUDE_CODE_EXTRA_BODY 自行添加的请求头值和请求体字段

• 在未使用 HIPAA 配置的直接连接上，或通过设置了 ANTHROPIC_BASE_URL 的网关，Claude Code 继续发送工具搜索 beta 请求头、defer_loading 工具字段和 tool_reference 块
• 在云提供商上，或通过 Claude apps gateway 登录，覆盖没有效果
• 在获得 HIPAA 配置的会话中，覆盖没有效果，工具搜索保持关闭

​

模型发现

​

发现何时运行

• 设置了任何 CLAUDE_CODE_USE_* 提供商变量，即使也设置了 ANTHROPIC_BASE_URL
• ANTHROPIC_BASE_URL 未设置或指向 api.anthropic.com

​

请求和响应

• Authorization：ANTHROPIC_AUTH_TOKEN 作为承载令牌，否则 apiKeyHelper 值作为承载令牌。
• 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-5 时，发现的 claude-sonnet-5-5 会折叠到 sonnet 行中，而发现的 claude-sonnet-5 仍会获得自己的行。

​

相关资源

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