Claude Opus 5.5 API 指南：模型 ID、四项破坏性变更，以及悄无声息的第五项

将模型字符串从 claude-opus-5 改为 claude-opus-5-5，你的代码依然能编译，依然能通过类型检查，依然能通过任何勉强算得上是测试套件的东西。然后它在生产环境里返回 400。Claude Opus 5 接受的四种请求形态被 Claude Opus 5.5 直接拒绝，而第五处变更完全不会破坏任何东西——这正是为什么它最终会成为那个触达你用户的变更。这是该模型的集成参考：标识符、为其提供服务的各个接口面、请求契约、那四个错误、沉默的第五个，以及 effort 参数如今的工作方式。在行为与 Claude Fable 5.1 一致的地方，已经迁移到该模型的团队已经完成了部分工作，因此下面的每处变更都会说明它是否同样适用于该模型。

此处的全部内容均于 2026-09-24 取自 Anthropic 自家的 Claude 文档，也就是该模型发布两天后。厂商说法均标注为厂商说法，独立数据均标注为独立数据，并且绝不会在同一 effort 设置下将二者呈现得仿佛它们可以相互比较。

模型 ID，以及它的服务位置

标识符是claude-opus-5-5——一个不带日期后缀的固定模型 id，与claude-opus-5采用相同的命名方案。既没有单独的固定快照形式可供采用，也没有会解析为其他内容的别名。

Anthropic 的模型概览列出了五个界面，并附有以下确切字符串：

• Claude API — claude-opus-5-5，面向所有客户开放。

• Amazon Bedrock —— anthropic.claude-opus-5-5（唯一会在前面加上供应商名称的界面）。

• AWS 上的 Claude 平台 — claude-opus-5-5，使用 Claude API 的 id，而非 Bedrock 风格的 id。

• Google Cloud — claude-opus-5-5。

• Microsoft Foundry — claude-opus-5-5；您发送的是部署名称，而 Foundry 遵循 Claude API 的生命周期时间表。

这五个当中，有两个比本节其余内容更为重要。Amazon Bedrock 和 Google Cloud 各自设定自己的生命周期和停用日期，而且——正如下方的破坏性变更所示——Bedrock 还是唯一一个旧版 computer-use 工具仍然可用的平台。如果你用的是 Bedrock，那么你的迁移路径就和其他人不一样。

现在每个请求都必须满足什么

Anthropic 的迁移指南以列表形式陈述了这一约定，而这份列表足够简短，你可以据此检查自己的客户端。无论你原本使用的是哪个模型，向 claude-opus-5-5 发起的请求都必须：

• 发送时不带 thinking 字段，或者使用 thinking: {"type": "adaptive"} —— 这两者是等效的，因为自适应思考始终处于开启状态。

• 使用 effort控制思考深度，它是唯一能做到这一点的请求参数；全部五个级别均受支持，默认为 medium。

• 使用 tool_choice，取值为 {"type": "auto"}（默认值）或 {"type": "none"}。强制指定工具会被拒绝。

• 省略 temperature、top_p和top_k，或将其保留为默认值。任何其他值都会被拒绝，在本模型上如此，从 Claude Opus 4.7 起的其他所有模型上也是如此。

• 不要以预填充的助手回合结束消息；这一点在 Opus 4.6 及更高版本上就已经被否决了。

将计算机使用声明为 computer_toolset_20260801工具集，适用于 Claude API 和 Google Cloud。

• 不发送上下文窗口测试版标头。100 万 token 上下文窗口是默认设置，为旧版模型编写的标头不会产生任何效果。

如果指南中说某个设置会被拒绝，那么 API 就会返回 HTTP 400。这就是迁移到这一模型的全部失败模式：不是输出质量下降，也不是日志里的一条警告——而是一个永远不会执行的请求。

四项破坏性变更

1. 思考无法被禁用

自适应思考始终开启。thinking: {"type": "disabled"}会返回 400，手动指定预算也是如此——thinking: {"type": "enabled", "budget_tokens": N}。错误文本会指出你发送的类型，然后指出应替换为的类型：

• 此模型不支持"thinking.type.disabled"。请使用"thinking.type.adaptive"和"output_config.effort"来控制思考行为。

• 此模型不支持“thinking.type.enabled”。请使用“thinking.type.adaptive”和“output_config.effort”来控制思考行为。

实际的后果并不在于错误本身，而在于你修复它之后会发生什么。在 Claude Opus 4.8 及更早版本中，不带 thinking 字段的请求不会进行思考。在 Claude Opus 5.5 上，每个请求都会思考，而 max_tokens 仍然是涵盖思考加回复文本的硬性上限。即使思考文本从未返回给你，思考 token 也按输出 token 计费。因此，一个此前在不思考的情况下运行的端点，在“修复”之后每次请求可能比之前产生更多输出 token。Anthropic 的建议是：在你过去用于禁用思考的地方降低 effort，并且——在 xhigh 或 max effort 下——将 max_tokens 的起始值设为 64k，再以此为基础进行调优。

响应的结构也发生了变化。响应可能在第一个文本块之前以一个或多个思考块开头，因此按位置读取回复的代码——content[0].text，或是将第一个 content_block_start 当作文本处理的流式处理器——在这类响应上都会出错，即使请求已经成功。请改为根据其 type 字段来选择块。

2. 强制工具使用会返回错误

tool_choice 类型 any 和 tool 会返回 400，同样的校验也适用于 token 计数端点，因此预检计数会以与真实调用相同的方式失败：

• tool_choice：此模型不支持类型 "tool" 和 "any"。

Auto 和 none 不受影响。文档记录的替代方案是保留 tool_choice: {"type": "auto"}，为工具标记 strict: true 以获得符合 schema 的参数，或者将 schema 移到结构化输出——并且在提示中说明工具何时适用，因为 auto 并不保证调用。严格工具使用接受 JSON Schema 的一个子集：工具的 input_schema 中的每个对象都必须设置 additionalProperties: false，因此在翻转该标志之前检查每个 schema。还要注意这留下的缺口：如果你的代码依赖的是 强制 调用而非仅仅允许调用，那么 auto 恢复的是许可，而不是保证。检查是否真的返回了 tool_use 块。

3. 思考块与模型和对话绑定

每个思考块都会记录是由哪个模型生成的，而每个模型都会读取自己的块以及一组已定义的其他模型的块。这些规则双向生效：

• Claude Opus 5.5 可读取 Claude Opus 5 以及更早的 Opus、Sonnet 和 Haiku 模型的思考块——但无法读取 Claude Fable 或 Claude Mythos 模型的。

• 在 Claude API 上，Claude Fable 5.1 和 Claude Mythos 5.1 会读取 Claude Opus 5.5 区块。其他模型都不会。

• 当对话从 Claude Opus 5.5 转移到除这两者之外的任何模型时，其后续轮次将在没有先前推理内容的情况下运行。

通过路由器或回退机制来迁移对话，是触发这一点的显而易见的方式。更微妙的一半在于，该块还绑定到对话前缀——系统提示、工具以及它之前的每一条消息。对于在 2026-08-31 00:00 UTC 或之后创建的账户，Anthropic 在 Claude API 和云平台上默认强制执行前缀检查：在编辑系统提示、工具列表或更早的消息后重放一个块，请求就会返回 400。存在两种逃生通道。发送 thinking-binding-controls-2026-08-01 beta 标头，并将 thinking.block_binding.prefix_mismatch_behavior 设置为 "drop_block"，以丢弃受影响的块，而不是让请求失败。或者保持对话为仅追加模式，并通过对话中途的系统消息而不是编辑来更改指令——这也正是 Claude Code、claude.ai、Claude Managed Agents 和 Claude Agent SDK 已经采用的做法。

有一条好消息很容易被忽略：当请求携带了目标模型无法读取的块时，API 会在模型看到它之前将其丢弃。请求会成功，而被丢弃的块不会计费。

4. 较旧的 computer-use 工具在 Claude API 和 Google Cloud 上被拒绝

类型为 computer_20251124 的工具条目在 Claude API 和 Google Cloud 上会返回 400。该消息会指出被拒绝的类型，然后列出该模型确实接受的类型：

• 'claude-opus-5-5' 不支持工具类型：computer_20251124。

替代方案是 computer_toolset_20260801 工具集：移除 computer-use-2025-11-24 beta 标头，并在发送 tools 条目时不带名称、也不带显示尺寸。这不仅是请求层面的变更——智能体循环也随之改变。动作以成员 tool_use 块的形式到达，而不是单个 computer 工具；一轮中可能有多个，动作是该块的 name，而不是 input.action，并且每个结果都必须把 toolset_name 回传回来。在 Amazon Bedrock 上，computer_20251124 的工作方式与在 Claude Opus 5 上完全相同，无需任何更改。

这四项中哪些也适用于 Claude Fable 5.1

Anthropic 表示，前三点在 Claude Fable 5.1 上也适用——始终开启的思考、无强制工具选择，以及与模型和对话绑定的思考块。computer-use 变更则不适用：那一项特定于 Claude API 和 Google Cloud 上的此模型。因此，已经迁移到 Claude Fable 5.1 的团队已弃用其禁用思考的代码路径和强制工具选择，并采用了仅追加式对话模式；剩下的就是模型 ID 和 computer-use 工具集。一个来自 Claude Opus 5 的团队要同时面对全部四项。这才是值得排期的迁移，而且根据你从哪里开始，工作量也不同。

第五个变化：没有任何错误，你的进度动态也安静了下来

在 Claude Opus 5 上，模型在工具调用之间写下的简短说明会以普通文本块的形式返回。而在 Claude Opus 5.5 上——与 Claude Fable 5.1 一样——这些叙述会以进度更新思考块的形式返回，每次工具调用前最多一个。thinking.display 默认为 "omitted"，因此这些块到达时会带有空的 thinking 字段，同时附带其签名。

没有任何请求失败。没有记录任何错误。一个将工具间文本作为进度指示器流式传输给用户的应用，会干脆停止在工具调用之间显示进度，并开始什么都不显示。可见的症状是，在用户最需要得到确认的那段工作期间，界面看起来像冻结了，而它会被报告为性能问题、网络问题或卡死——而不是迁移缺陷。这就是会发布到生产环境的变更。

修复方法是一个显示设置，外加一个与之匹配的读取：

• 将 thinking.display 设为 "updates"——测试版，需启用 thinking-display-updates-2026-08-18 标头——即可恢复进度更新，而推理本身仍保持隐藏。这正是进度信息流所需的设置。

• 或者将其设置为 "summarized"，即可在同一批块中同时接收进度更新和推理摘要。

• 然后从 thinking 块而不是 text 块中读取文本，将每个非空 thinking 块渲染在随后出现的 tool_use 块之前，并将这些块与 assistant 回合的其余部分一起原样传回。

Anthropic 自己对此的说明，在精神上值得引用：在工具调用之间渲染文本的界面，应当设置一个显示值，而不是依赖默认值。如果你的集成目前完全忽略 thinking 块，那正是默认值唯一安全的地方。

投入的努力就是 API 界面。

在思维无法禁用的情况下，output_config.effort成为控制模型推理量的唯一旋钮，因此也是特定任务下控制成本和延迟的唯一旋钮。在从旧模型复制设置之前，有四点值得了解。

默认值变了。Claude Opus 5.5 默认采用 medium effort，而 Claude Opus 5 及更早的 Opus 模型默认采用 high。如今省略 effort 的请求，会比切换前低一个层级运行。Anthropic 还说明，在给定的 effort 设置下，该模型每轮倾向于比 Claude Opus 5 思考更多，在 xhigh 和 max 下尤为明显。这两种效应方向相反，这正是厂商要求你在自己的评测上重新跑一轮 effort 扫描、而不是直接照搬某个设置的原因所在。

该量表为 low / medium / high / xhigh / max，此处五种全部支持。首先，命名级别本身并不是固定的 token 预算——Anthropic 将 effort 描述为一种行为信号，而非严格的预算——而且每个级别背后的 token 分配在不同模型之间有所变化，因此 Claude Opus 5.5 上的“high”并不等于 Claude Opus 5 上的“high”。将 effort 设为模型的默认值，与省略该设置完全相同。

有两个运维细节，因为一旦忽略它们都会造成成本。首先，在请求之间更改顶层 effort 值会使提示缓存失效：请选定一个级别，并在依赖缓存命中的对话中保持不变，而在不同工作负载之间再调整它。其次，该模型支持 按消息设置的 effort（beta 标头 mid-conversation-output-config-2026-07-01），可在不重启缓存的情况下从后续轮次更改该级别。这里的提示缓存最低为 512 个 token，低于上一代的 1,024，因此此前因太短而无法缓存的提示，现在无需改动代码就能创建缓存条目。

输出上限：128K 同步，300K（Batch）

同步 Messages API 的输出上限为 128K 个 token。Message Batches API 则可达到 300K 个输出 token，需使用 output-300k-2026-03-24 beta 标头——就是该确切字符串。默认情况下，输入为完整的 1M token 上下文窗口，无需任何标头。

实际解读：128K 上限与 Claude Opus 5 相比没有变化，因此同步集成没有任何部分需要仅因这一维度而重新调整预算。真正需要重新调整预算的是其中的 thinking。由于现在每次请求的 max_tokens 都涵盖 thinking 加文本，在 Claude Opus 5 上对响应文本刚好够用的值，在这里会更紧张——而在 xhigh 或 max effort 下，厂商建议从 64k 开始并逐步调优。如果一个长时间运行的任务原本是按 128K 同步上限来设定规模的，而现在被截断，那么发生变化的并不是这个上限。

安全防护路由是规范的一部分

这是一个集成事实，而非政策脚注：在某些提示词下，你发送的模型字符串并不描述实际作答的内容。

Claude Opus 5.5 内置了安全分类器，被拒绝的请求会以 HTTP 200 返回，并带有 stop_reason: "refusal"，以及一个stop_details对象，其中标明了策略领域。该模型覆盖的类别比 Claude Opus 5 更多——预计会出现 bio、frontier_llm和 reasoning_extraction，以及熟悉的 cyber。reasoning_extraction 拒绝会被直接拦截，而不会重试：Anthropic 的服务端回退不会重试它，该拒绝会返回给你。

对于确实会重试的类别，其机制是一个参数。请将 fallbacks 设置为 "default"，并配合 server-side-fallback-2026-07-01 测试版标头，API 便会在单次调用内，用 Anthropic 针对该类别推荐的模型重新执行被拒绝的请求，并返回单个响应。Anthropic 的帮助中心直接列出了该模型的路由方式：被标记的网络安全请求会回退到 Claude Opus 4.8，而它的生物学分类器——即 Fable-5 风格的那一套——会让两用生命科学工作回退到 Claude Opus 5。还有一小部分前沿 LLM 开发能力同样会路由到 Claude Opus 5。Anthropic 还指出，这些检查会审查模型读取的所有内容，而不只是你最新的一条消息，因此记忆、连接器内容、搜索结果和文件都可能触发切换。

对你的集成而言，有三点需要注意。在每次响应中读取顶层的 model 字段，因为它报告的是实际生成该消息的模型，而 fallback 内容块会标记每一个交接点。请验证回退机制自身的速率限制，因为受到速率限制的回退不会被尝试，而是直接返回拒绝——在高负载下，回退会退化为拒绝。此外，任何启用了防护措施而发布的基准测试结果，都应视为对路由后系统的测量，而非仅仅对 Claude Opus 5.5 的测量——这正是 Anthropic 在下面关于其自身数据的说法。

服务器端回退目前为测试版，且仅适用于 Claude API：Message Batches API 不支持该功能，Amazon Bedrock、Google Cloud 或 Microsoft Foundry 也不提供，而在这些平台上，SDK 中间件反而是文档记录的路径。在验证方面，两类均设有访问途径——Cyber Verification Program 和 Life Sciences Verification Program——但请注意，截至本文撰写时 Anthropic 帮助中心所记录的不对称性：Claude Opus 5.5 目前未列入 Cyber Verification Program，而生命科学项目则被描述为让经过验证的组织能够访问最强大的模型。

上下文、截止时间、停用和快速模式

信封的其余部分,来自模型页面和弃用表:

• 上下文窗口 — 100 万 token，默认，无需 beta 标头。

• 知识截止日期——2026年6月，这也是训练数据的截止时间。

• 退役 — 在 Anthropic 运营的平台上，最早不早于 2027-09-22，并会至少提前 60 天通知。Amazon Bedrock 和 Google Cloud 各自设定其日期。Claude Opus 5 至少在 2027-07-24 之前保持活跃状态，因此不存在强制切换。

• 费率表 — 每百万输入 $4.00，每百万输出 $20.00，每百万 5 分钟缓存写入 $5.00，每百万 1 小时缓存写入 $8.00，每百万缓存读取 $0.20。批处理在输入和输出两个方向均为半价，分别为 $2.00 / $10.00。

• 缓存读取是值得注意的异类：$0.20 为基础输入价格的 5%，而大多数 Claude 模型为 10%，Claude Fable 5.1 则为 2.5%。对于缓存复用率高的混合负载而言，这是实实在在的折扣。

• 快速模式 — 目前仍被标注为研究预览版，仅限 Claude API，单独定价，每百万输入 $8.00 / 每百万输出 $40.00。启用方式：speed: "fast" 以及 fast-mode-2026-02-01 测试版标头。该模式在 Bedrock、AWS 上的 Claude Platform、Google Cloud 或 Microsoft Foundry 上均不可用，也无法与 Batch API 一起使用，也无法与 Priority Tier 承诺一起使用。请注意，Claude Opus 5.5 完全不支持 Priority Tier。

基准测试说明了什么，以及在哪种设置下

工作量设置是供应商表格与独立表格无法逐行比较的原因，也是下文每个数字都标有其设置的原因。

厂商报告，基于 Anthropic 自家测试框架。 Anthropic 的发布说明指出，除非另有说明，所有 Claude Opus 5.5 的结果均在 max effort 下使用自适应思考（adaptive thinking）；例外是 Terminal-Bench 4.0，Claude Opus 5.5 报告为 xhigh，GPT-6 Astra 报告为 high，因为那分别是各模型的最高得分。在此基础上，厂商报告 Terminal-Bench 4.0 为 66.4%，FrontierCode v1.1 Main 为 54.4%，CursorBench 4.0 为 57.8%，GDPval-AA v2.1 为 1,846 Elo，AutomationBench 为 40.0%，Humanity's Last Exam（带工具）为 67.7%，Terminal-Bench-Science 0.1 为 58.7%，OSWorld 2.0 为 81.8%（部分），Chartography（带工具）为 89.0%。在该模型的默认 medium effort 下，厂商给出 FrontierCode 为 54.6%，CursorBench 为 52.5%。请注意同一份说明所披露的内容：这些评测在启用生产防护措施的情况下运行，而当这些防护措施被触发时，网络安全任务由 Claude Opus 4.8 完成，生物学和前沿 LLM 开发任务则由 Claude Opus 5 完成——Anthropic 表示，这很可能降低了 Claude Opus 5.5 在这些基准上的表现。因此，受影响评测上公布的分数并非对该模型的纯净测量。

独立评测，Artificial Analysis。在 Intelligence Index v4.3.2 上，Claude Opus 5.5 得分为58，即 Artificial Analysis 标注为“Adaptive Reasoning, Max Effort, Default Fallback”的配置——这是其测得的最高分，高出数分，并在十项组成评测中的六项上领先。在同一指数、同一套测试框架下，Claude Fable 5.1 得分为 53，Claude Opus 5 得分为 51。Artificial Analysis 公布了完整的 effort 阶梯，这是此处最有用的独立材料：max 58、xhigh 56、high 54、medium 51、low 42。其自身测量显示，在 max effort 下，Claude Opus 5.5 每个 index 任务约需 119,000 个输出 token，相比之下 Claude Opus 5 约为 73,000，Claude Fable 5.1 约为 78,000，GPT-6 Astra 为 27,000——这些 token 均按输出 token 计费——其页面报告每个 index 任务成本为 5.98 美元。它还测得 Terminal-Bench 4.0 为 59.6%、Humanity's Last Exam 为 61.4%，而厂商在不同测试框架、max effort 下报告的分别为 66.4% 和 67.7%。

把这两段对照起来读，诚实的结论其实很有限。厂商的 66.4% Terminal-Bench 和独立测得的 59.6% 是同一项基准测试，由不同的人在不同、且无法保证一致的设置下运行，两者都不能作为你自身工作负载的证据。真正可迁移的发现是努力程度阶梯：在一个独立指数上，这个模型自身不同设置之间的跨度达十六个百分点，比它与前代之间的差距还要大。选择努力程度比在这些模型之间做选择更重要，而那个标签里的 "Default Fallback" 条款是上文所述的保障性路由，而非基准测试的产物。

供应商报告的效率数据，来源已注明。Anthropic 表示，Claude Opus 5.5 在大多数工作上达到 Claude Fable 5.1 的水平，而运行成本降低约 40%；在标价下调 20% 的情况下，典型工作负载的成本比使用 Claude Opus 5 低约 40%。输出速度提升超过 30%。这些都是供应商对其自行选定工作负载平均值的描述。发布时的客户陈述属于同一类证据：Box 报告 token 用量降至三分之一，回答冗长度降低约 40%；Kiro 报告 token 用量约为一半，调用次数减少约 40%；Factory 报告输出 token 减少 20–25%；GitHub 则表示这是其测得的 token 和步骤数最少的之一。Anthropic 还报告了一项内部事实核查测试，其中 18 份报告有 16 份通过了质量门槛，而 Claude Fable 5.1 和 Claude Opus 5 在任何一次尝试中都未能达到该门槛。所有这些均为供应商报告，且均未经审计。其披露的局限异常坦诚，值得留意：Anthropic 表示 Claude Opus 5.5“常常怀疑自己正在被评估”。

最后是同期推出的兄弟型号：Anthropic 称 Claude Sonnet 5.5 和 Claude Haiku 5.5 将于"未来几周内"登场。这两款模型均未发布，均未定价，目前也均未登陆任何平台。

在不全面切换的情况下测试四项更改

这里的迁移风险不是质量——而是某条你在预发环境中从未跑过的代码路径，恰恰就是在生产环境返回 400 的那一条。这四个破坏性变更全都是请求结构层面的变更，这意味着它们会确定性地、立即失败，而找出你遗漏的那些路径的唯一办法，就是让真实流量跑过它们。

Claude Opus 5.5 已在 OrcaRouter 上线，型号为 anthropic/claude-opus-5.5，采用 Anthropic 官方标价，0% 加价——供应商标价直接透传，因此厂商调价当天此处即同步生效。

这样一来，你可以将一定比例的生产流量指向该模型，其余流量仍由 Claude Opus 5 处理，观察哪些请求失败、原因是什么，并逐一修复。这四个错误本身就说清了问题：每个错误都会指出它拒绝的参数，其中三个还会给出替代方案。当一个路径仍然有问题时，自动故障转移可以填补空缺——对于那些尚未充分表征的模型，失败的请求会回退到你已充分表征的模型，而不是把 400 直接抛给用户。

实际的工作顺序：先替换模型 id 并显式设置 effort，因为默认值已改为 medium；接着移除 thinking-disabled 和强制工具选择这两条路径；然后修复流式读取器——按类型进行块选择以及 thinking.display 设置——因为它属于静默失败而非大张旗鼓报错的那一类；如果你用的是 Bedrock，就把 computer-use 工具集的迁移留到最后，因为它在那里并不适用。其余的一切——价格、上下文窗口、缓存费率以及 1M token 默认值——都还停留在你离开时的样子。

将一部分实时流量路由至新模型，而无需完全切换：OrcaRouter 上的 Claude Opus 5.5按 Anthropic 的标价运行，并可自动故障转移到你已充分评估过的模型。