Claude 扩展思维（Extended Thinking）参考

本文是对 Anthropic 官方参考页的中文整理，完整与最新内容以原文为准：https://platform.claude.com/docs/en/build-with-claude/extended-thinking

概述与弃用状态

扩展思维（manual extended thinking）通过在请求中设置固定的思维 token 预算，让 Claude 在给出最终答案前先进行内部推理。适用于需要可预测延迟或需要精确控制思维成本的场景。

若请求返回 400 错误，且错误信息以「"thinking.type.enabled" is not supported」开头，说明该模型使用的是自适应思维模式，应参考本文「迁移到自适应思维」章节。

凡两种模式都可用的模型，官方建议优先使用自适应思维（adaptive thinking）。

支持的模型

各模型对扩展思维的支持情况（含仅支持扩展思维的模型列表），参见按模型配置对照表。

基本用法

请求体中加入 thinking 对象即可启用：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [ ... ]
}

响应中的 content 数组会包含 type: "thinking" 的思维块（内容在 thinking 字段中，为摘要形式）和 type: "text" 的正文文本块。

budget_tokens 规则

budget_tokens 是目标值而非严格上限——Claude 实际用量可能远小于预算；max_tokens 才是输出总量的硬上限。

在 Claude Opus 4.5（唯一支持effort的纯扩展思维模型）上，effort 决定整体响应形态，budget_tokens 决定思维深度，两者需同时设置。

预算调优建议

预算越高通常推理越全面，但收益递减，且延迟增加。

用量追踪

响应中 usage.output_tokens_details.thinking_tokens 字段记录被计费输出 token 中用于内部推理的部分。流式返回时，该字段只出现在最后一个 message_delta 事件中。

手动模式下的交错思维（Interleaved Thinking）

交错思维允许 Claude 在同一助手轮次内的工具调用之间进行思考，对每个工具结果推理后再决定下一步。概念与轮次结构参见思维总览页。

其他要点：

• 在交错思维场景下，budget_tokens 可超过 max_tokens（见上文预算规则例外）
• 交错思维仅支持通过 Messages API 使用的工具

各平台对 beta 头的处理

注意：「接受」不等于「生效」——在拒绝 type: "enabled" 的模型（4.7 及更新）或手动模式不支持交错思维的模型（Claude Opus 4.6）上，该头在手动模式下不产生效果，此时是自适应思维自动完成交错。

手动模式下的轮次结构

通用的轮次结构规则（单轮工具调用循环、轮次中途配置冲突处理、跨轮次切换思维开关）参见思维总览页 - 工具使用中的思维。

手动模式额外要求：启用思维的请求中，最后一个助手轮次必须以思维块开头（自适应思维取消了该要求）。跨轮次更改思维配置会使提示缓存失效（见下节）。

手动模式下的提示缓存

除思维模式通用的缓存行为（参见思维与提示缓存）外，手动模式额外规则：

跨请求更改 budget_tokens 会使缓存断点失效，原理与切换思维模式相同——因为预算值会被渲染进提示词中。

实测示例（Claude Sonnet 4.6，消息级缓存）

建议：在同一缓存对话的生命周期内选定一个预算值并保持不变。

与思维模式无关的共享机制

以下内容在思维总览页统一说明，手动模式同样适用：

• 控制思维展示（display 参数）
• 流式思维
• 工具使用中的思维（含思维块保留）
• 思维与提示缓存
• 思维与上下文窗口
• 思维加密
• 定价

迁移到自适应思维（Adaptive Thinking）

迁移映射

迁移前：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

迁移后：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

即：移除 budget_tokens，设置 thinking: {type: "adaptive"}，改用 output_config.effort 控制推理深度。effort: "high" 与 API 默认值一致，省略该字段效果相同。

行为差异（不仅是语法变化）

思维块保留差异

详见按模型的思维块保留说明。

切换思维模式属于思维配置变更，切换后第一个请求会使缓存断点失效（与「手动模式下的提示缓存」章节所述规则相同）。

完整指引另见：自适应思维、effort、模型迁移指南。