思考功能故障排查

本页面涵盖配置思考功能或回传思考块（即在后续请求中发回已返回的思考块）时最常见的故障。第一部分列出了每个模型支持的思考配置以及会被拒绝的配置；之后的各部分均从您观察到的症状入手，以便您将错误消息或意外响应直接对应到其原因和修复方法。有关思考功能的工作原理，请参阅思考概述。



各模型拒绝的配置

大多数思考配置错误源于请求中的 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 支持两种模式。在两种模式都可用的情况下，请改用自适应思考。

下表列出了每个模型支持的类型、默认设置，以及会以 400 错误拒绝的 thinking.type 值；未列为拒绝的值均会被接受。

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

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

早期的 Claude 4 模型（Claude Opus 4.1、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" 而非禁用思考；请参阅控制思考显示。

在 Claude Opus 5 上也可能出现针对 "disabled" 的 400 错误，该模型仅在 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 与预算组合生效；请参阅预算规则与调优。



后续步骤