Claude
Claude Sonnet 5.5 迁移教程：模型 ID、effort 与思考模式的改写要点
从 Sonnet 5 迁移到 Sonnet 5.5 时，代码里有五处需要改写：思考模式的关闭方式、工具强制指定、思考块归属、旧版计算机操作工具、顾问工具。本文按「先改代码、再换模型 ID、最后重测 effort」的顺序，给出 Claude Code 与 Claude API 两侧的具体命令、参数与配置写法。
Claude Sonnet 5.5 发布后，Sonnet 5 进入旧版（legacy）状态，官方会引导使用者考虑迁移。价格没有变化，但 Sonnet 5 上跑着的代码有五处会受影响，effort 的各档位也重新调整过。这篇教程面向已经在用 Sonnet 5 的开发者，按「先改受影响代码、再换模型 ID、最后重测 effort」的顺序，把 Claude Code 与 Claude API 两侧要动的地方逐条讲清楚。站内也有一个 Claude 工具页，可以先了解它的基本定位。
准备工作
开始之前，先确认下面几件事，避免改到一半卡住。
- 确认当前使用的模型 ID。 在代码、配置文件、环境变量里搜索
claude-sonnet-5，把所有出现的位置列出来。迁移的目标 ID 是claude-sonnet-5-5。 - 确认 Claude Code 版本。 部分交互操作（例如在
/effort滑块里按s保存）需要 Claude Code v2.1.257 或更高版本。版本过低时，保存动作的行为可能不同。 - 确认 API 密钥与调用方式。 无论走 Claude Code 还是直接调 Claude API，都需要可用的密钥与网络出口。本文不涉及密钥的申请流程，请以官网当前信息为准。
- 确认计费口径。 迁移本身不改变单价，但 effort 档位变化会改变实际消耗的 token 量，进而影响账单。价格与配额属于易变信息，请以官网当前信息为准。
- 准备一份可回滚的配置。 模型 ID、effort 档位、思考模式三处都会改动请求行为，建议在版本控制里分次提交，便于逐项回退。
先看一眼两个模型在关键字段上的差异，有助于判断哪些地方需要动。
| 项目 | Sonnet 5 | Sonnet 5.5 |
|---|---|---|
| Claude API 的模型 ID | claude-sonnet-5 | claude-sonnet-5-5 |
| 输入 / 输出（每 1 MTok） | $2 / $10 | $2 / $10 |
| 缓存读取（每 1 MTok） | $0.20 | $0.20 |
| 可靠知识截止 | 2026 年 1 月 | 2026 年 6 月 |
| Claude API 的默认 effort | high | high |
| 定位 | 旧版（引导考虑迁移到 5.5） | 迁移目标 |
作为对照，同期的 Opus 5.5 单价为输入 $4、输出 $20、缓存读取 $0.20 / MTok，Claude API 的模型 ID 是 claude-opus-5-5。以上价格与 ID 都可能随版本调整，实际以官网当前信息为准。
操作步骤
第一步：找出并修复五处受影响的代码
Sonnet 5 上能跑的代码，在 Sonnet 5.5 上有五处行为变化。逐条排查：
- 关闭思考的写法变了。 以前用
"disabled"表示不思考，现在要改成thinking: {"type": "between_tools"}。具体写法见后面的 API 小节。 - 强制指定工具会报错。 搜索请求里强制指定工具（tool choice 强制）的地方，这类请求在 Sonnet 5.5 上会返回错误，需要改掉。
- 思考块与模型、对话绑定。 思考块（thinking block）的归属关系发生变化，涉及多轮对话拼接、缓存或历史消息复用的代码要检查。
- 旧版计算机操作工具不再接受。 在 Claude API 与 Google Cloud 上，
computer_20251124不再被接受。搜索指定了这个工具版本的位置并替换。 - 顾问工具不再接受 Sonnet 5 等作为顾问。 检查顾问工具（advisor tool）的配置，把 Sonnet 5 之类的模型从顾问位置移除。
第 2、3、5 条的具体改法需要对照官方对应页面确认，因为涉及请求结构与工具定义的细节。第 1 条和第 4 条相对直接，可以先把这两处改完再处理其余。
另外还有一类与显示相关的改动：如果应用会把工具调用之间的文字流式输出给用户，Sonnet 5.5 下这些文字会以思考块的形式返回，不做处理的话，工具调用之间就没有内容显示。处理方式见后面的 API 小节。
第二步：在 Claude Code 里切换到 Sonnet 5.5
Claude Code 有两个入口可以选模型：启动时的 --model，以及会话中的 /model。两者都接受别名或模型名称，形式为 <alias|name>。
用别名指定时，官方给出的写法形如：
claude --model opus
/model sonnet第一行在启动时使用，第二行在会话内输入。别名具体指向哪个模型，需要查 Model configuration 页面确认，因为别名映射会随版本变化。
除了别名，也可以直接传模型 ID。用模型 ID 切换的写法是：
claude --model claude-sonnet-5-5
/model claude-sonnet-5-5同样，第一行用于启动，第二行用于会话中。按生效范围区分，操作方式如下：
| 生效范围 | 操作 |
|---|---|
| 仅当前会话 | 不带参数的 /model 打开选择界面，选中 Sonnet 5.5 后按 s |
| 作为新会话的默认值 | 不带参数的 /model 打开选择界面，选中 Sonnet 5.5 后按回车 |
| 写入配置文件长期生效 | 在配置文件的 model 键里写模型 ID |
写入配置文件的写法如下：
{
"model": "claude-sonnet-5-5"
}写进配置文件后，后续会话都会沿用这个模型，不需要每次启动再指定。
第三步：重新测一遍 effort 档位
Sonnet 5.5 的 effort 档位被重新调整过，所以不要沿用 Sonnet 5 上的设置，应该按自己的评测重新测一遍。先记住几个基本事实：
- 可选档位：
low、medium、high、xhigh、max。 - 默认档位： Claude Code 是
medium，Claude API 是high。 - 建议起点： 在智能体式编码（agentic coding）场景下，规格明确的课题从
medium起步，遇到困难或耗时的课题再升到high。
调整 effort 的方式按目的区分：
| 目的 | 操作 |
|---|---|
| 只在当前会话试一档 | 不带参数的 /effort 打开滑块，选好档位后按 s（需要 Claude Code v2.1.257 及以上） |
| 把选中的档位保存为默认 | 不带参数的 /effort 打开滑块，选好档位后按回车 |
| 启动时显式指定 | 给 --effort 传档位，例如 claude --effort medium |
| 写进配置长期生效 | 在配置的 modelSettings 里按模型写档位 |
在 /effort 后面直接跟档位名，可以立刻切到该档位。例如先从中等档起步、遇到难题再升档：
/effort medium
/effort high需要注意：max 不能写进 modelSettings，也不能写进 effortLevel。如果此前用的是最顶层的 effortLevel 配置，要按 Model configuration 页面的格式改成 modelSettings 下的按模型写法，再填入 Sonnet 5.5 的档位。
第四步：改写 API 侧关闭思考的请求
Sonnet 5.5 不再用 "disabled" 关闭思考，改为发送 thinking: {"type": "between_tools"}。和模型 ID 一起改，请求体大致是这样：
{
"model": "claude-sonnet-5-5",
"thinking": { "type": "between_tools" }
}这个设置适用于 low、medium、high 三档。Claude API 上 Sonnet 5.5 的默认 effort 是 high；xhigh 与 max 没有被列为该设置可用的档位范围。
如果应用会把工具调用之间的文字展示给用户，需要额外处理，二选一：
- 用
between_tools关闭工具之间的思考，让这部分内容不再以思考块返回； - 或者调整展示逻辑，改为从思考块中读取并渲染这段文字。
不处理的话，Sonnet 5.5 会把这段文字放进思考块返回，工具调用之间就什么都不显示了。
第五步：判断该用 Sonnet 5.5 还是 Opus 5.5
迁移完成后，还有一个选型问题。按官方指引：
| 场景 | 更适合的模型 |
|---|---|
| 范围明确的日常作业、缺陷修复 | Sonnet 5.5 |
| 数小时级的自主编码智能体、大规模重构 | Opus 5.5 |
| 拿不定主意时 | 多数作业从 Opus 5.5 起步 |
在换成 Opus 5.5 之前，先考虑调整 effort。官方指引认为，比起换模型，调 effort 往往是更合适的手段。
一个完整示例
下面把一次最小迁移串起来，从改代码到验证跑通。
第 1 步：修掉旧版计算机操作工具。 在代码库中搜索 computer_20251124，把出现的位置替换为当前可用的工具版本。Claude API 与 Google Cloud 都不再接受这个旧版本。
第 2 步：修掉强制指定工具。 搜索请求里强制指定工具的部分，改为不强制，或改用当前支持的写法。具体格式对照官方页面确认。
第 3 步：改写关闭思考的请求体。 把原来的 "disabled" 换成 between_tools，同时把模型 ID 一起换掉：
{
"model": "claude-sonnet-5-5",
"thinking": { "type": "between_tools" }
}第 4 步：在 Claude Code 里切模型。 启动时指定，或写入配置文件：
claude --model claude-sonnet-5-5{
"model": "claude-sonnet-5-5"
}第 5 步：重测 effort。 先从中等档起步，跑几个规格明确的课题；遇到难题再升档：
/effort medium
/effort high第 6 步：验证。 用非交互模式跑一个最小任务，确认模型 ID 生效、思考模式符合预期、工具调用之间没有出现空白显示：
claude -p --model claude-sonnet-5-5 "用一句话说明这个仓库的用途"如果输出正常、没有报错，说明模型 ID 与请求结构都已切换成功。接着再跑一遍完整测试集，确认第 2、3、5 条改动没有引入回归。
注意事项
- 不要沿用 Sonnet 5 的 effort 设置。 Sonnet 5.5 的档位经过重新调整，官方明确建议按自己的评测重新测，而不是直接搬过来。
max有写入限制。 它不能写进modelSettings，也不能写进effortLevel。- 最顶层的
effortLevel需要改格式。 如果此前用的是这个配置，要按 Model configuration 页面的格式改成按模型书写的modelSettings。 between_tools有档位范围。 它适用于low、medium、high；xhigh与max不在其列。- 工具调用之间的文字可能不再显示。 这是显示层面的行为变化，需要主动处理，否则用户会看到空白。
- 别名映射会变。
sonnet、opus这类别名指向哪个模型，以 Model configuration 页面为准，不要凭记忆写死。 - 价格、配额、模型 ID、知识截止时间都属于易变信息。 本文列出的数值仅用于说明迁移时的对照关系，实际以官网当前信息为准。
- 迁移顺序不要颠倒。 先修受影响的代码，再换模型 ID，最后重测 effort。顺序反了容易把行为变化误判成模型能力差异。