Claude API 扩展思考（extended thinking）参数怎么设：adaptive、budget_tokens、effort 和 display

本文根据 Claude 官方《Extended thinking》《Thinking》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 Anthropic 官方网站。API 是按用量计费的独立服务，与 Claude 订阅分开计算，Key 的获取见 /guides/claude-api-key-console。

适用于谁

• 想让 Claude 在复杂数学、代码、分析任务里先推理再回答的开发者；
• 看到旧教程写 thinking={"type": "enabled", "budget_tokens": ...}，换了新模型却报 400 的人；
• 想知道思考到底怎么计费、怎么控制深度的人。

结论先说

1. 官方现在推荐自适应思考：thinking 写 {"type": "adaptive"}，深度用 output_config 里的 effort 控制。
2. 旧的 enabled 加 budget_tokens 是遗留功能，已弃用；Claude 4.7 及之后的模型不支持，请求会返回 400。
3. Claude 5 系列等较新模型默认就是自适应思考，不用写 thinking 也在思考；Opus 4.8、4.7、4.6 和 Sonnet 4.6 默认关闭，要显式设 adaptive。
4. 思考 token 按输出 token 计费，即使你设了不返回思考文字，也按完整思考计费，并且算在 max_tokens 里。
5. 想看思考文字要设 display：较新的模型默认 omitted，只返回空的 thinking 字段加签名。

图：本站根据 Claude 官方《Thinking》 整理的示意图

一、先认识三个概念

• thinking：决定“思不思考”以及“用哪种方式”的开关；
• effort：决定整个回答“花多少力气”，在自适应模式下，也就决定了多久想一次、想多深；
• display：决定思考文字“要不要返回给你”。

官方特别强调：adaptive 是 thinking 的模式，不是 effort 的取值，别把它填进 effort。

图：本站根据 Claude 官方《Thinking》 整理的示意图

二、推荐写法：adaptive 加 display

官方示例的 Python 写法：

python
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",  # 以官方模型页当天为准
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "1071 和 462 的最大公约数是多少？",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print("思考摘要：", block.thinking)
    elif block.type == "text":
        print("回答：", block.text)

要点：

• 响应里会先出现 thinking 块，再出现 text 块；
• display: "summarized" 才会返回思考摘要，官方说明返回的永远是摘要，不是原始思维链；
• 如果模型觉得问题简单、没有思考，就不会产生 thinking 块，不管 display 怎么设；
• max_tokens 要给够，思考也占这个额度。

三、用 effort 控制深度

取值有 low、medium、high、xhigh、max，放在 output_config 里：

json
{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "high" }
}

Python 里对应 output_config={"effort": "high"}。官方说明的默认值：Sonnet 4.6 默认 high；Opus 5.5 和 Haiku 5.5 默认 medium；其他支持 effort 的模型默认 high。每个级别具体怎么影响思考、每个模型支持哪些级别，请看官方 Effort 页，本文不替官方列表。

官方给了一个选用思路：

• 想降成本、降延迟：先降 effort，它会把整个回答缩小，包括思考；
• Claude 想得太少或太浅：提高 effort；
• 想彻底关掉思考：用 thinking: {"type": "disabled"}，但只有部分模型接受；
• 想要硬性的费用上限：用 max_tokens，effort 只是软性指导。

四、各模型能设什么

官方的对照表很长，下面只摘常见的几类（完整表格以官方当天为准）：

关闭思考也有差别：Opus 5.5 不接受 disabled；Sonnet 5.5 不接受 disabled，最低档是 {"type": "between_tools"}，它关掉“回答前的思考”，但工具调用之间的简短说明仍以思考块的形式返回；Haiku 5.5 接受 disabled，但 effort 为 xhigh 或 max 时会报错。具体哪个模型怎么写，到官方对照表核对最稳。

五、旧写法：budget_tokens

仍在用 Claude 4.5 系列这类只支持旧写法的模型时，才需要它：

python
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "你的问题"}],
)

官方对预算的规则：

• 最小 1024 个 token，小于会被拒绝；
• 必须小于 max_tokens，因为思考计入 max_tokens，预算要给最终回答留位置（交错思考是例外）；
• 它是目标，不是严格上限，Claude 可能用不满预算；max_tokens 才是硬上限；
• 简单任务从接近 1024 起步，复杂任务从 16000 左右起步，再按延迟和质量调整；
• 预算超过 32k 时，官方建议改用批处理，避免长请求被网络掐断；
• 多轮缓存对话里，中途改 budget_tokens 会使缓存失效，所以选定后别乱改；
• 响应的 usage.output_tokens_details.thinking_tokens 能看到其中有多少是思考。

从旧写法迁移到新写法很简单：删掉 budget_tokens，把 type 改成 adaptive，用 effort 控制深度。官方提醒这不只是语法变化：旧写法每次都思考，自适应则由 Claude 判断，低 effort 时简单问题可能完全不思考。切换思考配置后的第一个请求会让缓存断点失效。

六、和工具调用一起用

用了思考又调用工具时，官方要求：把 thinking 块原样、完整地和对应的 tool_use 块一起传回去，不能改、不能删、不能重排，否则返回 400。官方强调即使 thinking 字段是空的也要传。工具调用基础见 /guides/claude-tool-use-basics。

另有几条限制（具体模型名单以官方当天为准）：

• Claude 4.6 及之后的模型不支持“预填”助手回复，会返回 400；
• 较新的模型上 temperature、top_p、top_k 取非默认值会返回 400；
• Opus 5.5、Sonnet 5.5、Fable 5.1 等不支持强制工具调用（tool_choice 的 any 或指定工具），用 auto 即可。

七、流式与计费

流式时，思考以 thinking_delta 事件出现，签名以一个 signature_delta 在块结束前发送，事件顺序见 /guides/claude-api-streaming。display 设为 omitted 时不流式发送思考文字，官方说这样正文开始得更早，但不会省钱，只省延迟。

费用上：思考 token 计入输出 token，对于“只返回摘要”的情况，账单按完整思考生成量算，而不是按你看到的摘要。在 Claude Opus 4.5 以及编号 4.6 及更高的模型上，之前轮次的思考块会保留在上下文里并按输入 token 计费，较早的模型会自动去掉。价格以官方价格页当天为准，估算上下文大小请用 /guides/claude-api-count-tokens。

常见问题

Q：报 "thinking.type.enabled" is not supported for this model？

你用的是 Claude 4.7 及之后的模型，旧写法已被移除。按上面的迁移，改成 adaptive 并用 effort 控制。

Q：报 adaptive thinking is not supported on this model？

你用的是只支持旧写法的模型（Claude 4.5 及更早），改回 enabled 加 budget_tokens，或换到支持 adaptive 的模型。

Q：报 thinking 块不能被修改？

工具调用后传回历史时，你改动或丢掉了 thinking 块，请原样传回，包括 redacted_thinking。其他 400 报错的整体排查见 /guides/claude-api-error-codes。

Q：模型怎么选？

见 /guides/claude-models-compare。

参考资料

• Claude 官方：Extended thinking — https://platform.claude.com/docs/en/build-with-claude/extended-thinking
• Claude 官方：Thinking — https://platform.claude.com/docs/en/build-with-claude/thinking
• Claude 官方：Claude API errors — https://platform.claude.com/docs/en/api/errors