思考疑難排解

本頁涵蓋配置思考或往返傳遞思考區塊（將回傳的思考區塊在後續請求中送回）時最常見的失敗情況。第一節列出每個模型支援的思考配置以及它會拒絕的配置；之後的各節都從您觀察到的症狀開始，讓您可以將錯誤訊息或非預期的回應直接對應到其原因和修復方法。關於思考的運作方式，請參閱思考概覽。



各模型拒絕的配置

大多數思考配置錯誤是請求中的 thinking.type 值與模型支援的內容不匹配。在目前的模型上，思考以 thinking: {type: "adaptive"} 執行，而在最新的模型上它預設為開啟。某些較早的模型則使用 extended thinking（擴展思考），這是一種舊式的手動模式，配置為 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 等級來控制 token 成本。如果您的整合必須保持停用思考，請套用在停用思考的情況下執行中的提示緩解措施。



回應以 stop_reason: "max_tokens" 停止

回應以 stop_reason: "max_tokens" 結束，通常伴隨被截斷或缺失的文字區塊。

這是因為思考 token 會計入 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 會與預算組合；請參閱預算規則與調整。



後續步驟