保留思考

在运行前缀检查的 Claude 模型上,保留思考决定模型能否使用您从早期轮次发回的思考块。

当您的代码发回思考块时,Claude 可以在早期轮次的推理基础上继续推理。Preserved thinking(保留思考)决定它可以使用其中哪些块。在具有保留思考的模型上,可用的块会留在上下文中,并按输入计费。请原样发回助手轮次,与 API 返回时完全一致。

如果请求已因 The block is bound to a different conversation 而失败,请从修复绑定到其他对话的思考块开始。

思考块与什么绑定

在这些模型上,思考块与以下内容绑定:

prefix_mismatch_behavior 用于选择未通过前缀检查的请求是收到 400 错误,还是由 API 丢弃未通过前缀检查的块。响应中的 input_transformations 会列出 API 丢弃或放行的思考块。丢弃思考是有代价的(请参阅丢弃思考的代价)。

切换模型再切换回来

更改 model,并持续发送完整对话。新模型或账户无法使用的思考块永远不会导致错误。API 会在该次请求中丢弃它且不对其计费,Claude 会在没有该推理的情况下作答。

在具有保留思考的模型上,thinking: {"type": "enabled"} 会导致 400 错误,而未通过前缀检查的请求也可能会收到该错误。

同一历史记录依次发送给 Claude Fable 5.1、Claude Opus 5.5,再发送给 Claude Fable 5.1:其思考块被丢弃一次,然后被再次读取

Claude Opus 5.5 无法读取 Claude Fable 5.1 的思考块,因此 API 会在发给它的请求中丢弃这些块。回到 Claude Fable 5.1 后,这些块会被再次读取,因为 API 从不更改您的 messages。切换模型时,只有当您的代码移除推理时,推理才会永久丢失。因此,不要移除思考,也不要为每个模型单独维护一份历史记录。

被丢弃的块不算作对对话的更改,因此两个模型的思考块都保持有效。

并非由您的代码进行的切换

路由器、拒绝后的回退或服务器端回退可能会替您切换模型,其他提供商的模型也可能接管某一轮次。请持续发送完整对话。包含 fallback 块的轮次有其自身的规则。关于应排除哪些块,请参阅继续对话。

任何切换都可能选中不接受系统消息的模型。请参阅当模型不接受系统消息时。

账户和云平台

迁移到另一个账户或云平台的方式相同:持续发送完整历史记录。

来自 Claude Fable 5.2、Claude Mythos 5.2、Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考块仅在生成它们的账户或与之关联的账户中有效。在其他任何账户中,API 会丢弃这些块,且不报错。

什么算作您的账户取决于平台。

机密信息和不受信任的文本

对于您的用户不会期望 Claude 信任的文件,请仅在 tool_result 块中发送。当您从历史记录中移除机密信息、个人数据或注入的文本时,还要移除它们首次出现位置之后的每个思考块。之后 Claude 会在没有该推理的情况下工作。

让智能体检查您的代码

在 Claude Code 中,先运行 claude update,然后在构建请求的代码仓库中运行以下提示:

让 Claude Code 为您检查代码

示例代码
/claude-api preserved-thinking-migration

使用其他智能体时,请向它提供更改工具或指令而不会导致前缀检查失败,并让它修复您的代码在请求之间更改 system、tools 或更早消息的每一处。

技术细节

在 Claude API 上哪些模型切换会保留推理

短横线表示您切换到的模型无法读取这些块。经过多次切换后,请为历史记录中的每个模型各查看一行。

切换前的模型切换到 Claude Fable 5.2 或 Claude Mythos 5.2切换到 Claude Fable 5.1 或 Claude Mythos 5.1切换到 Claude Opus 5.5切换到 Claude Sonnet 5.5切换到 Claude Haiku 5.5
Claude Haiku 5.5✅—✅✅✅
Claude Sonnet 5.5✅—✅✅—
Claude Opus 5✅✅✅——
Claude Opus 5.5✅✅✅——
Claude Fable 5 或 Claude Mythos 5✅✅———
Claude Fable 5.1 或 Claude Mythos 5.1✅✅———
Claude Fable 5.2 或 Claude Mythos 5.2✅————

如果某个模型没有对应的行或列,请参阅较早的模型。

较早的模型,例如 Claude Opus 5 和 Claude Sonnet 5

每个 Claude 模型都能读取来自 Claude Opus 4.8、Claude Sonnet 5、Claude Haiku 4.5 以及更早的 Claude Opus、Claude Sonnet 和 Claude Haiku 模型的思考块。

您切换到的模型仅读取来自以下模型的块
Claude Opus 4.8、Claude Sonnet 5、Claude Haiku 4.5 以及更早的 Claude Opus、Claude Sonnet 和 Claude Haiku 模型彼此
Claude Opus 5其自身,以及第一行中的模型
Claude Fable 5 和 Claude Mythos 5彼此、Claude Mythos Preview、Claude Opus 5,以及第一行中的模型

新模型上的思考设置

具有保留思考的模型会以 400 错误拒绝 thinking: {"type": "enabled"}。当您将对话从请求中设置了 "enabled" 的模型迁移到这些模型之一时,请改为发送 "adaptive"。在这些模型上省略 thinking 同样会启用自适应思考。

当模型不接受系统消息时

如果某个模型不在接受系统消息的模型列表中,请仅在发给该模型的请求中省略系统消息。让它们继续留在您存储的历史记录中。回到接受系统消息的模型后,请再次发送完整的已存储历史记录。回来时不带这些消息属于更改,请求可能会收到该 400 错误。

拒绝之后

允许的回退模型都无法读取拒绝模型的思考,因此回退模型会在没有该思考的情况下作答。回到您请求的模型后,Claude 会读取两个模型的思考。

来自其他提供商模型的轮次

来自其他提供商模型的轮次以 text 和 tool_use 内容的形式放在末尾。Claude 之前的思考保持有效。

各平台上什么算作您的账户

您调用 Claude 的位置您的账户
Claude API、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 或 Microsoft Foundry您的组织
Amazon Bedrock您的 AWS 账户
Claude Models on Google Cloud (Google managed)您的 Google Cloud 项目

如果某个思考块由另一个账户生成,而该账户的信誉已不再良好,API 也可能会省略该思考块。这适用于发往 Claude Fable 和 Claude Mythos 模型、Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 的请求。请求仍会成功,模型会在没有该块推理的情况下作答。

可用性

保留思考在部分模型上可用。

API 支持

具有保留思考的模型列于未通过前缀检查时各模型的行为中。

Messages API

  • 可用性:始终开启

Managed Agents

  • 可用性:始终开启

后续步骤

思考块的前缀检查

前缀检查比较哪些内容、请求未通过前缀检查时会发生什么,以及如何处理这两种情况。

文档内容持续同步更新