Anthropic Beta Header 全景：从 Claude Code 私有协议到四大平台的差异
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。事实上果然如此。这篇文章就是作为上一篇文章留下的边角料，做些拓展写出来的。 这里四个平台指 事实上 databricks 上也能跑 Anthropic 模型，不过用的人估计不多，这里也不展开写写了。省事。 在聊具体 header 之前，先说一个很容易踩坑的事：beta 信息在四个平台上的传递方式是不一样的。在有些平台上甚至不能算是 header。 直接调用 Anthropic API 时，beta 走的是 HTTP header： Azure（Microsoft Foundry）的端点格式是 Vertex 的 Bedrock 就不一样了。Bedrock 的 Converse API 不透传 HTTP header，beta 信息要放进请求体： 如果用 AWS 的 Python SDK boto3 直接调 InvokeModel，则是 body 里的顶层字段 Claude Code 源码里也能印证这一点。代码里有一段注释明确说 Bedrock 的一小部分 beta 不走 header 而是走 body 里的 上一篇文章里提到的 tool search 能力，在平台维度上值得单独拎出来说。 Claude Code 源码里对这个能力用了两个不同的 header： 两者本质是同一类能力——动态工具加载。tool schema 里会出现 对应的 body 变化是一样的： 做网关转发的时候，需要根据目标平台选择正确的 header。如果你把 顺手解释一下文中会反复出现的一个术语： 这个词在 Claude Code 里不是泛泛而谈的“代理式调用”，而是代码里一个明确的布尔条件。凡是这些 可以把它理解成“代理真正正在干活”的请求：模型会基于当前上下文推进任务、决定是否调用工具、消费工具结果、继续下一步。相对地，像 token count、compact、side question、classifier、extract memories 这类辅助请求，一般不算 agentic query。这个区分很重要，因为 Claude Code 有一批 beta header 只应该出现在 agentic query 上；如果辅助请求也乱带这些 header，最常见的后果不是功能变多，而是 cache key 被打碎，或者 provider 直接 400。 这里按用途做个快速汇总，每个展开讲一些平台维度的细节。 这类 header 不对应具体 body 字段，更像是告诉服务端"我是谁、我要怎么工作"。 直接 API 永远是第一个拿到新功能的。Foundry 紧随其后——从文档和 SDK 支持来看，Foundry 和直接 API 的功能对齐程度很高，毕竟底层请求实际上还是 Anthropic 在处理（Foundry 文档明确说 "Claude models run on Anthropic's infrastructure"）。Vertex 和 Bedrock 通常会滞后。这不是什么秘密，但实际影响比听起来大 —— 如果你在 Bedrock 上跑 Claude Code，某些最新的 beta header 发过去会直接报 不是所有 header 都能在四个平台上用。Beta Header 的传递方式，四个平台各不相同
anthropic-beta: interleaved-thinking-2025-05-14,context-1m-2025-08-07https://{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，就是因为这个原因。rawPredict / streamRawPredict 端点也是透传 HTTP header，所以和直接 API 一样，anthropic-beta 放在请求头里就行。区别在于 Vertex 的 anthropic_version 要填 vertex-2023-10-16，而不是直接 API 的版本号。{
"additionalModelRequestFields": {
"anthropic_beta": ["context-1m-2025-08-07"]
}
}anthropic_beta。Anthropic 自己的 Bedrock SDK 会帮你做这个转换——你还是写 betas=[...]，SDK 内部映射到 body 字段。但如果你自己拼请求，或者在做网关转发，这个差异不注意就会出问题。我见过有人把 anthropic-beta HTTP header 原封不动地转发给 Bedrock 端点，结果当然是被忽略了，功能默默地没开。不报错，就是不生效。平台 beta 传递方式 直接 API HTTP header anthropic-betaAzure (Foundry) HTTP header anthropic-betaVertex rawPredict HTTP header anthropic-betaBedrock Converse body additionalModelRequestFields.anthropic_betaBedrock InvokeModel body 顶层 anthropic_betaanthropic_beta。做网关的人如果想同时代理四个平台，这是第一个要处理的分歧。动态工具加载：同一能力，两个 header
advanced-tool-use-2025-11-20：用于直接 API / Foundrytool-search-tool-2025-10-19：用于 Vertex / Bedrockdefer_loading，消息内容里会出现 tool_reference。但同一个功能在不同平台上 header 名字不一样，这种事如果你不看代码，光看文档是未必能发现的。{
"name": "SomeTool",
"input_schema": { "type": "object" },
"defer_loading": true
}{
"type": "tool_reference",
"tool_name": "SomeTool"
}advanced-tool-use 发到 Bedrock 上，或者把 tool-search-tool 发到直接 API 上，大概率会收到 invalid beta flag。agentic query。querySource，都会被当成 agentic query：repl_main_thread*agent:*sdkhook_agentverification_agentClaude Code 里的全部 Beta Header
协议身份与模式标识
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 的专用 headerfiles-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 后端接口上可用。总结
invalid beta flag。files-api、mcp-servers、ccr-byoc、ccr-triggers 这些非推理链路的 header，走的是 Anthropic 自己的后端接口。Foundry 因为是代理到 Anthropic 基础设施，Files API 是支持的；Bedrock 和 Vertex 上根本不存在对应的端点。
