Anthropic 使用 beta header 来作为 feature flag:https://platform.claude.com/docs/en/api/beta-headers。官方文档上并没有列出所有的 beta header,而且不同平台的 Anthropic 模型上支持的 beta header 也不一致。
之前写过一篇文章拆 Claude Code 源码里的 prompt cache 的行为:https://segmentfault.com/a/1190000047693863。当时估摸着 Claude Code 里应该有一些私有的 beta header。事实上果然如此。这篇文章就是作为上一篇文章留下的边角料,做些拓展写出来的。
Beta Header 的传递方式,四个平台各不相同
这里四个平台指
- 直接 API
- Azure Foundry
- Vertex
- Bedrock
事实上 databricks 上也能跑 Anthropic 模型,不过用的人估计不多,这里也不展开写写了。省事。
在聊具体 header 之前,先说一个很容易踩坑的事:beta 信息在四个平台上的传递方式是不一样的。在有些平台上甚至不能算是 header。
直接调用 Anthropic API 时,beta 走的是 HTTP header:
anthropic-beta: interleaved-thinking-2025-05-14,context-1m-2025-08-07
Azure(Microsoft Foundry)的端点格式是 https://{resource}.services.ai.azure.com/anthropic/v1/messages,本质上是 Anthropic API 的代理层。beta 传递方式和直接 API 完全一样 —— anthropic-beta 放在 HTTP header 里。SDK 层面用的是 AnthropicFoundry 类,但最终生成的 HTTP 请求和直接 API 几乎一致,anthropic-version 也是 2023-06-01。Claude Code 源码里把 Foundry 和直接 API 归为同一组来处理 tool search header,就是因为这个原因。
Vertex 的 rawPredict / streamRawPredict 端点也是透传 HTTP header,所以和直接 API 一样,anthropic-beta 放在请求头里就行。区别在于 Vertex 的 anthropic_version 要填 vertex-2023-10-16,而不是直接 API 的版本号。
Bedrock 就不一样了。Bedrock 的 Converse API 不透传 HTTP header,beta 信息要放进请求体:
{
"additionalModelRequestFields": {
"anthropic_beta": ["context-1m-2025-08-07"]
}
}
如果用 AWS 的 Python SDK boto3 直接调 InvokeModel,则是 body 里的顶层字段 anthropic_beta。Anthropic 自己的 Bedrock SDK 会帮你做这个转换——你还是写 betas=[...],SDK 内部映射到 body 字段。但如果你自己拼请求,或者在做网关转发,这个差异不注意就会出问题。我见过有人把 anthropic-beta HTTP header 原封不动地转发给 Bedrock 端点,结果当然是被忽略了,功能默默地没开。不报错,就是不生效。
| 平台 | beta 传递方式 |
|---|
| 直接 API | HTTP header anthropic-beta |
| Azure (Foundry) | HTTP header anthropic-beta |
| Vertex rawPredict | HTTP header anthropic-beta |
| Bedrock Converse | body additionalModelRequestFields.anthropic_beta |
| Bedrock InvokeModel | body 顶层 anthropic_beta |
Claude Code 源码里也能印证这一点。代码里有一段注释明确说 Bedrock 的一小部分 beta 不走 header 而是走 body 里的 anthropic_beta。做网关的人如果想同时代理四个平台,这是第一个要处理的分歧。
动态工具加载:同一能力,两个 header
上一篇文章里提到的 tool search 能力,在平台维度上值得单独拎出来说。
Claude Code 源码里对这个能力用了两个不同的 header:
advanced-tool-use-2025-11-20:用于直接 API / Foundrytool-search-tool-2025-10-19:用于 Vertex / Bedrock
两者本质是同一类能力——动态工具加载。tool schema 里会出现 defer_loading,消息内容里会出现 tool_reference。但同一个功能在不同平台上 header 名字不一样,这种事如果你不看代码,光看文档是未必能发现的。
对应的 body 变化是一样的:
{
"name": "SomeTool",
"input_schema": { "type": "object" },
"defer_loading": true
}
{
"type": "tool_reference",
"tool_name": "SomeTool"
}
做网关转发的时候,需要根据目标平台选择正确的 header。如果你把 advanced-tool-use 发到 Bedrock 上,或者把 tool-search-tool 发到直接 API 上,大概率会收到 invalid beta flag。
顺手解释一下文中会反复出现的一个术语:agentic query。
这个词在 Claude Code 里不是泛泛而谈的“代理式调用”,而是代码里一个明确的布尔条件。凡是这些 querySource,都会被当成 agentic query:
repl_main_thread*agent:*sdkhook_agentverification_agent
可以把它理解成“代理真正正在干活”的请求:模型会基于当前上下文推进任务、决定是否调用工具、消费工具结果、继续下一步。相对地,像 token count、compact、side question、classifier、extract memories 这类辅助请求,一般不算 agentic query。这个区分很重要,因为 Claude Code 有一批 beta header 只应该出现在 agentic query 上;如果辅助请求也乱带这些 header,最常见的后果不是功能变多,而是 cache key 被打碎,或者 provider 直接 400。
Claude Code 里的全部 Beta Header
这里按用途做个快速汇总,每个展开讲一些平台维度的细节。
协议身份与模式标识
这类 header 不对应具体 body 字段,更像是告诉服务端"我是谁、我要怎么工作"。
claude-code-20250219 是 Claude Code 的主协议标识,所有 agentic query 都会带上它。它不开启某个具体字段,而是告诉服务端这不是普通聊天调用,而是一个具备工具调用、长会话、缓存、推理控制能力的客户端。从 Claude Code 源码看,它会作为普通 model beta 出现在直接 API、Foundry、Vertex 这些路径里;Bedrock 只有少数特定 beta 会被搬到 body 里的 anthropic_beta,而 claude-code-20250219 不在那份名单里。也就是说,至少按 Claude Code 当前实现,不能简单说它在 Bedrock 上会自动从 HTTP header 变成 body 字段。做代理的时候不要因为"看不出它控制哪个字段"就把它删掉。
cli-internal-2026-02-09 只在内部用户(USER_TYPE=ant)且入口是 CLI 时出现。外部用户正常情况下不会见到它。它和 claude-code-20250219 一样被当成 agentic query 基础协议的一部分,大概率是用来切换内部专属的 feature flag 或计费路径。如果你在代理层看到它……这个不太可能。
oauth-2025-04-20 不是开启某个推理字段,而是告诉服务端这次请求属于 Claude.ai OAuth / subscriber 通道。它通常和 Authorization: Bearer ... 以及 metadata.user_id 里的 account_uuid 一起出现。如果你只透传 Bearer token 不透传这个 header,行为不一定完全等价 —— 它不只是鉴权头的替代品,而是 OAuth 路径的一部分协议标识。这个 header 基本只在直接 API 上有意义,Bedrock 和 Vertex 有自己的鉴权机制。
afk-mode-2026-01-31 对应 auto mode / AFK mode 相关协议。Claude Code 只会在 agentic query 上发送它,classifier、compaction 这些辅助请求不会带。它不增加新的 body 字段,更像是请求模式标识——不要把它当成一个"任何时候都可以顺手加上的优化头",它是跟请求来源强绑定的。
上下文与缓存
context-1m-2025-08-07 对应 1M context 窗口能力。它不让 body 多出任何字段,而是让服务端按更大的上下文窗口处理请求。如果你把它去掉,模型可能退回较小的上下文窗口,但不会立刻报错——表现是更早触发 compact、上下文更早超限。目前直接 API、Foundry、Vertex 都支持,Bedrock 上部分模型也已支持。有意思的是 Azure Foundry 的文档明确说 Opus 4.6 和 Sonnet 4.6 有 1M context window,其他模型是 200K。
prompt-caching-scope-2026-01-05 本身是 no-op,只有和 body 里的 cache_control.scope 一起出现才真正生效。典型的配套用法是 "cache_control": {"type": "ephemeral", "scope": "global"}。只透 header 不透 scope 没有意义,只透 scope 不透 header 也不一定按预期工作。这里有个容易误解的点:Claude Code 会在 first-party 和 Foundry 路径上都带这个 header,但真正的 global scope 逻辑只在 first-party 上启用。也就是说,在 Foundry 上它更像一个协议位或 no-op;到了 Vertex 和 Bedrock,Claude Code 本身也不会走这条全局 scope 路径。
context-management-2025-06-27 是最典型的"header 和 body 字段成套出现"的能力之一。有这个 header 时,body 里会多出 context_management 字段,包含各种编辑策略:清理旧的 thinking turn、清理旧的 tool inputs / tool uses。它是 API-side 的上下文管理,只透 header 不透 body 没有意义,只透 body 不透 header 大概率会被服务端拒绝。需要注意的是,从 Claude Code 的自动加 header 逻辑看,它只会在 first-party 和 Foundry 路径上主动开启这项能力;至少不能仅凭 Claude Code 源码就断言 Vertex 和 Bedrock 也一定支持。更稳妥的说法是:直接 API 和 Foundry 明确在用,Vertex / Bedrock 是否支持要看各自平台文档和实测,而不是从 Claude Code 的实现反推。
summarize-connector-text-2026-03-13 对应服务端总结能力。代码注释描述得很清楚:API 会缓冲工具调用之间的 assistant text,服务端做总结,返回 summary 和 signature,后续 turn 可以再恢复原文。body 里没有专属字段,它更像服务端行为模式切换,但会改变返回内容的语义。
thinking 相关
interleaved-thinking-2025-05-14 和 body 里的 thinking 参数严格配套。Claude Code 请求里常见两种形状:{"thinking": {"type": "adaptive"}} 和 {"thinking": {"type": "enabled", "budget_tokens": 4000}}。有了这个 header 后响应流会出现 thinking 相关 block,streaming 时有 thinking_delta、signature_delta 之类的事件。这不是"只加个 header 就好"的能力——如果中间层不透传 thinking body 或不透传原始 thinking SSE 事件,Claude Code 会直接不兼容。四个平台都支持 thinking,但 Foundry 文档特别提到 Mythos Preview 只支持 adaptive 和 enabled,不支持 disabled。
redact-thinking-2026-02-12 不是开启 thinking,而是改变 thinking 的返回方式。有了它之后服务端更可能返回 redacted_thinking 而不是把 summary 原文直接暴露出来。它通常和已有的 thinking 参数一起工作,不新增 body 字段,但会改变返回的 content block 类型。如果你的中间层对 content block 类型有白名单,redacted_thinking 很容易被误删或误判。
工具与输出
structured-outputs-2025-12-15 至少对应两类 body 变化。一种是结构化输出格式(output_config.format 配 JSON schema),另一种是 tool schema 上的 strict 字段让工具调用更严格。strict 很容易被第三方网关当成"额外字段"清理掉,如果代理有 tool schema 校验或重写逻辑,这里是高风险区。
token-efficient-tools-2026-03-28 的重点不是"长出一个新字段",而是切换 tool_use 的编码方式。代码注释写得很清楚,它对应 JSON tool_use format,目标是减少 output tokens。body 里没有固定专属字段,它真正改变的是模型输出如何编码工具调用。不要只看"body 有没有新字段"来判断一个 beta 是否重要——有些 beta 改的是响应协议。
advanced-tool-use-2025-11-20 / tool-search-tool-2025-10-19 是动态工具加载协议,上面已经单独拆过。直接 API 和 Foundry 用前者,Vertex 和 Bedrock 用后者。对应的 body 变化是 tool schema 里的 defer_loading 和 message content 里的 tool_reference。这是第三方代理最容易打坏的一组能力——很多代理不支持 tool_reference,很多代理会把 defer_loading 当成非法字段。
web-search-2025-03-05 对应 provider-native web search,不等于 Claude Code 本地的 WebSearchTool。从主 /v1/messages 调用里看不到一个与它一一对应的固定字段,它更像 provider 侧的原生搜索能力开关。不要把它和本地工具调用混为一谈。Foundry 文档里提到支持 "Web fetch",但那和这个 provider-native search 不完全是一回事。
advisor-tool-2026-03-01 对应 advisor server tool。进入 agentic query 时,请求体的 tools 数组里可能多一个 {"type": "advisor_20260301", "name": "advisor", "model": "..."}。它有个有趣的设计:即使非 agentic query 也尽量带着这个 header,因为历史里可能已经有 advisor 相关 block,后续请求至少要有能力解析。这是"header 可能常驻,但真正的 body 能力主要在 agentic query 才活跃"的代表。
性能与控制
fast-mode-2026-02-01 和 body 里的 speed 配套,设计上很讲究。header 是 sticky-on 的 —— 一旦开了就一直带着,不改变 cache key。实际是不是走 fast,再由 speed 字段动态控制(比如 "speed": "fast")。只透 header 不透 speed 达不到想要的运行态效果,只透 speed 不透 header 也可能被 API 拒绝或表现不一致。
effort-2025-11-24 对应推理投入度控制。最常见的 body 形状是 "output_config": {"effort": "low"}。对于内部用户的数值 override,还会走另一条路径:"anthropic_internal": {"effort_override": 0.7}。这是"同一个 beta 对应多种 body 形状"的典型例子。外部兼容至少要保证 output_config.effort 不被删掉。Foundry 文档明确列出了支持的 effort 级别:low、medium、high,Opus 4.6 和 Sonnet 4.6 还额外支持 max。
task-budgets-2026-03-13 对应任务预算感知。body 里会新增 output_config.task_budget,包含 type、total、remaining 等字段,让模型知道当前任务还剩多少预算。这是标准的 header+body 成套能力。如果代理会重写 output_config,这里很容易被误伤。
非 /v1/messages 的专用 header
files-api-2025-04-14 是 Files API 的 beta。它打开的是 Files API 本身,允许在 public API route 上使用 Bearer OAuth。Foundry 文档提到支持 Files API,Bedrock 和 Vertex 上没有对应端点。
mcp-servers-2025-12-04 用于 Claude.ai 组织级 MCP server 配置接口,访问的是 /v1/mcp_servers 这类专门端点。Foundry 文档提到支持 "MCP connector",但走的可能是不同的接入方式。Bedrock 和 Vertex 上这个端点不存在。
ccr-byoc-2025-07-29 不属于主 Anthropic 推理协议,而是 Claude Code Remote / bridge / session history 这套后端接口的 beta——创建远程 session、访问 session events、remote setup / teleport 等。它只在 Anthropic 自己的后端有意义。
ccr-triggers-2026-01-30 也是 CCR 体系的一部分,用于 /v1/code/triggers 相关接口。同样只在 Anthropic 后端接口上可用。
总结
直接 API 永远是第一个拿到新功能的。Foundry 紧随其后——从文档和 SDK 支持来看,Foundry 和直接 API 的功能对齐程度很高,毕竟底层请求实际上还是 Anthropic 在处理(Foundry 文档明确说 "Claude models run on Anthropic's infrastructure")。Vertex 和 Bedrock 通常会滞后。这不是什么秘密,但实际影响比听起来大 —— 如果你在 Bedrock 上跑 Claude Code,某些最新的 beta header 发过去会直接报 invalid beta flag。
不是所有 header 都能在四个平台上用。files-api、mcp-servers、ccr-byoc、ccr-triggers 这些非推理链路的 header,走的是 Anthropic 自己的后端接口。Foundry 因为是代理到 Anthropic 基础设施,Files API 是支持的;Bedrock 和 Vertex 上根本不存在对应的端点。