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