Claude Opus 5.5 迁移：5个必现400错误的设置

Claude Opus 5.5 和 Sonnet 5.5 的发布带来了性能提升，但也给开发者埋下了不少"只改模型名"就会触发的陷阱。根据官方迁移指南和实际API复现，有五个设置在升级时会直接返回 HTTP 400 错误。如果你打算从 Opus 5 或 Sonnet 5 平滑迁移，这些坑必须提前避开。

陷阱一：thinking 设置不再支持 disabled

Opus 5.5 无法关闭思考功能。在 Opus 5 上，你可以在 high 及以下 effort 级别发送 {"type": "disabled"}，但 Opus 5.5 在所有 effort 级别都拒绝 disabled 和 enabled + budget_tokens 组合。API 会明确报错："thinking.type.disabled" is not supported for this model.

解决方案是省略 thinking 参数（等同于 adaptive 模式），并通过降低 output_config.effort 来间接控制思考深度。

Sonnet 5.5 的处理方式不同：它用 between_tools 替代了 disabled。这是最低级别的思考设置——模型不在响应前思考，只在工具调用之间输出简短注释。但 between_tools 仅在 high 及以下 effort 有效，与 xhigh/max 搭配会返回 400，且不能与其他字段组合使用。

**什么是 effort 与 thinking 的关系？** 在 Anthropic 的 API 里，`output_config.effort` 是一个从 `low` 到 `max` 的分级旋钮，用来告知模型在回答前愿意投入多少内部推理预算；而 `thinking` 参数则控制是否启用扩展思考模式、以及思考内容的处理方式。两者并非彼此独立：effort 决定了思考的“深度上限”，thinking.type 决定思考“是否开启、如何展示”。当新模型不再允许显式关闭思考时，开发者能做的就是从 effort 侧间接调控——调低 effort 等价于让模型少想、快点给出答案，调高 effort 则允许它展开更长的推理链。理解这一映射关系，是读懂后续所有 thinking 相关 400 报错的前提。
# Sonnet 5.5 正确写法
client.messages.create(model="claude-sonnet-5-5", max_tokens=16000,
                       thinking={"type": "between_tools"}, output_config={"effort": "high"}, messages=[...])

注意：不含工具的请求使用 between_tools 时模型完全不思考，多步推理任务应切回 adaptive。

陷阱二：强制 tool_choice 被废弃

{"type": "any"} 和 {"type": "tool", "name": ...} 在两个新模型上都被拒绝，包括 token 计数端点。错误信息为：tool_choice: type "tool" and "any" are not supported for this model.

替代方案是使用 {"type": "auto"}，将工具标记为 strict: true 以确保输入符合 schema，并在提示词中明确何时调用该工具。严格模式工具每次请求上限为20个，且每个对象都需设置 additionalProperties: false。

Bedrock 用户需特别注意：Opus 5.5 和 Sonnet 5.5 在 Amazon Bedrock 上不支持结构化输出（包括严格模式），只能发送 auto，在提示词中指定工具，并自行验证输入。

strict 模式与结构化输出是什么？ 在工具调用场景中，strict: true 表示模型必须严格按照你提供的 JSON Schema 生成工具参数，不允许添加 schema 之外的字段或臆造类型。它相当于把工具输入从“建议格式”升级为“强约束契约”。配合 additionalProperties: false，每个对象都被封闭，模型无法偷偷塞入额外键。之所以在 tool_choice 被限制为 auto 后需要依赖 strict，是因为 auto 意味着模型有权选择不调用工具，此时唯一能保证输出符合预期的手段就是让 schema 本身足够严格。若模型在 auto 下仍决定调用工具，strict 会确保它只使用合法字段；若不调用，则需要靠提示词明确触发条件。

陷阱三：computer_20251124 在多数平台失效

计算机使用工具需要声明为 computer_toolset_20260801 工具集，且不再需要 beta 头。Sonnet 5.5 在所有平台都拒绝 computer_20250124。例外情况是 Amazon Bedrock 保留 computer_20251124。

另外，fine-grained-tool-streaming-2025-05-14 头如果与工具集条目同时出现会返回 400，应该在需要流式传输的工具上设置 eager_input_streaming: true。

陷阱四：编辑对话历史会导致400或丢弃思考

Fable 5.1 引入的保留思考检查现在适用于 Opus 5.5 和 Sonnet 5.5：思考块与模型及对话前缀绑定。如果你编辑了 system、tools 或早期轮次，然后发回思考块，在2026年8月31日或之后创建的账户上会直接返回 400，其他账户则会被静默丢弃。

保持历史记录只追加是核心原则：

• 用对话中的 {"role": "system", ...} 消息改变指令
• 用 tool_addition / tool_removal 改变工具，配合 inline-tools-2026-09-15 beta 可包含完整定义
• 用按需压缩（compact-2026-09-04）缩小历史：你会收到签名摘要块，下次请求时优先发送

Sonnet 5.5 的思考块还绑定账户：从其他组织发送会被静默丢弃。

什么是“保留思考检查”？ 这是 Fable 5.1 引入、如今扩展到 Opus 5.5 和 Sonnet 5.5 的一项安全机制。模型返回的思考块（thinking block）并不是无状态的文本，而是与生成它的模型版本、对话前缀（system、tools、早期轮次内容）做了密码学意义上的绑定。当你把思考块发回 API 时，服务端会重新校验“这段思考是否确实产生于当前这段历史”。一旦你编辑了历史中的任何前置部分，校验失败：新账户直接 400，旧账户则静默丢弃思考块，模型相当于失忆。因此“只追加、不修改”成为硬性设计约束，凡是需要变更指令或工具集的地方，都要改用 system 消息、tool_addition、tool_removal 或压缩摘要等官方机制来绕过前缀改写。

陷阱五：Sonnet 5.5 不接受旧模型作为顾问

Sonnet 5.5 作为执行器时，顾问必须是 Opus 5、Opus 5.5、Sonnet 5.5、Fable 5 / 5.1 或 Mythos 5 / 5.1。Opus 4.8 / 4.7 / 4.6、Sonnet 5、Sonnet 4.6 和 Haiku 5.5 都会返回 400。建议结果以 advisor_redacted_result 加密形式返回。

不会报错但需要关注的变更

除了上述五个硬性错误，还有一些静默变更值得警惕：

Opus 5.5 默认 effort 为 medium（Opus 5 是 high）。如果不带 effort 参数直接迁移，模型会降一级运行。Anthropic 表示 5.5 在 medium 级别可匹配或超越 Opus 5 在 high 级别的表现。

Sonnet 5.5 的 effort 级别重新校准：编码代理从 medium 起步，通用工作用 high，max_tokens 建议128K并开启流式。

工具调用间的文本现在以 thinking 块形式返回，默认 display 下为空。流式显示进度注释的 UI 会静默失效，需要使用 display: "updates"（beta 头 thinking-display-updates-2026-08-18）。

拒绝类别扩展：Opus 5.5 新增 bio；Sonnet 5.5 包含 cyber、bio、frontier_llm、reasoning_extraction、general_harms。自9月24日起，在输出前被拒绝的 bio / frontier_llm / reasoning_extraction 请求会计费。

提示缓存最低要求512 tokens（Sonnet 5 是1024）。Sonnet 5.5 缓存读取价格在10月7日降至 $0.10/MTok。

Priority Tier 在 Opus 5.5 上不支持。Sonnet 4.5 将于2026年11月30日退役，由 Sonnet 5.5 替代。

迁移建议

从 4.x 迁移到 Opus 5 / Sonnet 5 时已经踩过的七个坑（temperature、budget_tokens、prefill、max_tokens 被思考消耗、拒绝时的 content[0]、空思考文本、约30%的 tokenizer 增长）仍然适用。

作者提供了一个开源静态扫描工具 claude5-migration-kit，可以定位代码中这些问题的具体位置：

python scan.py path/to/your/app --target opus-5-5

对于需要完整迁移清单的团队，还有一份70页的PDF指南涵盖各模型检查表、提示词重调表、缓存和历史设计及验证脚本。

迁移的核心教训很简单：只改模型名是不够的。每个版本迭代都在调整API契约，理解这些变更背后的设计意图，比机械替换字符串更能保证系统稳定。