思考故障排除

本页涵盖配置思考或往返传递思考块（将返回的思考块在后续请求中发送回去）时最常见的故障。第一节列出了每个模型支持的思考配置以及它拒绝的配置；之后的各节均从您观察到的症状出发，以便您可以将错误消息或意外响应直接与其原因和修复方法对应起来。关于思考的工作原理，请参阅思考概述。



各模型拒绝的配置

大多数思考配置错误是请求中的 thinking.type 值与模型支持的内容不匹配。在当前模型上，思考以 thinking: {type: "adaptive"} 运行，而在最新的模型上它默认开启。一些较早的模型则使用扩展思考，这是一种旧版手动模式，配置为 thinking: {type: "enabled", budget_tokens: N}。

扩展思考（thinking.type: "enabled" 搭配 budget_tokens）在 Claude 4.6 模型上已弃用（使用它的请求仍会成功）。Claude 4.7 及更高版本的模型不支持它，并会拒绝使用它的请求，返回 400 错误。在支持思考的 Claude 4.5 及更早版本的模型上，扩展思考是唯一可用的思考模式。Claude Mythos Preview 支持两种模式。在两种模式都可用的情况下，请改用自适应思考。

下表列出了每个模型支持的内容、默认值，以及哪些 thinking.type 值会被以 400 错误拒绝；任何未列为被拒绝的值都会被接受。

¹ enabled 和 budget_tokens 在这些模型上仍然有效，但已被弃用；请改用自适应思考。
² Claude Opus 5 在 effort 为 high 或更低时接受 "disabled"；将其与 effort xhigh 或 max 组合会返回 400 错误。此限制适用于 Claude Opus 5 及更高版本的模型，并在每个请求上强制执行。

标记为始终开启的模型无法关闭思考。标记为开启的模型默认进行思考，但接受 thinking: {type: "disabled"}。

较早的 Claude 4 模型（Claude Sonnet 4 和 Claude Opus 4）仅支持扩展思考；有关其可用性，请参阅模型弃用。Claude Fable 5 和 Claude Mythos 5 在零数据保留下不可用。



400 错误提示不支持 "thinking.type.enabled"

请求失败并返回 400 错误，其消息内容为：

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

这是因为您请求的模型已移除扩展思考（请参阅各模型拒绝的配置）。

将请求切换为 thinking: {type: "adaptive"}，并使用 effort 而不是 budget_tokens 来控制思考深度。迁移到自适应思考详细介绍了转换过程。



400 错误提示不支持 "thinking.type.disabled"

请求失败并返回 400 错误，其消息内容为：

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

这发生在思考始终开启的模型上：Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 会拒绝 "disabled"。在 Claude Fable 5 和 Claude Mythos 5 上，错误文本中建议的 "thinking.type.enabled" 也不适用：这些模型同样会拒绝它。

省略 thinking 参数；这些模型无需任何配置即可进行思考。如果您的目标是让响应中不包含思考文本，请使用 display: "omitted" 而不是禁用思考；请参阅控制思考显示。

"disabled" 上的 400 错误也可能发生在 Claude Opus 5 上，它仅在 effort 为 high 或更低时接受 thinking: {type: "disabled"}：将其与 effort xhigh 或 max 组合会被拒绝。请降低 effort 级别，或保持思考开启。



400 错误提示不支持自适应思考

请求失败并返回 400 错误，其消息内容为：

adaptive thinking is not supported on this model

这是因为该模型仅支持扩展思考（请参阅各模型拒绝的配置）。

请改用 thinking: {type: "enabled", budget_tokens: N}；有关配置，请参阅扩展思考。



400 错误提示思考块不能被修改

返回工具结果的请求失败并返回 400 invalid_request_error，其消息包含：

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

在多轮和工具使用对话中，您会将之前的助手消息（包括其 thinking 和 redacted_thinking 块）发送回 API，API 会验证它们是否原样到达。当您发送回的助手消息与 API 返回的消息不同时，就会发生此错误，最常见的原因是您的代码按类型过滤内容块并丢弃了 redacted_thinking 块，或者重新构建了助手消息而不是原样回传。

请将助手轮次原样回传，包括思考块。有关规则，请参阅保留思考块，以及工具和多轮工作流中的思考中的完整往返示例，其中包含每个 SDK 的正确代码。



响应中的 thinking 字段为空

响应包含 thinking 块，但其 thinking 字段是空字符串，只有 signature 字段有值。

这是因为在较新的模型上 display 默认为 "omitted"，它返回不含文本的思考块。

在您的思考配置中设置 display: "summarized" 以接收摘要的思考文本；有关各模型的默认值，请参阅控制思考显示。



某些轮次没有出现思考块

即使已配置思考，某些响应也完全不包含 thinking 块。

这在自适应模式下是正常的：Claude 会在它判断足够简单、可以直接回答的请求上跳过思考。

如果您希望思考更频繁或更深入，请提高 effort 或通过提示进行引导；请参阅引导 Claude 思考的频率。



文本输出中出现工具调用或 XML 标签

响应偶尔会将工具调用写入其文本中而不是发出 tool_use 块，或者在其可见文本中包含 <thinking> 或其他内部 XML 标签。泄漏的工具调用永远不会运行，并且在代理循环中，泄漏的文本会保留在对话历史中，因此后续轮次也会受到影响。

这发生在禁用思考的 Claude Opus 5 上，最常见于搜索等工具密集型工作负载。指示模型不要思考或不要推理的系统提示规则会增加标签泄漏。

重新启用思考（默认设置），并改用较低的 effort 级别来控制令牌成本。如果您的集成必须保持禁用思考，请应用在禁用思考的情况下运行中的提示缓解措施。



响应以 stop_reason: "max_tokens" 停止

响应以 stop_reason: "max_tokens" 结束，通常伴随被截断或缺失的文本块。

这是因为思考令牌计入 max_tokens，因此较长的思考过程可能会在文本响应完成之前耗尽预算。

提高 max_tokens 以便为思考和文本都留出空间，或降低 effort 使 Claude 在思考上花费更少；请参阅成本控制和思考与上下文窗口。



更改思考设置后缓存命中率下降

之前命中缓存的请求的 cache_read_input_tokens 降为零。

这是因为思考配置和 effort 级别（或其默认值）是缓存提示前缀的一部分，因此更改其中任何一项都会开始一个新的前缀：切换思考模式、更改 effort 值以及更改 budget_tokens 都会使消息缓存断点失效，并且还可能使工具和系统提示断点失效，具体取决于模型在何处呈现该配置。

在共享同一对话的请求之间保持思考配置和 effort 级别不变；将参数显式设置为其默认值等同于省略它，不会导致失效。请参阅思考与提示缓存。



设置 effort 没有改变思考

您更改了 effort，但思考频率或深度保持不变。

这是因为 effort 仅在自适应模式下才是主要的思考控制手段。在仅支持扩展思考的模型上，思考深度由 budget_tokens 设置。

在这些模型上调整 budget_tokens，或检查您的模型运行在哪种模式下；请参阅思考与 effort。在 Claude Opus 4.5（唯一支持 effort 的仅扩展思考模型）上，effort 与预算组合生效；请参阅预算规则与调优。



后续步骤