Claude Opus 5.5 生成输出的速度比上一代 Opus 5 快 30% 以上，完成同样的任务通常也用更少的 token。

如果你直接把以前为 Opus 5 写的提示词搬过来，它依然能跑得不错。但如果迁移之后遇到Agent 做到一半停下、长时间看不到进度、请求被拒答、每轮更慢更贵，多半是它的几处行为和 Opus 5 不一样了。

Anthropic 的这份开发者文档就是按“你看到了什么现象”来组织的：每种现象对应一段解释、一个参数调整或一段可以直接粘贴的提示词。本文把它们逐条讲清。如果你主要在 Claude 应用和 Claude Code 里用它，可以先看站内那篇面向日常使用的 Opus 5.5 指南；本文偏 API 接入和 Agent 框架。

文档开头按“你看到了什么现象”列了一份索引。遇到哪种情况，直接跳到对应部分：

先认识 7 个术语

下面这些词会反复出现，先用大白话过一遍：

• effort（思考力度 / 算力档位）：控制模型在回答前思考深度的参数。档位越高，它在回答前想得越多，花的 token 和时间也越多。
• max_tokens（最大输出上限）：单次调用中允许模型吐出的最大 token 总数。注意：无论你能不能看到模型的思考过程，思考消耗的 token 都会算在这个上限里。
• stop_reason（停止原因）：API 返回给你的状态标签。比如 end_turn 代表模型觉得自己讲完了把麦克风交还给你；tool_use 代表它要调工具；refusal 代表被安全规则拦截了。
• thinking 块（思维数据块）：API 返回结构中的独立区块，存放模型回答前的思考内容，和给用户看的正文（text 块）是分开的两类块。
• 提示缓存（Prompt Cache）：云端把重复的系统提示词或前文上下文缓存起来的技术，只要前缀不变，就能省钱、省时间。会话中途改动全局参数、系统提示词或工具列表，缓存就可能对不上而失效。
• harness / 框架（Agent 运行脚手架）：你的后台业务调度代码。它负责发请求给模型、接收返回结果、运行命令行或数据库工具，并在循环中驱动 Agent 一步步走下去。
• 子代理（Subagent）：主 Agent 派发专门任务给下级独立 Agent 协作运行的机制，常用于多任务并行。

核心变化：更快、更强，但思考机制变了

1. 先交代背景

Opus 5.5 是 Opus 5 的下一代模型。这份官方文档只讲 Opus 5.5 相比 Opus 5 的行为差异，以及对应的提示词和框架写法。原来给 Opus 5 写的提示词不改也能跑得不错，上一代的写法仍是合理起点。站内有两篇可以配合看：

官方另有三份文档分工：模型能力与 API 变化在 What's new in Claude Opus 5.5；从 Opus 5 迁移有 4 项破坏性 API 变更（会让旧请求直接出错的改动），在迁移指南；适用于所有当前 Claude 模型的通用技巧在 Prompting best practices。

所以本文讲的是：同样的代码和提示词换到 5.5 上，哪些地方表现会不一样、该怎么调。

2. 更快、更省，但前提是重新选档位

Opus 5.5 生成输出 token 的速度比 Opus 5 快 30% 以上；完成同样的任务，通常用的 token 也更少。对使用者来说，这意味着同样的活等得更短、token 花费更少。

但有个前提：同一个 effort 档位（控制它想多深的设置）下，5.5 每轮往往比 Opus 5 想得更多，xhigh 和 max 尤其明显；如果沿用 Opus 5 的档位，每轮会更长、输出 token 更多。“更快更省”要靠重新选档位来兑现：Anthropic 测试中，5.5 的默认档 medium 在编程和知识工作评测上达到或超过 Opus 5 的 high，在几项编程评测上 low 也接近它、成本低得多。具体怎么选，见下文第一部分。

3. 思考一直开着，effort 成了主开关

这里说的“思考”，是模型在给出回答之前先在内部推理一遍，这部分同样算输出 token。

Opus 5 在 high 及以下档位可以用 thinking: {"type": "disabled"} 关掉思考；Opus 5.5 不接受这个设置，思考始终开着，由模型自己决定想多少。

随之而来的几个变化：

• effort 成了控制思考量的主开关；想少思考先降 effort，比在提示词里要求更可靠。（→ 第一部分）
• 思考计入 max_tokens，哪怕思考内容没返回给你。（→ 第一部分）
• 响应开头可能有、也可能没有 thinking 块，要按块类型读取。（→ 第一部分）
• 你能看到多少思考内容由 thinking.display 决定：默认 "omitted" 下 thinking 字段是空的；"summarized" 返回推理摘要；"updates"（beta）返回工具调用之间进度更新的摘要。（→ 第二部分第 2 节）
• 要求模型把内部推理写进回复正文，请求可能以 reasoning_extraction 类别被拒。（→ 第三部分）

4. 能力上强在哪

文档列了和写提示词最相关的四项能力。下面的对比来自 Anthropic 自己的测试和早期测试者反馈：