从 Fable 5.1 迁移到 Fable 5.2：改模型 ID、设 effort、调整 API 参数
从 Fable 5.1 迁移到 Fable 5.2：改模型 ID、设 effort、调整 API 参数
把 Claude Code 与 API 从 Fable 5.1 迁到 Fable 5.2 的实操步骤：替换模型 ID（含 Amazon Bedrock 写法）、用 /model 与 /effort 控制会话与默认值、在 API 侧去掉 tool_choice 强制并省略采样参数、按 effort 调整 max_tokens，并说明两版在费用与耗时上的取舍。
Fable 5.2 发布后，从 Fable 5.1 迁过去并不需要重写整套调用逻辑，真正要动的只有三处：模型 ID、effort 档位、以及 API 请求里几个已经不再适用的参数。这篇教程把这三处拆成可以照着敲的步骤，并说明在 Claude Code 与直接调用 API 两种场景下，改动分别落在哪里、默认值有什么差别、哪些旧配置必须删掉。
适合读这篇的人：已经在用 Fable 5.1 跑 Claude Code 或自建 API 调用，想评估是否值得切换，或者已经决定切换但不确定要改哪些字段。文中涉及的单价、上下文与配额等易变信息，请以官网当前公布的信息为准。
准备工作
动手之前先确认几件事，否则改完参数也跑不起来。
- 可用的模型访问权限。Fable 5.2 是当前的最新模型，Fable 5.1 仍处于可用状态（legacy），两者可以并存，因此迁移期间可以随时回退。
- Claude Code 客户端。本文涉及的会话级切换行为依赖较新的版本：
-p中执行/model只影响当次会话、不写入默认值的行为需要 Claude Code v2.1.205 及以上；选择界面里按s只切换当前会话的行为需要 v2.1.257 及以上。版本号请以官网当前信息为准。 - API 凭据与提供方。确认你的调用走的是 Claude API、Microsoft Foundry、Claude Platform on AWS、Claude Models on Google Cloud，还是 Amazon Bedrock——模型 ID 的写法在 Bedrock 上不同。
- 一份可回退的旧配置。把当前使用的模型 ID、effort 档位、
max_tokens与采样参数记录下来，方便对比与回滚。 - 一个用于验证的小任务。迁移后先用一个短任务跑通，确认请求不再返回 400，再放到正式流程里。
操作步骤
第一步：替换模型 ID
模型 ID 是最先要改的地方，而且写法随提供方而变。
| 提供方 | Fable 5.2 的模型 ID | Fable 5.1 的模型 ID |
|---|---|---|
| Claude API、Microsoft Foundry、Claude Platform on AWS、Claude Models on Google Cloud | claude-fable-5-2 | claude-fable-5-1 |
| Amazon Bedrock | anthropic.claude-fable-5-2 | anthropic.claude-fable-5-1 |
如果代码里把模型 ID 写成了常量或环境变量，改一处即可；如果散落在多个脚本里，建议先全局搜索 claude-fable-5-1 与 anthropic.claude-fable-5-1 两个字符串，逐个替换。
第二步：在 Claude Code 里切换模型
Claude Code 提供三种切换方式，区别在于改动是否会被保存为默认值。
| 方式 | 生效范围 |
|---|---|
在 /model 的选择界面按 Enter | 切换并保存为后续新会话的默认模型 |
在 /model 的选择界面按 s | 仅当前会话 |
直接输入 /model <name> | 与按 Enter 相同，会保存为默认值 |
在 -p 执行过程中使用 /model | 仅该会话，不保存（Claude Code v2.1.205 及以上） |
启动时加 claude --model <name> 或设置环境变量 ANTHROPIC_MODEL | 仅该次启动的会话 |
在设置文件的 model 项中固定 | 新会话的默认值 |
环境变量 ANTHROPIC_DEFAULT_MODEL | 新会话的默认值 |
想把当前会话切到 Fable 5.2，同时把它设为以后的默认模型：
/model claude-fable-5-2只想试一次、不动默认值，就在启动时指定：
claude --model claude-fable-5-2如果需要在多个终端里同时跑不同模型，不要用 /model 来回切，而是每个终端启动时各自带上 --model，这样互不干扰。
第三步：确定 effort 的起点
effort 决定模型在思考上投入多少。迁移时最容易踩的坑，是把 Fable 5.1 上用的档位原样搬过来——官方建议在迁移时按自己的评测重新定档，而不是沿用旧值。
推荐的起点是 high：能力提升的大部分在 high 上就能拿到，再往上收益不稳定、因任务而异。只有在最困难的长时间编码或 agent 任务上，并且自己的评测确实测到了提升，才考虑 xhigh；反过来，如果评测证明质量能保住，可以降到 medium 或 low。max 留给测量模型上限、或者不在意时间和 token 消耗的少数任务。
注意默认值在两个入口上并不一致：
| 入口 | 不指定 effort 时的默认档位 |
|---|---|
| Claude Code | medium（与 Opus 5.5、Sonnet 5.5、Haiku 5.5 相同） |
| API | high（Fable 5.1 也是 high） |
也就是说，在 Claude Code 里什么都不写，会从 medium 起步；而在 API 里省略 effort，会从 high 起步。如果你的评测是在 high 上做的，Claude Code 侧就要显式指定，否则实际跑的不是你测过的配置。
第四步：在 Claude Code 里指定 effort
把当前会话设为 high 并保存为默认值：
/effort high只想让当前会话生效，就在选择界面按 s（Claude Code v2.1.257 及以上）。/effort 的生效范围如下：
| 用法 | 生效范围 |
|---|---|
| 在选择界面按 Enter，或直接输入档位名 | 保存为默认值，后续会话继续生效 |
在选择界面按 s | 仅当前会话（v2.1.257 及以上） |
在 -p 执行过程中使用 /effort | 仅该会话，不保存 |
/effort auto | 清除当前模型已保存的档位 |
也可以在启动时把模型和 effort 一起传进去，--effort 只对当次会话生效：
claude --model claude-fable-5-2 --effort high需要写进设置文件时，在项目级、本地级、管理员级设置，或通过 --settings 传入的设置顶层写 effortLevel。注意这个键对所有模型生效：
{
"model": "claude-fable-5-2",
"effortLevel": "high"
}不想改文件、只想临时试一下，可以在启动时用 --settings 直接传 JSON：
claude --model claude-fable-5-2 --settings '{"effortLevel":"high"}'如果不同模型需要不同档位，用 modelSettings 按模型分别设置。effortLevel 可接受的值为 low、medium、high、xhigh，它同时充当未在 modelSettings 中单独指定档位的模型的默认值。max 不能写进这两个键中的任何一个。此外也可以用环境变量 CLAUDE_CODE_EFFORT_LEVEL 来设定。
第五步：调整 API 请求参数
API 侧除了换模型 ID，还要按 Fable 5.2 的约束清理请求体。逐项对照下表：
| 项目 | Fable 5.2 下的处理方式 |
|---|---|
| 思考（thinking） | 始终开启，无法关闭；深度通过 effort 调节 |
tool_choice | 用类型 any 或 tool 强制使用工具会返回 400 错误，必须去掉强制 |
temperature、top_p、top_k | 省略不传 |
| effort | 省略时为 high；迁移时按自己的评测重新定档 |
max_tokens | high 及以上要取较大值 |
其中 max_tokens 这一条尤其容易被忽略：它是思考内容与回复正文合计的输出上限，而 Fable 5.2 在 high 及以上档位会消耗明显更多的思考 token，沿用旧值很容易被截断。具体该设多大，取决于任务长度，建议先用一个代表性任务观察实际输出量再定。
把上面几条落到代码里，请求体大致是这样：
{
"model": "claude-fable-5-2",
"max_tokens": 16000,
"messages": [
{ "role": "user", "content": "..." }
]
}对比迁移前的写法，需要删掉的是 temperature、top_p、top_k 三个字段，以及 tool_choice 中形如 {"type": "any"} 或 {"type": "tool", "name": "..."} 的强制写法。如果业务逻辑依赖“必须调用某个工具”，改成在提示词里明确要求，或由应用层校验返回结果，而不是靠 tool_choice 强制。
一个完整示例
下面把整条链路串起来：从命令行启动一个使用 Fable 5.2、effort 为 high 的 Claude Code 会话，再用 API 发一次等价请求。
场景一：Claude Code 交互式会话。先启动并指定模型与 effort，两者都只对本次会话生效，不影响默认配置：
claude --model claude-fable-5-2 --effort high进入会话后确认当前配置，如果发现 effort 不是 high，用 /effort high 补上。若希望这套配置成为以后所有新会话的默认值，改用 /model claude-fable-5-2 与 /effort high，两者都会写入用户设置。
场景二：非交互式批量执行。在脚本里跑一次性任务时，用 -p 模式，并在启动参数里固定模型与 effort：
claude -p "整理这个目录下的变更说明" --model claude-fable-5-2 --effort high这种写法不会改动默认模型，适合在 CI 或多终端并行时使用。
场景三：直接调用 API。把模型 ID 换成 claude-fable-5-2（Amazon Bedrock 上为 anthropic.claude-fable-5-2），去掉采样参数与工具强制，并把 max_tokens 放大：
{
"model": "claude-fable-5-2",
"max_tokens": 16000,
"messages": [
{ "role": "user", "content": "把这段日志按错误类型归类" }
]
}如果请求返回 400，优先检查两处：tool_choice 是否还残留 any 或 tool 的强制写法，以及是否还在传 temperature、top_p、top_k。
场景四：用设置文件统一管理。团队里多人共用一套配置时，把模型与 effort 写进设置文件，避免每个人各自记参数：
{
"model": "claude-fable-5-2",
"effortLevel": "high"
}需要按模型区分档位时，改用 modelSettings 单独指定，effortLevel 则作为其余模型的兜底值。
注意事项
两个入口的默认 effort 不同。Claude Code 不指定时是 medium，API 不指定时是 high。如果你的评测是在 high 上做的，Claude Code 侧必须显式指定，否则实际运行配置与评测配置不一致。
不要直接沿用 Fable 5.1 的档位。迁移时应按自己的评测重新定档，从 high 起步，再根据结果上下调整。
max 不能写进设置文件。effortLevel 与 modelSettings 都只接受 low、medium、high、xhigh。
思考无法关闭。Fable 5.2 的思考始终开启，只能通过 effort 调节深度。这意味着输出 token 中会包含思考部分，计费与截断判断都要把这块算进去。
工具强制会直接报错。tool_choice 使用 any 或 tool 会返回 400，不是降级处理，而是请求失败。迁移前务必检查所有构造请求体的位置。
权限收紧的环境下，被拒绝的命令可能变多。在只自动放行部分操作、其余一律拒绝的配置下（例如 --permission-mode dontAsk），Fable 5.2 触发的拒绝次数可能高于 Fable 5.1，被拒绝的命令不会执行，任务仍会继续推进。如果生产环境对允许的操作范围限制得很窄，迁移后应额外统计被拒绝的命令数量，评估对结果的影响。
费用与耗时的取舍要按用途判断。在小型任务上的对比结果显示，两版成功率相同，Fable 5.2 的费用更低、耗时更长。因此：需要反复自动执行、费用会累积的批处理场景，Fable 5.2 更合适；需要人坐在屏幕前等结果的交互场景，Fable 5.1 的响应更快。这类结论来自小规模任务，困难任务、长时间 agent 作业、大型代码库以及 high 以外的档位都未经验证，不要直接外推到所有场景。
单价与配额以官网为准。Fable 5.2 的各项单价低于 Fable 5.1，Batch API 下输入与输出均有折扣，但具体数字、可用区域与速率限制会随时间调整，做预算前请查阅官网当前信息。
Fable 5.1 仍可使用。它处于 legacy 状态，迁移期间可以保留旧配置作为回退路径，不必一次性全量切换。