思考功能疑難排解

本頁說明設定「thinking」（思考）或往返傳遞「thinking blocks」（思考區塊，即在後續請求中將傳回的思考區塊送回）時最常見的失敗情況。第一節列出每個模型支援的思考設定，以及會拒絕的設定。之後各節都從您觀察到的症狀出發，讓您能將錯誤訊息或非預期的回應直接對應到原因與修正方式。若要了解思考的運作方式，請參閱思考概覽。

各模型的思考支援、預設值與被拒絕的設定

大多數思考設定錯誤，都是請求中的 thinking.type 值與模型支援的內容不相符所致。在大多數模型上，思考功能以 thinking: {type: "adaptive"} 執行，且許多模型預設為開啟。部分較早的模型則改用擴展思考，這是一種舊版的手動模式，設定方式為 thinking: {type: "enabled", budget_tokens: N}。

「Extended thinking」（擴展思考）（thinking.type: "enabled" 搭配 budget_tokens）在 Claude 4.6 模型上已被棄用（使用它的請求仍會成功）。Claude 4.7 及更新的模型不支援它，並會拒絕使用它的請求，回傳 400 錯誤。在支援思考功能的 Claude 4.5 及更早的模型上，擴展思考是唯一可用的思考模式。Claude Mythos Preview 同時支援兩種模式。在兩種模式皆可用的情況下，請改用「adaptive thinking」（自適應思考）。

下表列出每個模型支援的內容、預設值，以及會以 400 錯誤拒絕的 thinking.type 值；未列為被拒絕的值皆可接受。只有 Claude Sonnet 5.5 接受 "between_tools"，且它以該值取代 "disabled"。

¹ enabled 與 budget_tokens 在這些模型上仍可運作，但已棄用；請改用自適應思考。
² Claude Opus 5 與 Claude Haiku 5.5 在 effort（投入程度）為 high 或以下時接受 "disabled"；將其與 effort xhigh 或 max 搭配使用會傳回 400 錯誤。在 Claude Opus 5 上，此限制會在每個請求中強制執行。在 Claude Haiku 5.5 上，與目前生效等級不同的逐訊息 effort 也會傳回 400 錯誤。
³ Claude Sonnet 5.5 在 effort 為 high 或以下時接受 "between_tools"。將其與 effort xhigh 或 max 搭配使用會傳回 400 錯誤，與目前生效等級不同的逐訊息 effort 也會如此。

標示為 永遠開啟 的模型無法關閉思考功能。標示為 開啟 的模型預設會進行思考。Claude Opus 5、Claude Sonnet 5 與 Claude Haiku 5.5 接受 thinking: {type: "disabled"}。在 Claude Sonnet 5.5 上，請傳送 thinking: {type: "between_tools"} 以關閉預先思考。

較早的 Claude 4 模型（Claude Opus 4.1、Claude Sonnet 4 與 Claude Opus 4）僅支援擴展思考。其可用性請參閱模型棄用。除非經 Anthropic 明確授權，否則 Claude Fable 5.1、Claude Mythos 5.1、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 來調整思考深度。遷移至自適應思考會逐步說明轉換方式。

傳送 thinking: {type: "disabled"} 後出現 400 錯誤

請求失敗並傳回 400 錯誤。在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Opus 5.5 與 Claude Mythos 5 上，訊息為：

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

在 Claude Mythos Preview（這些模型中唯一接受擴展思考的模型）上，訊息為：

"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.

這是因為這些模型的思考功能永遠開啟（請參閱各模型設定表）。

請省略 thinking 參數；這些模型無需任何設定即會進行思考。如果您的目的是讓回應中不包含思考文字，請使用 display: "omitted"，而非停用思考；請參閱控制思考顯示。

"disabled" 的 400 錯誤也可能發生在 Claude Opus 5 與 Claude Haiku 5.5 上，這兩個模型僅在 effort 為 high 或以下時接受 thinking: {type: "disabled"}：將其與 effort xhigh 或 max 搭配使用會被拒絕。請降低 effort 等級，或將 thinking 設為 {"type": "adaptive"}。

在 Claude Sonnet 5.5 上，thinking: {type: "disabled"} 在每個 effort 等級都會傳回 400 錯誤。訊息為：

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

若要在 Claude Sonnet 5.5 上關閉預先思考，請改為在 effort 為 high 或以下時傳送 thinking: {type: "between_tools"}。

400 錯誤指出不支援 "thinking.type.between_tools"

請求失敗並傳回 400 錯誤，其訊息內容為：

"thinking.type.between_tools" is not supported for this model.

發生此情況的原因是只有 Claude Sonnet 5.5 接受 thinking: {type: "between_tools"}（請參閱各模型設定表）。

請僅對 Claude Sonnet 5.5 傳送 between_tools。在其他模型上，請省略 thinking，或使用表中未列為被拒絕的 thinking.type 值。

400 錯誤指出停用思考時不支援某個 effort 等級

在 Claude Sonnet 5.5 上，以 effort xhigh 或 max 搭配 thinking: {type: "between_tools"} 的請求會失敗並傳回 400 錯誤，其訊息為：

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

這是因為 Claude Sonnet 5.5 僅在 effort 為 high 或以下時接受 between_tools。訊息之所以表示思考已停用，是因為 between_tools 沒有預先思考，即使請求並未傳送 "disabled"。訊息會指出請求所傳送的等級。

請將 effort 降低至 high 或以下。若要以 xhigh 或 max 執行，請使用自適應思考：省略 thinking 欄位或傳送 thinking: {"type": "adaptive"}。這就是訊息中「enable thinking」的意思。Claude Sonnet 5.5 會以 400 錯誤拒絕 "enabled"。

當請求以 effort xhigh 或 max 傳送 thinking: {type: "disabled"} 時，Claude Haiku 5.5 會傳回相同的訊息。它僅在 high 或以下時接受 "disabled"。請降低 effort，或將 thinking 設為 {"type": "adaptive"}。

400 錯誤指出停用思考時無法變更 effort

在 Claude Sonnet 5.5 上，使用 thinking: {type: "between_tools"} 且其每則訊息的 effort 變更了等級的請求會失敗並傳回 400 錯誤，其訊息為：

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

訊息之所以表示思考已停用，是因為 between_tools 沒有預先思考。使用 between_tools 時，effort 無法在對話中途變更：與目前生效等級不同的逐訊息 output_config.effort 會傳回 400 錯誤。messages.N 是設定新等級之訊息的位置。

請移除該逐訊息 effort，或將其設為目前生效的等級。若要在每個回合改變 effort，請使用自適應思考：省略 thinking 欄位，或傳送 thinking: {"type": "adaptive"}。這就是訊息中「enable thinking」的意思。

當使用 thinking: {type: "disabled"} 的請求設定了與目前生效等級不同的逐訊息 effort 時，Claude Haiku 5.5 會傳回相同的訊息。請移除該逐訊息 effort，或將 thinking 設為 {"type": "adaptive"} 以在每個回合改變 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 的正確程式碼請參閱工具與多輪工作流程中的思考中的完整往返範例。

400 錯誤指出思考區塊簽章無效

對 Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5 或 Claude Haiku 5.5 重播先前思考區塊的請求失敗並傳回 400 invalid_request_error，其訊息為：

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

如果請求未傳送 thinking-binding-controls-2026-08-01 beta 標頭，訊息會加上 That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

訊息通常以一句說明變更內容的句子結尾：system 提示、tools 清單、第一個不同的訊息或區塊、缺少或新增的內容，或是缺少或順序錯亂的先前思考區塊。該句子是供人員閱讀及寫入日誌之用。其措辭可能會變更，因此請勿在程式碼中比對它。

如果訊息在 Invalid `signature` in `thinking` block 之後就結束，表示簽章本身未通過驗證：它被截斷、遭到修改或以空值送回，且 prefix_mismatch_behavior 不適用。編輯過的思考文字會傳回不同的錯誤。請參閱400 錯誤指出思考區塊不可修改。

在 Claude Fable 5.1、Claude Opus 5.5、Claude Sonnet 5.5 與 Claude Haiku 5.5 上，只有在其之前的 system 提示、tools 與訊息保持不變時，API 才會接受重播的思考區塊。請參閱保持前綴不變。此錯誤表示對話中較早的某些內容在請求之間發生了變更：被編輯、重新排序或移除的回合、被注入後又移除的逐回合提醒、重新建構的 system 提示或 tools 陣列，或是原樣保留最近回合及其思考的用戶端壓縮。此檢查會對 2026 年 8 月 31 日當天或之後建立的新帳戶，以及任何設定了 thinking.block_binding.prefix_mismatch_behavior 的請求強制執行。伺服器端的壓縮與上下文編輯永遠不會觸發此檢查。

若要修正，請讓歷史記錄保持僅附加：將先前的回合完全依照傳送與接收時的樣子送回，使用對話中途系統訊息新增指示，而非編輯 system 或 tools，並讓伺服器端的上下文編輯或壓縮進行任何修剪。重試相同的請求主體無法清除此錯誤。若要在不使用已失效推理的情況下繼續此請求，請傳送 thinking-binding-controls-2026-08-01 beta 標頭，並將 thinking.block_binding.prefix_mismatch_behavior 設為 "drop_block"。或者，從歷史記錄中移除所有 thinking 與 redacted_thinking 區塊（至少移除被指出的區塊及其之後的每個區塊，包括該回合與所有後續回合），保留每個回合的其他區塊，然後重試一次。在 Claude Sonnet 5.5 與 Claude Haiku 5.5 上，block_binding 僅能搭配 thinking: {"type": "adaptive"} 使用。在 Claude Sonnet 5.5 上使用 between_tools，或在 Claude Haiku 5.5 上使用 thinking: {"type": "disabled"} 時，請讓歷史記錄保持僅附加，或從被編輯的回合起移除思考區塊。

來自目標模型無法讀取之模型的區塊永遠不會產生此錯誤：API 會捨棄它，並在使用 beta 標頭時於 input_transformations 中回報。

回應中的 thinking 欄位為空

回應包含 thinking 區塊，但其 thinking 欄位為空字串，只有 signature 欄位有值。

原因是在較新的模型上，display 預設為 "omitted"，會傳回不含文字的思考區塊。

請在思考設定中設定 display: "summarized"，以接收摘要後的思考文字。各模型的預設值請參閱控制思考顯示。如果您只想取得部分模型在工具呼叫之間寫出的簡短狀態行，而不需要推理內容，請改為設定 display: "updates"（beta）。請參閱工具呼叫之間的進度更新。

thinking 欄位為空的區塊仍然是完整的，推理內容保存在 signature 中。請像處理其他區塊一樣，將它隨回合一併送回。請參閱依原樣送回助理回合。

部分回合沒有出現思考區塊

即使已設定思考，部分回應仍完全不含 thinking 區塊。

這在自適應模式下屬於正常現象：當 Claude 判斷請求夠簡單、可以直接回答時，就會略過思考。

如果您希望 Claude 更頻繁或更深入地思考，請提高 effort 或透過提示加以引導；請參閱引導 Claude 的思考頻率。

強制的 tool_choice（{"type": "any"} 或指定的工具）也不會傳回 thinking 區塊：回應會以工具呼叫開始。若要讓模型在呼叫工具前先思考，請使用 tool_choice: {"type": "auto"}，並在提示中說明何時使用該工具。

文字輸出中出現工具呼叫或 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 會與預算共同作用；請參閱預算規則與調整。

後續步驟