症状：把旧模型的 model 改成 claude-opus-5-5 后，请求开始出现 thinking、工具调用或上下文恢复异常。
最快解法：不要直接全量替换，先冻结旧模型基线，复核 thinking 与完整 block 回传，再让低风险请求双轨运行；涉及工具执行和长期会话的生产 Agent，完成同条件回归后再放行。
这篇文章适合三类人：正在检查 Messages API 兼容性的 Claude API 开发者；需要处理 thinking block、工具调用和模型回退的 Agent 平台工程师；希望在 2026 年 9 月热点窗口完成低风险试点、但不能丢掉旧模型回退路径的 AI 创业团队技术负责人。
最后更新于 2026 年 9 月 23 日，数据核实自 Anthropic 于 2026 年 9 月 22 日发布的 Claude Opus 5.5 说明、Claude Platform 文档、工具调用文档与错误处理文档。
发布边界：新模型不是旧接线的同名替换
Anthropic 已确认 Claude Opus 5.5 于 2026 年 9 月 22 日发布，可通过 Claude Platform 使用，API 模型标识为 claude-opus-5-5。官方同时把它描述为采用 preserved thinking 的模型，并说明这一机制适用于 2026 年 8 月 31 日及以后创建的 API 账号。这些是发布事实，不等于你的 SDK、Agent 编排器或第三方封装已经完成兼容。(anthropic.com)
你需要先把接入路径拆开：
- Claude Platform：直接检查 Messages API、thinking、工具定义、错误响应和模型回退。
- Claude Code：检查它使用的账号、权限、项目上下文、文件系统和执行环境，不能把 Claude Code 的体验直接当成 API 兼容性证明。
- 第三方平台或云服务：单独确认模型是否已经开放、模型 ID 是否经过重写、是否支持完整 thinking block，以及工具结果是否仍按 Anthropic 的消息结构传递。
官方发布页称 Opus 5.5 在多数工作上接近 Claude Fable 5.1，但这只能作为产品定位，不能写成所有业务等价。只读问答、代码解释和工具型 Agent 的失败代价不同，迁移门槛也不应相同。模型生命周期和可用状态还可能变化，正式上线前应查看 Claude Platform 模型状态与弃用说明。
迁移前冻结：先保存旧模型的可复现基线
第一步不是改代码，而是把现有请求冻结成可以重放的样本。至少保存以下内容：
- 当前模型 ID、
max_tokens、thinking、effort和任何旧版预算参数。 - 完整的
tools、input_schema、强制工具选择策略和工具结果格式。 - system prompt、用户消息、上下文拼接顺序，以及是否会压缩历史消息。
- API 响应中的
text、thinking、redacted_thinking、tool_use、stop_reason和 usage 信息。 - 超时、重试、限流、工具拒绝、模型回退与人工接管的处理分支。
测试样本不要只放普通问答，至少建立五组：普通问答、代码修改、工具调用、长上下文、模型回退。每组都要记录输入、输出、调用次数、失败类型和最终交付证据。
这里有一个经常被忽略的隔离原则：模型响应质量、API 请求链路、工具执行器、代码工作区、CI 和云端 Mac 是不同故障域。比如 API 返回成功，但工具没有真正写入文件；或者 Agent 生成了正确补丁，却因为 Xcode、签名或构建环境失败。不要把这些问题统称为“模型迁移失败”。
如果任务最后需要在 macOS 上构建或验收，应该把代码交付和真实执行环境分开记录。你可以先参考 Mac mini 的 AI 本地模型与持续运行评估，但不要用本地硬件测试替代 API 回归。
请求契约：参数变化比模型 ID 更容易制造故障
Claude Opus 5.5 API 迁移时，优先检查四类契约。
第一类是 thinking 配置。 如果旧请求使用 thinking: {"type": "enabled", "budget_tokens": ...}，不能假设新模型继续接受同一组字段。Anthropic 当前迁移文档把较新的模型引向 adaptive thinking，并使用 output_config.effort 控制思考深度；过时的 budget_tokens 在部分新模型上会触发 400 请求错误。(docs.anthropic.com)
第二类是输出结构。 客户端不能只读取 text。如果界面、日志系统或中间件把 thinking、redacted_thinking、tool_use 过滤掉，长任务可能表现为“没有输出”或“卡住”，但实际是渲染层丢失了中间内容。
第三类是预填充回答。 如果旧系统通过 assistant 末尾预填充来强制 JSON、代码块或固定格式，需要单独验证。较新模型可能不再支持原有的 assistant message prefill，继续发送会得到请求错误。(docs.anthropic.com)
第四类是工具选择。 auto、强制指定工具和 none 不应混在一个测试结论里。工具调用响应需要读取 stop_reason、工具名称、工具 ID 和输入对象，再把结果以新的 user 消息和 tool_result block 回传；Anthropic 的工具调用实现并不是把工具结果塞进一个自定义角色就结束。(docs.anthropic.com)
| 检查项 | 旧系统常见做法 | Opus 5.5 迁移动作 | 未通过时的处理 |
|---|---|---|---|
| 模型标识 | 只替换 model 字符串 |
确认 Claude Platform 中的可用 ID 与实际账号权限 | 保留旧模型 |
| thinking | 固定预算或直接关闭 | 检查 adaptive thinking、effort 与默认行为 |
单独建兼容分支 |
| 输出解析 | 只取 text |
保留 thinking、redacted_thinking、tool_use 等 block | 禁止进入生产 |
| 工具结果 | 自定义拼接文本 | 按 tool_use_id 原样匹配 tool_result |
回退到旧模型 |
| 预填充 | assistant 末尾预填 JSON | 验证是否仍支持 prefill | 改用结构化提示或输出校验 |
| 错误处理 | 所有 4xx 都重试 | 区分参数拒绝、工具错误、限流和网络失败 | 仅对可重试错误重试 |
Agent 状态：thinking block 不能当作普通文本改写
Claude Opus 5.5 的 preserved thinking 会影响上下文回传。你不能把历史 assistant 消息重新拼成“看起来一样”的自然语言，也不能只保留可见文本后继续发送。官方错误文档明确说明，最近一轮 assistant 消息里的 thinking 或 redacted_thinking block 如果被编辑、排序、过滤或重建，可能返回 invalid_request_error；使用工具时，这些 block 需要按原样回传，包括内容为空的 block。(docs.anthropic.com)
因此，Agent 平台至少要分开保存四类状态：
- 模型会话历史：包含消息顺序与原始 content blocks。
- Agent 业务状态：任务 ID、阶段、审批状态和人工接管信息。
- 工具执行结果：工具输入、工具 ID、返回值、退出状态和副作用证明。
- 代码工作区：提交、补丁、文件变更、构建产物和测试日志。
不要把“模型总结”作为唯一恢复点。一次工具失败后，如果你只保存了一段摘要，下一次恢复可能缺少原始工具 ID、thinking block 或工作区状态，导致重复执行、错误回滚，甚至把已经完成的外部写入再做一次。
建议在隔离工作区完成三次联调：
- 一次普通成功调用，确认完整响应可以落库并重新发送。
- 一次工具执行失败，确认 Agent 能识别失败类型，而不是把错误文本当作成功结果。
- 一次中断恢复，模拟进程退出、网络断开或人工暂停，确认恢复后不会重复副作用操作。
长任务回归：成功返回不等于真实交付
长任务要验证的不只是最终文本，而是整个执行链。建议按下面顺序操作：
- 选一个旧模型已经稳定完成的代表性任务，固定输入、工具集和工作区。
- 同时发送旧模型与 Opus 5.5 请求，保存响应 block、工具调用次数和停止原因。
- 模拟一次超时，确认重试不会重复创建资源、提交代码或发送外部通知。
- 模拟一次工具拒绝，确认系统不会把安全拒绝当作网络故障继续重试。
- 在中途切换到回退模型，清理不属于新模型的 thinking block，再验证上下文是否仍然有效。
- 让任务进入人工接管，确认人工可以看到输入、执行历史、当前工作区和下一步动作。
- 最后在真实交付环境重新执行，例如独立 Mac、Xcode、签名、桌面工具或 CI 节点。
模型切换尤其容易被忽视。官方文档已经提示，较新的模型会保留既有 thinking 内容，但在切换模型时，应清理不属于新模型的 thinking block。换句话说，回退路径不是简单地把 model 换回旧值，而是要重新建立一条合法的上下文边界。
如果你的 Agent 会调用 MCP、桌面工具或 macOS 构建链，还要单独检查第三方封装是否保留了原始 block。工具定义本身也会进入请求上下文，工具名称、描述、输入结构和返回结果任何一处变化，都可能让“模型质量问题”与“工具契约问题”混在一起。关于工具调用的消息结构，可以对照 Anthropic 工具调用实现文档 与 工具调用概览。
首周双轨：按风险而不是按模型热度放行
首周不建议把所有请求切到 Claude Opus 5.5。你可以采用下面的分流：
- 低风险、只读、可重试：先让 Opus 5.5 承担一部分流量，旧模型保留为即时回退。
- 代码分析和补丁生成：双轨对比输出与测试证据，不只比较回答是否“看起来更好”。
- 外部写入、生产发布、长期工具链：完成中断恢复、重复调用、权限拒绝和人工接管测试后再考虑放量。
- 高价值交付和 macOS 构建：API 请求成功只能说明模型服务正常，必须在独立真实 Mac 环境拿到构建、测试或发布证据。
用这张表形成放行结论：
| 评估维度 | 试点通过 | 需要双轨 | 暂缓迁移 |
|---|---|---|---|
| 完整任务成功率 | 与旧基线接近且证据完整 | 偶发需要人工修正 | 经常中断或无法复现 |
| 工具调用 | ID、输入、结果均能闭环 | 需要额外适配器 | 出现重复副作用或结果错配 |
| 上下文恢复 | 中断后可继续且不重做 | 只能从摘要恢复 | thinking block 经常被破坏 |
| 回退路径 | 可清理上下文并继续 | 需要人工介入 | 切换后任务状态丢失 |
| 真实交付 | CI 或独立 Mac 验收通过 | 仍需环境排查 | API 成功但交付失败 |
评分时，把完整任务成功率、人工返工、工具重试、上下文占用和执行环境等待放在一起看；不要只看单次响应是否返回 200。网络重试、参数拒绝、工具失败和安全拒绝必须分开统计，否则你会把不可重试的问题误判为暂时性故障。
结论只保留三档：迁移，代表低风险与生产回归均通过；双轨，代表 Opus 5.5 可承担明确范围，但旧模型仍是可靠回退；暂缓，代表请求契约、状态恢复或真实交付证据至少有一项不完整。
当前方案与 Mac 方案：交付环境不要被 API 成功掩盖
如果你现在把 Agent 放在开发者本地 Mac、共享 CI 或临时云主机上，常见缺点通常不是模型本身，而是环境不稳定：本地机器会被休眠、网络和权限打断；共享 CI 难以保留完整工作区与桌面状态；临时云环境可能缺少 Xcode、签名、模拟器或真实 macOS 工具链。这样一来，你很难判断失败来自 Claude API、工具执行器，还是交付环境。
对于需要临时验证、短期并发测试或隔离 macOS 构建的团队，租赁 Mac 的价值在于把执行环境单独固定下来，再用日志证明模型调用、工具副作用和最终交付分别发生了什么。你可以先阅读 MacPull 的帮助与控制台入口，再根据任务是否需要长期稳定重负载、物理接口或固定设备决定是否适合租赁；长期高负载且已有成熟运维能力的团队，自购 Mac 可能更合适。
在真正切换前，先保存旧模型基线，再把工具调用排查、thinking block 回传、模型回退和独立 Mac 验收串成一条可重放链路。这样你得到的不是“新模型看起来不错”的印象，而是一份能够说明何时迁移、何时双轨、何时退回旧模型的接入证据。