Claude Platform Docs
模型与定价Claude Opus 5.5

Claude Opus 5.5 迁移指南

通过本迁移指南从早期 Opus 模型或 Claude Sonnet 5 切换到 Claude Opus 5.5。启用 Claude Opus 5.5 的指导内容包括会返回错误的请求设置、每个响应中的思考块，以及针对每个起始模型的检查清单。

Claude Code

让 Claude Code 为您迁移代码

/claude-api migrate 将此项目迁移到 claude-opus-5-5

本页列出了从 Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 及更早的 Opus 模型或 Claude Sonnet 5 迁移到 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.5 的新功能。有关行为差异和特定于模型的提示模式，请参阅提示 Claude Opus 5.5。

每个发往 Claude Opus 5.5 的请求必须满足的要求

无论您从哪个模型迁移而来，发往 claude-opus-5-5 的请求都必须满足以下要求。如果某项说明某个设置会被拒绝，则 API 会返回 400 错误。

  • 模型 ID： 使用 claude-opus-5-5，这是一个不带日期后缀的固定模型 ID。在 Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed)、Claude Models on Google Cloud (Google managed) 和 Microsoft Foundry 上，请使用该平台的模型 ID；请参阅可用性。
  • 思考： 不发送 thinking 字段，或发送 thinking: {"type": "adaptive"}，两者等效：自适应思考始终处于开启状态。thinking: {"type": "disabled"} 和手动思考预算（thinking: {"type": "enabled", "budget_tokens": N}）会被拒绝。请参阅思考的前后对比。
  • Effort： 使用 effort 参数控制思考深度，这是唯一控制思考深度的请求参数。支持全部五个级别（low、medium、high、xhigh、max），默认值为 medium。请参阅 Claude Opus 5.5 的推荐 effort 级别。
  • 工具选择： 使用 tool_choice {"type": "auto"}（默认值）或 {"type": "none"}。使用 {"type": "any"} 或 {"type": "tool", "name": "..."} 强制调用工具会被拒绝。请参阅工具选择的前后对比。
  • 采样参数： 省略 temperature、top_p 和 top_k。请使用提示来引导模型的行为。
  • 预填充： 不要以预填充的助手轮次结束 messages：这会被拒绝。请改用结构化输出或系统提示指令。
  • 计算机使用： 将计算机使用声明为 computer_toolset_20260801 工具集。在 Amazon Bedrock 上，computer_20251124 也可以使用。请参阅计算机使用的破坏性变更。
  • 上下文窗口： 不需要上下文窗口 beta 标头。1M 令牌上下文窗口是默认设置，为旧模型发送的标头不会产生任何效果。

以下请求满足列表中的每一项：设置了 effort，且没有 thinking 字段。在示例打印文本的地方，它按类型查找文本块，因为 thinking 块排在前面。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

处理每个响应中的思考

思考会在每个 Claude Opus 5.5 请求上运行，因此每个响应都可能以 thinking 块开头，并且 max_tokens 涵盖思考和文本。如果您的代码已经在开启思考的情况下运行，那么第 1 到 3 项很可能已经就绪：请检查第 4 和第 5 项。如果您的代码在任何早期模型上都是在不开启思考的情况下运行的，那么每一项都是一项更改。

  1. max_tokens 涵盖思考和文本： 在 Claude Opus 4.8 及更早的 Opus 模型上，没有 thinking 字段的请求在不思考的情况下运行。Claude Opus 5 和 Claude Sonnet 5 接受 thinking: {"type": "disabled"}。在 Claude Opus 5.5 上，每个请求都使用自适应思考运行。max_tokens 仍然是总输出（思考加响应文本）的硬性限制，因此请为之前不开启思考运行的工作负载重新审视它。即使思考文本没有返回给您，思考令牌也会按输出令牌计费，因此此类工作负载每个请求可能会产生更多输出令牌。请参阅成本控制。要减少用于思考的令牌，请降低 effort 级别。如果您以 xhigh 或 max effort 运行，请设置较大的 max_tokens，让模型有空间进行思考和行动；从 64k 令牌开始，并在此基础上调整。如果您的提示是针对不开启思考的运行方式调优的，请参阅为禁用思考编写的提示。

  2. 响应以思考块开头： 响应可能在第一个 text 块之前以一个或多个 thinking 块开头。按位置读取回复的代码（例如 content[0].text，或将第一个 content_block_start 事件视为文本的流处理程序）在这些响应上会出错。请改为按 type 字段选择内容块：从 type 为 "text" 的块中读取 text，并在处理流事件时按块类型进行分支。

  3. 在工具使用循环中原样返回思考块： 如果您运行工具使用循环，在返回工具结果时，请将每个助手响应中的 thinking 块完整且未经修改地传回 API，包括 thinking 字段为空的块。请按接收时的原样回传助手消息，而不是按类型过滤其内容块或重新构建它：API 会以 400 错误拒绝被编辑、重新排序或部分丢弃的思考块。请参阅保留思考块。

  4. 默认省略思考文本： thinking.display 默认为 "omitted"，因此 thinking 块到达时 thinking 字段为空，并附带其 signature。请仅将 thinking 字段视为显示文本。要改为接收可读的摘要，请将 thinking.display 设置为 "summarized"：

    thinking = {
    "type": "adaptive",
    "display": "summarized",
}

    如果您的产品会向用户流式传输推理过程，默认设置会表现为输出开始前的长时间停顿；请设置 display: "summarized" 以在思考期间恢复可见的进度。请参阅控制思考显示。

  5. 工具调用之间的文本以思考块返回： 模型在工具调用之间编写的简短说明以 thinking 块的形式返回，在默认显示设置下这些块为空。请参阅工具调用之间的文本以思考块返回。

按起始模型划分的迁移检查清单

从上往下逐组查看，并在列出您当前模型的那一组之后停止：到该组为止的每一项都适用于您。如果您使用的是 Claude Opus 5，第一组就是完整的清单。如果您使用的是 Claude Sonnet 5，请应用第一组和最后一组。

所有起始模型

  • 将模型 ID 更新为 claude-opus-5-5。
  • 移除 thinking: {"type": "disabled"} 和 thinking: {"type": "enabled", ...}；改为选择一个 effort 级别。
  • 显式设置 effort：默认值为 medium，而 Claude Opus 5 的默认值为 high。
  • 将 tool_choice 类型 any 和 tool 替换为 auto 加上严格工具使用或结构化输出。
  • 如果您使用较早的计算机使用工具版本，请改为声明 computer_toolset_20260801（无需 beta 标头），并针对该工具集更新您的代理循环。在 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 API 和 Claude Models on Google Cloud (Google managed) 上还可以读取来自 Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考，但不能读取来自 Claude Fable 或 Claude Mythos 模型的思考。
  • 按 type 读取内容块，并在工具使用循环中原样传回 thinking 块。
  • 如果您的界面会渲染工具调用之间的文本，请设置 display: "updates"（beta）或 "summarized"，并渲染非空的 thinking 块。
  • 如果您的代码会在对话中途编辑较早的轮次、system 提示或 tools，请遵循保留思考。
  • 处理 stop_reason: "refusal" 并配置回退。
  • 在您选择的 effort 级别下重新建立成本和延迟基线。
  • 如果您的代码曾禁用思考，请重新审视 max_tokens，它涵盖思考和响应文本；在 xhigh 或 max effort 下，从 64k 开始。请参阅在每个响应中处理思考。

Claude Opus 4.8 或更早版本

  • 审查之前在没有 thinking 字段的情况下运行的工作负载：在 Claude Opus 5.5 上，它们会开启思考运行，并且思考无法禁用。重新审视 max_tokens，它仍然是总输出（思考加响应文本）的硬性限制；在您希望减少思考的地方降低 effort。思考令牌按输出令牌计费，因此这些工作负载每个请求可能会产生更多输出令牌。
  • 验证所有解析 thinking 字段的代码都仅将其视为显示文本。设置 display: "summarized" 以接收可读的摘要。
  • 审查接近缓存最小长度的提示：512 个令牌或更多的提示可以创建缓存条目。
  • 如果您的组织有 Priority Tier 承诺，请单独规划容量：Claude Opus 5.5 不支持 Priority Tier。
  • 如果您以 xhigh 或 max effort 运行，请将 max_tokens 提高到至少 64k 作为起点。
  • 对于智能体工作负载，请考虑使用任务预算（beta）和对话中途工具更改（beta）。

Claude Opus 4.7 或更早版本

  • 在您自己的评估上重新进行 effort 扫描，而不是沿用为早期模型调优的设置。
  • 移除所有上下文窗口 beta 标头。
  • 如果您通过重建对话历史来更新指令，请考虑改用对话中途的系统消息，以保留提示缓存命中。
  • 验证您的停止原因处理逻辑在拒绝时会读取 stop_details。
  • 如果您想使用 Claude Opus 4.7 会拒绝的快速模式，请在您的 Claude API 请求上设置 speed: "fast"。Claude Opus 5.5 不需要 beta 标头。

Claude Opus 4.6 或更早版本

  • 从请求负载中移除 temperature、top_p 和 top_k。
  • 将 thinking: {"type": "enabled", "budget_tokens": N} 替换为 thinking: {"type": "adaptive"} 加工作量参数，或完全移除 thinking 字段；自适应思考始终开启。
  • 如果您的 UI 显示思考内容，请显式选择启用思考摘要。
  • 在更新后的分词方式下重新对端到端成本和延迟进行基准测试。
  • 重新调整 max_tokens 以适应更新后的分词方式，包括压缩触发条件。
  • 重新测试所有客户端令牌计数估算。
  • 如果您的应用程序发送图像，请针对高分辨率图像支持重新制定预算（每张全分辨率图像最多约多 3 倍的图像令牌）。如果您不需要额外的保真度，请在发送前降低采样率。
  • 如果您使用模型输出的指点或边界框坐标，请移除所有缩放因子转换；在 Claude Opus 4.7 及更高版本的模型上，坐标与实际图像像素为 1:1 对应。
  • 审查从 Claude Opus 4.7 开始的行为变化。
  • 如果您的产品从事合法的安全工作，请申请加入 Cyber Verification Program，以获得对网络安全内容更宽松的限制。

Claude Opus 4.5 或更早版本

  • 移除所有助手消息预填充；Claude Opus 4.6 已经会拒绝它们。
  • 验证工具调用 JSON 解析使用标准 JSON 解析器。
  • 从 client.beta.messages.create() 迁移到 client.messages.create()：自适应思考和 effort 不需要 beta 命名空间。
  • 移除 effort-2025-11-24 beta 标头（effort 参数不需要它）。
  • 移除 fine-grained-tool-streaming-2025-05-14 beta 标头。
  • 移除 interleaved-thinking-2025-05-14 beta 标头（自适应思考会自动启用交错思考）。
  • 将 output_format 迁移到 output_config.format（如适用）。

Claude 4.1 或更早版本

  • 更新工具版本（text_editor_20250728、code_execution_20260521）。
  • 处理 refusal 停止原因。
  • 处理 model_context_window_exceeded 停止原因。
  • 验证工具字符串参数对尾随换行符的处理。
  • 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19 beta 标头。
  • 按照提示最佳实践审查并更新提示。

仅限 Claude Sonnet 5

  • 如果您通过重建对话历史来更新指令，请考虑改用对话中途的系统消息，以保留提示缓存命中。
  • 审查接近缓存最小长度的提示：512 个令牌或更多的提示可以创建缓存条目。

从 Claude Opus 5 迁移到 Claude Opus 5.5

首先完成每个发往 Claude Opus 5.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、Claude Models on Google Cloud (Anthropic managed)、Claude Models on Google Cloud (Google managed) 和 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 会以 400 错误拒绝它：

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 配合严格工具使用或结构化输出，并在提示中说明何时应使用该工具。严格工具使用接受 JSON Schema 的一个子集，因此在添加 strict: true 之前，请检查每个工具的 input_schema。模式中的每个对象都必须设置 additionalProperties: false；请参阅 JSON Schema 限制。请参阅不支持强制工具使用。

之前。Claude Opus 5 接受此请求，而 Claude Opus 5.5 会以 400 错误拒绝它：

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,
    # 严格工具使用：每次调用都与工具的 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 的 thinking block（思考块）；其他模型均不能。将对话从 Claude Opus 5.5 转移到任何其他模型的路由器或回退机制，在运行这些轮次时将不包含这些思考块。反过来，Claude Opus 5.5 可以读取来自 Claude Opus 5、更早的 Opus、Sonnet 和 Haiku 模型的思考块，并且在 Claude API 和 Claude Models on Google Cloud (Google managed) 上，还可以读取来自 Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考块，但不能读取来自 Claude Fable 或 Claude Mythos 模型的思考块。请保持对话仅追加（在对话中途不编辑 system 提示、tools 或之前的消息），以使这些思考块保持有效；Claude Code、claude.ai、Claude Managed Agents 和 Claude Agent SDK 已经这样做了。对于在 2026 年 8 月 31 日 00:00 UTC 或之后创建的账户，在 Claude API 和云平台上，如果请求在此类编辑之后重放思考块，且未设置 thinking.block_binding.prefix_mismatch_behavior，将收到 400 错误。对于仅追加的集成，无需更改代码。请参阅思考块与模型和对话绑定和保留的思考。

部分计算机使用工具版本不受支持

Claude Opus 5.5 通过 computer_toolset_20260801 工具集支持计算机使用。在 Amazon Bedrock 上，Claude Opus 5.5 还接受带有 computer-use-2025-11-24 beta 标头的 computer_20251124 工具。对于任何不接受的计算机使用工具版本（例如 Claude API 上的 computer_20251124），Claude Opus 5.5 会返回 400 错误。它在任何平台上都不接受 computer_20250124。在 Claude API 上，错误消息以 'claude-opus-5-5' does not support tool types: computer_20251124. 开头，随后列出该模型接受的工具类型。

使用该工具集的集成无需更改。要将 computer_20251124 集成迁移到该工具集，请删除 beta 标头，并发送不带 name 或显示尺寸的 computer_toolset_20260801 条目。在您的代理循环中，处理一个轮次中的每个成员 tool_use 块，并在每个结果中回传 toolset_name。从每个块的 name 读取操作，而不是从 input.action 读取。从 computer_20251124 迁移列出了代理循环的相关变更。

之前。Claude Opus 5 接受此请求，而 Claude Opus 5.5 在 Claude API 上会以 400 错误拒绝它：

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 块之前，并将这些块与助手轮次的其余部分一起原样传回。请参阅面向用户的进度更新。

安全分类器和回退

Claude Opus 5.5 可能会返回带有 stop_details 类别的 stop_reason: "refusal"。它的分类器覆盖的类别范围比 Claude Opus 5 更广，因此除了 "cyber" 和 "reasoning_extraction" 之外，还可能出现 "bio" 等 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. 在切换生产流量之前，在开发环境中进行测试。

从 Claude Opus 4.8 迁移到 Claude Opus 5.5

首先完成每个发往 Claude Opus 5.5 的请求必须满足的要求、处理每个响应中的思考和从 Claude Opus 5 迁移到 Claude Opus 5.5。将 claude-opus-4-8 作为您要替换的模型 ID。最后那一节原样适用于 Claude Opus 4.8 上的代码，因为 Claude Opus 4.8 与 Claude Opus 5 一样：

  • 接受 thinking: {"type": "disabled"}、强制工具选择和 computer_20251124 工具。
  • 以 text 块返回工具调用之间的文本。
  • 默认使用 high effort。

本节补充了 Claude Opus 4.8 与 Claude Opus 5 之间的变化。有关检查清单，请参阅迁移检查清单的前两组。

变化内容

  1. 省略思考的请求也会运行思考： 在 Claude Opus 4.8 上，除非您请求，否则思考是关闭的。在 Claude Opus 5.5 上，没有 thinking 字段的请求会开启思考运行，因此处理每个响应中的思考中的每一项对于此类代码都是一项更改。如果您的代码从未发送过 thinking 字段，那么在思考设置的前后对比下就没有需要移除的内容。

  2. 更低的提示缓存最小长度： Claude Opus 5.5 上可缓存提示的最小长度为 512 个令牌，低于 Claude Opus 4.8 上的 1,024 个令牌。在 Claude Opus 4.8 上因过短而无法缓存的提示现在可以创建缓存条目，无需更改代码。有关各模型的最小长度，请参阅提示缓存。

  3. 不支持 Priority Tier： Claude Opus 5.5 不支持 Priority Tier，而 Claude Opus 4.8 保留了该支持。如果您的组织有 Priority Tier 承诺，请单独规划容量。

这些不是必需的，但会改善您的使用体验：

  1. 考虑任务预算（beta）： 对于智能体工作负载，任务预算会告诉模型在完整的智能体循环中可用的令牌数量。它们需要 task-budgets-2026-03-13 beta 标头。

  2. 考虑对话中途的工具更改（beta）： 对话中途的工具更改允许您在对话的轮次之间添加或移除工具，而不会使早期轮次的提示缓存命中失效。更改 tools 数组本身会使缓存的前缀失效。在 Claude API、Claude Platform on AWS 和 Claude Models on Google Cloud (Anthropic managed) 上，请发送 inline-tools-2026-09-15 beta 标头。mid-conversation-tool-changes-2026-07-01 标头适用于通过引用指定工具名称的更改，支持 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 和 Claude Models on Google Cloud (Google managed)。

从 Claude Opus 4.7 迁移到 Claude Opus 5.5

首先完成每个发往 Claude Opus 5.5 的请求必须满足的要求、处理每个响应中的思考、从 Claude Opus 5 迁移到 Claude Opus 5.5和从 Claude Opus 4.8 迁移到 Claude Opus 5.5。将 claude-opus-4-7 作为您要替换的模型 ID。这些章节原样适用于 Claude Opus 4.7 上的代码。与 Claude Opus 4.8 一样，它接受 thinking: {"type": "disabled"}、强制工具选择和 computer_20251124 工具。它默认使用 high effort，并且除非您请求，否则不开启思考运行。

本节补充了 Claude Opus 4.7 之后的变化。如果您的代码使用的是 Claude Opus 4.6 或更早版本，请在本节之后继续阅读从 Claude Opus 4.6 及更早的 Opus 模型迁移到 Claude Opus 5.5。该节补充了在 Claude Opus 4.7 中生效的破坏性变更。有关检查清单，请参阅迁移检查清单的前三组。

变化内容

以下各项都不会在前面章节的基础上新增破坏性变更；在您替换模型 ID 之后，值得对它们进行检查。

  1. 重新校准的 effort 级别： 与 Claude Opus 4.7 相比，Claude Opus 5.5 上每个 effort 级别背后的令牌分配有所变化。默认值为 medium，而 Claude Opus 4.7 的默认值为 high。请在您自己的评估上重新进行 effort 扫描，而不是沿用为 Claude Opus 4.7 调优的设置。请参阅 Effort。

  2. 1M 上下文窗口为默认值： Claude Opus 5.5 默认提供完整的 1M 令牌 “context window”（上下文窗口），无需 beta 标头。如果您的客户端为了兼容旧模型而传递了上下文窗口 beta 标头，请将其移除。

  3. 对话中途的系统消息： 在 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 和 Claude Models on Google Cloud (Google managed) 上，Claude Opus 5.5 接受在 messages 数组中紧跟在用户轮次之后的 role: "system" 消息（需遵守放置规则）。对于从一开始就适用的指令，请使用顶层 system 字段。Claude Opus 4.7 会以 400 错误拒绝 messages 中的 role: "system"。如果您维护着通过重建完整消息历史来更新指令的代码路径，您可以简化它们，并保留早期轮次的提示缓存命中。

  4. 拒绝停止详情： 当模型拒绝请求时，Claude Opus 5.5 会在返回 refusal 停止原因的同时，返回一个指明拒绝类别的 stop_details 对象。Claude Opus 4.7 也返回相同的对象，因此只有当您的停止原因处理逻辑尚未读取该对象时，这一点才有影响。无需 beta 标头，也无法选择退出。如果您的停止原因处理逻辑尚未读取该对象，请参阅处理停止原因。Claude Opus 5.5 会在更多类别中拒绝请求；请参阅安全分类器和回退。

  5. 快速模式： Claude Opus 5.5 在 Claude API 上支持快速模式。快速模式在 Claude Opus 4.7 上不可用，在该模型上带有 speed: "fast" 的请求会返回错误。请在您的请求中设置 speed: "fast"。Claude Opus 5.5 不需要 beta 标头。

  6. 计算机使用工具集和浏览器使用工具： Claude Opus 5.5 支持以 computer_toolset_20260801 工具集形式提供的计算机使用，以及用于网页内任务的浏览器使用工具。Claude Opus 4.7 两者均不支持。要将 computer_20251124 集成迁移到该工具集，请参阅计算机使用的破坏性变更。

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

首先按页面顺序完成前面的每一个部分。它们是每个发送到 Claude Opus 5.5 的请求必须满足的条件、在每个响应中处理思考内容，以及 Claude Opus 5、Claude Opus 4.8 和 Claude Opus 4.7 的相关部分。这些部分按原样适用于运行在 Claude Opus 4.6 上的代码。与 Claude Opus 4.7 一样，Claude Opus 4.6 接受 thinking: {"type": "disabled"}、强制工具选择以及 computer_20251124 工具。它默认使用 high effort，并且除非您明确要求，否则不会启用思考。Claude Opus 4.5 及更早的 Opus 模型同样接受 thinking: {"type": "disabled"} 和强制工具选择，并且除非您明确要求，否则不会启用思考，因此这些部分也适用于它们。

本部分补充了 Claude Opus 4.7 中的变更，您需要替换的模型 ID 为 claude-opus-4-6。其两个子部分补充了在此之前的变更，分别面向使用 Claude Opus 4.5 或更早版本和 Claude 4.1 或更早版本的读者。如需检查清单，请参阅迁移检查清单，直至列出您所用模型的那一组。

破坏性变更

  1. 扩展思考已移除： Claude Opus 4.7 及更高版本的模型不再支持 thinking: {"type": "enabled", "budget_tokens": N}，使用该配置将返回 400 错误。请改用 adaptive thinking（自适应思考）（thinking: {"type": "adaptive"}），并使用 effort 参数来控制思考深度。在 Claude Opus 5.5 上，自适应思考始终开启：thinking: {"type": "adaptive"} 是有效的，并且等同于完全省略 thinking 字段。

    之前（Claude Opus 4.6）：

    client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

    之后（Claude Opus 5.5），其中模型 ID、thinking 和 output_config 这几行有所不同：

    client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

    自适应思考可以通过提示和 effort 参数进行引导，effort 参数取代了思考预算，成为控制模型推理量的方式。请在您自己的评估上进行 effort 扫描测试，而不是直接换算 budget_tokens 值。effort 级别表说明了何时使用各个级别，Claude Opus 5.5 的推荐 effort 级别则介绍了此模型的情况。

  2. 采样参数已移除： 请省略 temperature、top_p 和 top_k。 在 Claude Opus 5.5 上，推荐通过提示来引导模型行为。如果您之前使用 temperature = 0 来获得确定性，请注意，它在之前的模型上也从未保证输出完全相同。

  3. 默认省略思考内容： 在 Claude Opus 4.7 及更高版本的模型上，思考块仍会出现在响应流中，但除非您明确选择启用，否则其 thinking 字段为空。这是相对于 Claude Opus 4.6 的一项静默变更，在 Claude Opus 4.6 中，默认会返回摘要形式的思考文本。要恢复该行为，请参阅在每个响应中处理思考内容的第 4 项。

  4. 令牌计数已更新： Claude Opus 4.7 引入了新的 tokenizer（分词器），之后的 Opus 模型（包括 Claude Opus 5.5）也使用该分词器。它有助于提升在各类任务上的性能，但与 Claude Opus 4.7 之前的模型相比，处理文本时可能会使用大约 1 到 1.35 倍的令牌（最多多出约 35%，因内容而异）。

    /v1/messages/count_tokens 为 Claude Opus 5.5 返回的令牌数与为 Claude Opus 4.6 返回的不同。令牌效率可能因工作负载形态而异。

    请更新您的 max_tokens 参数以留出额外余量（包括压缩触发阈值），并重新测试任何在客户端估算令牌数或假定固定令牌/字符比例的代码路径。请使用令牌计数端点进行验证。提示层面的干预、task_budget 和 effort 可以帮助控制成本；但这些控制手段可能会以牺牲模型智能为代价。

  5. 预填充移除（在 Claude Opus 4.6 上已生效）： 在 Claude Opus 4.6 及更高版本的 Opus 模型（包括 Claude Opus 5.5）上，预填充助手消息会返回 400 错误，因此只有当您从 Claude Opus 4.5 或更早版本迁移时，这才是一项变更。请改用结构化输出或系统提示指令。

行为变更

Claude Opus 4.7 引入了一些与 Claude Opus 4.6 不同的行为差异，这些差异并非 API 破坏性变更。以下三项会影响代码或脚手架：

  1. 智能体轨迹中的内置进度更新： 在较长的智能体轨迹中，Claude Opus 4.7 会向用户提供更频繁、更高质量的更新。如果您添加了用于强制输出中间状态消息的脚手架（例如"每进行 3 次工具调用后，总结进度"），请尝试将其移除。在 Claude Opus 5.5 上，这些更新出现在 thinking 块中，而在默认的 thinking.display 设置下这些块为空。要接收这些更新，请参阅工具调用之间的文本以思考块形式返回。要调整其长度和内容，请参阅面向用户的进度更新。

  2. 实时网络安全防护措施： 这些防护措施是 Claude Opus 4.7 中新增的：涉及受禁止或高风险主题的请求可能会被拒绝。对于渗透测试、漏洞研究或红队测试等合法安全工作，请申请加入 Cyber Verification Program 以请求放宽限制。申请途径取决于您访问 Claude 的方式。

  3. 高分辨率图像支持： Claude Opus 4.7 是第一个支持高分辨率图像的 Claude 模型。最大图像分辨率为长边 2,576 像素，高于之前模型的 1,568 像素。这为视觉密集型工作负载带来了提升，对于计算机使用、屏幕截图理解和文档分析尤其有价值。

    高分辨率支持是自动启用的，不需要 beta 标头或客户端选择启用。需要提前规划两点：

    • 全分辨率图像可能比之前的模型多使用约 3 倍的图像令牌（每张图像最多 4,784 个令牌，而之前的上限约为 1,600 个令牌）。请为图像密集型工作负载重新规划 max_tokens 和成本预期；如果您不需要额外的保真度，也可以在发送前进行降采样。
    • 在 Claude Opus 4.7 上，模型返回的指向坐标和边界框坐标与实际图像像素为 1:1 对应，因此无需进行缩放系数换算。

    详情请参阅 Claude Opus 4.7 上的高分辨率图像支持。

有关提示方面的差异，请参阅为 Claude Opus 5.5 编写提示和提示最佳实践。

从 Claude Opus 4.5 或更早版本迁移

如果您要从 Claude Opus 4.5、Claude Opus 4.1 或更早的模型直接迁移到 Claude Opus 5.5，请从头阅读本页：首先按页面顺序完成前面的每一个部分。然后完成本部分前面的从 Claude Opus 4.6 迁移的破坏性变更。接着应用以下累积变更，这些变更在 Claude Opus 4.5 到 Claude Opus 4.7 之间生效。如果您使用的是 Claude Opus 4.1 或更早版本，请在完成本子部分后继续阅读从 Claude 4.1 或更早版本迁移。

破坏性变更

  1. 预填充移除已在从 Claude Opus 4.6 迁移的破坏性变更中介绍。

  2. 工具参数引号处理： Claude Opus 4.6 及更高版本的模型在工具调用参数中生成的 JSON 字符串转义可能略有不同（例如，对 Unicode 转义或正斜杠转义的处理方式不同）。如果您将工具调用的 input 作为原始字符串解析而不是使用 JSON 解析器，请检查您的解析逻辑。标准 JSON 解析器（例如 json.loads() 或 JSON.parse()）会自动处理这些差异。

第一项在 Claude Opus 5.5 上是必需的；其余各项为推荐变更。

  1. 迁移到自适应思考（必需）： 在 Claude Opus 4.7 及更高版本的模型上，thinking: {"type": "enabled", "budget_tokens": N} 会返回 400 错误。迁移前后的对比见从 Claude Opus 4.6 迁移的破坏性变更的第 1 项。此次迁移还需从 client.beta.messages.create() 改为 client.messages.create()：自适应思考和 effort 不需要 beta SDK 命名空间，也不需要任何 beta 标头。

  2. 移除 effort beta 标头： effort 参数不需要 beta 标头。请从您的请求中移除 effort-2025-11-24 beta。

  3. 移除细粒度工具流式传输 beta 标头： 细粒度工具流式传输不需要 beta 标头。请从您的请求中移除 fine-grained-tool-streaming-2025-05-14 beta。

  4. 移除交错思考 beta 标头： 使用自适应思考时，在每个支持自适应思考的模型上，交错思考都会自动启用。请从您的请求中移除 interleaved-thinking-2025-05-14 beta。

  5. 迁移到 output_config.format： 如果您使用结构化输出，请将 output_format={...} 更新为 output_config={"format": {...}}。output_format 参数已弃用，并将在未来移除。如果仍要使用它，请添加 structured-outputs-2025-11-13 beta 标头。否则，API 将返回 400 错误。Python SDK（v1.0 及更高版本）在 client.beta.messages.create() 或 count_tokens() 上不接受 output_format={...}。parse() 和 stream() 辅助方法的 output_format=Model 参数保持不变。

从 Claude 4.1 或更早版本迁移

如果您要从 Claude Opus 4.1 或更早的模型直接迁移到 Claude Opus 5.5，请首先应用从 Claude Opus 4.5 或更早版本迁移中的全部内容。该子部分以前面的每一个部分为起点，因此实际上您需要从头阅读本页。然后应用本子部分中的其他变更。

其他破坏性变更

  1. 移除采样参数： 详见采样参数已移除。

  2. 更新工具版本

    更新到当前的工具版本。移除任何使用 undo_edit 命令的代码。

    # 之前
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]

# 之后
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
    • 文本编辑器： 使用 text_editor_20250728 和 str_replace_based_edit_tool。详情请参阅文本编辑器工具文档。
    • 代码执行： 升级到 code_execution_20260521。迁移说明请参阅代码执行工具文档。
    • 计算机使用： 使用 computer_toolset_20260801 工具集代替 Claude Opus 5.5 不接受的 computer_20250124。在 Amazon Bedrock 上，computer_20251124 也可以使用。请参阅计算机使用的破坏性变更。

  3. 处理 refusal 停止原因

    更新您的应用程序以处理 refusal 停止原因：

    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # 妥善处理拒绝响应
    pass

  4. 处理 model_context_window_exceeded 停止原因

    当生成因达到上下文窗口限制（而非请求的 max_tokens 限制）而停止时，Claude 4.5 及更高版本的模型会返回 model_context_window_exceeded 停止原因。请更新您的应用程序以处理这一新的停止原因：

    response = client.messages.create(...)

if response.stop_reason == "model_context_window_exceeded":
    # 妥善处理上下文窗口限制
    pass

  5. 验证工具参数处理（尾随换行符）

    Claude 4.5 及更高版本的模型会保留工具调用字符串参数中的尾随换行符，而这些换行符以前会被去除。如果您的工具依赖于对工具调用参数进行精确字符串匹配，请验证您的逻辑能否正确处理尾随换行符。

  6. 针对行为变化更新您的提示

    Claude 4 及更高版本的模型具有更简洁、直接的沟通风格，并且需要明确的指示。有关优化指导，请查阅提示最佳实践。

  • Beta 标头： 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4 及更高版本的模型都内置了令牌高效的工具使用功能，这些标头不再起作用。

从 Claude Sonnet 5 迁移到 Claude Opus 5.5

请完成每个发送到 Claude Opus 5.5 的请求必须满足的条件、在每个响应中处理思考内容以及从 Claude Opus 5 迁移到 Claude Opus 5.5。将 claude-sonnet-5 作为您要替换的模型 ID。最后一个部分按原样适用于运行在 Claude Sonnet 5 上的代码，因为 Claude Sonnet 5 与 Claude Opus 5 一样：

  • 默认启用思考，并接受 thinking: {"type": "disabled"}（对于 Claude Sonnet 5，在任何 effort 级别下均可）。
  • 接受强制工具选择和 computer_20251124 工具。
  • 将工具调用之间的文本作为 text 块返回。
  • 默认使用 high effort。

手动扩展思考、采样参数以及助手预填充在这两个模型上都会返回 400 错误，因此这方面没有任何变化。Claude Opus 4.8、Claude Opus 4.7 和 Claude Opus 4.6 相关部分中的必需变更均不适用于您。

变更内容

  1. 对话中途的系统消息： 在 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 和 Claude Models on Google Cloud (Google managed) 上，Claude Opus 5.5 接受在 messages 数组中紧跟在用户轮次之后的 role: "system" 消息（需遵守放置规则）。此功能在 Claude Sonnet 5 上不可用。如果您维护着通过重建完整消息历史来更新指令的代码路径，您可以简化它们，并保留早期轮次的提示缓存命中。

  2. 更低的提示缓存最小值： Claude Opus 5.5 上可缓存提示的最小长度为 512 个令牌，低于 Claude Sonnet 5 上的 1,024 个令牌。在 Claude Sonnet 5 上因过短而无法缓存的提示现在可以创建缓存条目，无需任何代码更改。有关各模型的最小值，请参阅提示缓存。

此页面对您有帮助吗？