迁移到 Claude Opus 5.5

有关行为差异和特定于模型的提示模式，请参阅为 Claude Opus 5.5 编写提示。

Claude Opus 5.5 的价格低于 Claude Opus 5（每百万输入/输出令牌 4 美元 / 20 美元，而 Claude Opus 5 为 5 美元 / 25 美元；请参阅 Claude 定价），并保留了 Claude Opus 5 的 1M 令牌"context window"（上下文窗口）和 128k 最大输出令牌。对于已在 Claude Opus 5 上运行的代码，共有四项"breaking changes"（破坏性变更），详见破坏性变更。有关功能支持，请参阅 Claude Opus 5.5 的新功能。

从 Claude Opus 5 迁移到 Claude Opus 5.5

更新模型名称

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 是一个不带日期后缀的固定模型 ID，与 claude-opus-5 采用相同的命名方案。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 和 Microsoft Foundry 上，请使用该平台的模型 ID；请参阅可用性。

破坏性变更

每项变更的说明见 Claude Opus 5.5 的新功能；本节给出每项变更对应的代码修改。

无法禁用思考

thinking: {"type": "disabled"} 和 thinking: {"type": "enabled", "budget_tokens": N} 都会返回 400 错误（"thinking.type.disabled" is not supported for this model. 或 "thinking.type.enabled" is not supported for this model.）。请移除 thinking 字段并选择一个 effort（努力程度）级别；如果您之前禁用思考是为了节省令牌，请使用较低的级别。此后响应会以 thinking 块开头，因此请按 type 选择内容块，并在返回工具结果时原样传回 thinking 块。请参阅无法禁用思考。

之前（在 Claude Opus 5 上被接受，在 Claude Opus 5.5 上被拒绝）：

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

之后：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

不支持强制工具使用

tool_choice 类型 any 和 tool 会返回 400 错误（tool_choice: type "tool" and "any" are not supported for this model.），在令牌计数端点上也是如此。请使用 auto 配合严格工具使用或结构化输出，并在提示中说明何时适用该工具。请参阅不支持强制工具使用。

之前：

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

之后：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # strict tool use（严格工具使用）：每次调用都符合该工具的 input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

思考块与模型和对话绑定

在 Claude API 上，Claude Fable 5.1 和 Claude Mythos 5.1 可以读取 Claude Opus 5.5 的思考块；其他模型都不能。如果路由器或回退机制将对话从 Claude Opus 5.5 转移到任何其他模型，这些轮次将在没有这些思考块的情况下运行。反过来，Claude Opus 5.5 可以读取来自 Claude Opus 5 及更早的 Opus、Sonnet 和 Haiku 模型的思考块，但不能读取来自 Claude Fable 或 Claude Mythos 模型的思考块。请保持对话仅追加（不在对话中途编辑 system 提示、tools 或之前的消息），以使这些块保持有效；Claude Code、claude.ai、Claude Managed Agents 和 Claude Agent SDK 已经这样做了。在所有平台上，强制执行方式与 Claude Fable 5.1 相同：对于在 2026 年 8 月 31 日 00:00 UTC 或之后创建的账户，在此类编辑之后重放思考块默认会返回 400 错误。仅追加的集成无需修改代码。请参阅思考块与模型和对话绑定和保留思考。

Claude API 和 Google Cloud 上不支持 computer_20251124 计算机使用工具

在 Claude API 和 Google Cloud 上，类型为 computer_20251124 的 tools 条目会返回 400 错误（'claude-opus-5-5' does not support tool types: computer_20251124.，后面列出该模型接受的工具类型）。请改为声明 computer_toolset_20260801 工具集：去掉 beta 标头，并在发送条目时不带 name 或显示尺寸。在您的智能体循环中，处理成员 tool_use 块（操作是块的 name，而不是 input.action），每轮可能有多个此类块，并在每个结果中回传 toolset_name。请求的更改如下所示；智能体循环的更改列在从 computer_20251124 迁移中。在 Amazon Bedrock 上，早期的 computer_20251124 工具在 Claude Opus 5.5 上仍可正常使用，与在 Claude Opus 5 上一样，因此无需更改；对于其他平台，请参阅计算机使用工具的兼容性部分。请参阅Claude API 和 Google Cloud 上不支持 computer_20251124 计算机使用工具。

之前：

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

之后：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # 无需 beta 标头；该工具集条目不接受名称或显示尺寸
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

工具调用之间的文本在思考块中返回

在 Claude Opus 5 上，模型在工具调用之间编写的文本以 text 块的形式返回。在 Claude Opus 5.5 上，与 Claude Fable 5.1 一样，这些叙述以进度更新 thinking 块的形式返回，每次工具调用之前最多一个。在默认的 thinking.display 值 "omitted" 下，它们的 thinking 字段为空。请求不会失败，但如果应用程序将这些文本作为进度更新流式传输给用户，那么在工具调用之间将不再显示任何内容。要恢复这些更新，请从 thinking 块中读取它们，并设置一个会返回其文本的 display 值："updates"（beta，需要 thinking-display-updates-2026-08-18 标头）会返回进度更新，同时保持推理内容隐藏；"summarized" 则会同时返回两者，且混合在一起。然后，在紧跟于每个非空 thinking 块之后的 tool_use 块之前渲染该 thinking 块，并将这些块与助手轮次的其余部分一起原样传回。请参阅面向用户的进度更新。

安全分类器和回退

Claude Opus 5.5 可能会返回带有 stop_details 类别的 stop_reason: "refusal"。它的分类器涵盖的类别比 Claude Opus 5 更广，因此除了 "cyber" 之外，还可能出现 "bio" 和 "reasoning_extraction" 等 stop_details.category 值；请参阅拒绝类别表。请处理拒绝情况，并配置服务器端回退或您自己的重试机制（服务器端回退不会重试因 "reasoning_extraction" 而被拒绝的请求；该拒绝会直接返回给您）；请参阅拒绝与回退和安全防护拒绝。

建议的更改

1. 重新进行 effort 级别对比测试。 Effort 是 Claude Opus 5.5 上唯一的思考控制项，其默认值为 medium，而 Claude Opus 5 的默认值为 high，因此省略 effort 的请求现在会以 medium 运行。在质量能够保持的情况下降低级别，对于要求最高的工作则提高级别。请参阅 Effort。
2. 重新评估特定于模型的提示指令。 针对 Claude Opus 5 行为调整的指令可能不再需要；请参阅为 Claude Opus 5.5 编写提示。如果您之前在禁用思考的情况下运行，另请参阅为禁用思考而编写的提示。
3. 在切换生产流量之前，先在开发环境中进行测试。

迁移检查清单

• 将模型 ID 更新为 claude-opus-5-5。
• 移除 thinking: {"type": "disabled"} 和 thinking: {"type": "enabled", ...}；改为选择一个 effort 级别。
• 显式设置 effort：默认值为 medium，而 Claude Opus 5 的默认值为 high。
• 将 tool_choice 类型 any 和 tool 替换为 auto，并配合严格工具使用或结构化输出。
• 如果您在 Claude API 或 Google Cloud 上使用计算机使用功能，请声明 computer_toolset_20260801（无需 beta 标头）来代替 computer_20251124，并针对该工具集更新您的智能体循环。在 Amazon Bedrock 上，请继续使用 computer_20251124；对于其他平台，请查看计算机使用工具的兼容性部分。
• 如果路由器或回退机制可能将对话从 Claude Opus 5.5 转移到其他模型，请预期该模型将在没有 Claude Opus 5.5 思考块的情况下运行（Claude API 上的 Claude Fable 5.1 和 Claude Mythos 5.1 是例外，会保留这些思考块）。Claude Opus 5.5 本身可以读取来自 Claude Opus 5 及更早的 Opus、Sonnet 和 Haiku 模型的思考内容，但不能读取来自 Claude Fable 或 Claude Mythos 模型的思考内容。
• 按 type 读取内容块，并在工具使用循环中原样传回 thinking 块。
• 如果您的界面会渲染工具调用之间的文本，请设置 display: "updates"（beta）或 "summarized"，并渲染非空的 thinking 块。
• 如果您的代码会在对话中途编辑之前的轮次、system 提示或 tools，请遵循保留思考。
• 处理 stop_reason: "refusal" 并配置回退。
• 在您选择的 effort 级别下重新确定成本和延迟基线。

从 Claude Opus 4.8 迁移到 Claude Opus 5.5

请先完成从 Claude Opus 4.8 迁移到 Claude Opus 5：其中介绍了默认开启思考以及随之而来的响应结构变化。然后应用从 Claude Opus 5 迁移。其中 Claude Opus 5 的第二项破坏性变更（仅在 high 或更低 effort 级别下才能禁用思考）不适用于此：在 Claude Opus 5.5 上完全无法禁用思考。

迁移检查清单

• Claude Opus 4.8 → Claude Opus 5 检查清单中的所有内容，但 thinking: {"type": "disabled"} 不可用。
• Claude Opus 5 → Claude Opus 5.5 检查清单中的所有内容。

从 Claude Opus 4.7 及更早的 Opus 模型迁移到 Claude Opus 5.5

Claude Opus 5 迁移指南介绍了您当前模型与 Claude Opus 5 之间的破坏性变更：采样参数被拒绝、手动扩展思考被拒绝、预填充被移除，以及更新的分词器。请完成该指南中与您的模型对应的部分，将目标设为 claude-opus-5-5 而不是 claude-opus-5，然后应用从 Claude Opus 5 迁移。该指南中提到可以在 high 或更低 effort 级别下禁用思考，但在 Claude Opus 5.5 上无法禁用；该指南中提到现有的 computer_20251124 集成可以继续使用，但在 Claude API 和 Google Cloud 上，这些集成在 Claude Opus 5.5 上无法使用，因为 Claude Opus 5.5 在这些平台上仅接受以 computer_toolset_20260801 工具集形式提供的计算机使用功能（请参阅该破坏性变更）；在 Amazon Bedrock 上，这些集成可以继续使用。

从 Claude Sonnet 5 迁移到 Claude Opus 5.5

请参阅从 Claude Sonnet 5 迁移到 Claude Opus 5，了解升级到更高模型级别时会发生哪些变化，然后应用从 Claude Opus 5 迁移。