思考

一個以單次處理回答的模型必須在第一次嘗試時就把所有事情做對：沒有草稿、沒有檢查、也無法在中途改變方向。對於一個證明、一個棘手的錯誤，或一項長時間的代理任務而言，第一種做法往往不是最好的做法。

「Thinking」（思考）移除了這項限制。當思考處於啟用狀態時，Claude 會在回答之前先用自己的話把問題推演一遍：它會重述被詢問的內容、嘗試各種做法、檢查中間結果，並放棄站不住腳的路徑。這些推理會以 thinking 內容區塊的形式出現在回應之前，而 Claude 會依據它來產生最終答案。這就是為什麼思考能提升數學、程式設計、分析以及長時間代理工作等複雜任務的表現——在這些任務中，答案的品質取決於中間工作，而這些中間工作原本會被壓縮進回應本身或被略過。

思考是有成本的：Claude 花在推理上的 token 會以輸出 token 計費，即使思考文字並未回傳給您也是如此，而且它們會與回應文字一起計入 max_tokens。本頁涵蓋思考在整個 API 介面上的行為：如何開啟、如何讀取其輸出，以及如何管理它與工具、串流、快取和「context window」（上下文視窗）之間的互動。

思考如何運作

Claude 是否會針對某個請求進行思考，以及思考的深度，取決於您的思考設定與請求的複雜度。

以下是思考在回應中的樣貌：一個或多個 thinking 內容區塊會在 text 區塊之前抵達。thinking 區塊仍然是生成的內容，就像其後的 text 區塊一樣，但它與正式回應是分開的。每個 thinking 區塊還帶有一個 signature 欄位，這是完整推理的加密副本，您在多輪對話與工具使用對話中需原封不動地傳回（請參閱思考加密）：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

您不一定總是會看到這段文字，而且您看到的永遠不是原始的思維鏈：thinking 區塊中的文字是 Claude 推理的摘要。思考設定上的 display 欄位控制是否回傳該摘要："summarized" 會回傳它，而 "omitted"（許多模型的預設值）則會回傳 thinking 欄位為空的 thinking 區塊。無論哪種方式，該區塊的計費方式相同，在多輪對話中傳回的方式也相同。各模型的預設值與詳細資訊請參閱控制思考顯示。

如果 Claude 使用工具，思考也可能出現在工具呼叫之間。請參閱搭配工具使用的思考。完整的回應格式請參閱 Messages API 參考文件。

設定思考

在大多數模型上，思考預設為開啟，或只需一個參數即可開啟。每個模型接受哪種設定以及其預設值，列於疑難排解頁面的各模型設定表中。

在 Claude Opus 5、Claude Sonnet 5、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 上，思考已經開啟，無需設定。這些模型上的 display 預設為 "omitted"，因此在您選擇啟用之前，思考文字是隱藏的。使用 thinking: {"type": "adaptive", "display": "summarized"} 來選擇啟用，這與下方的請求完全相同，只需替換模型字串。

在 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 上，思考在您設定 thinking: {type: "adaptive"} 之前是關閉的；該設定讓 Claude 根據請求自行決定何時思考以及思考多深。以下範例即如此設定，並設定 display: "summarized" 讓思考文字可見，同時使用寬裕的 max_tokens：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

執行此範例會先印出摘要思考，然後印出答案：

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

思考 token 會計入 max_tokens，因此請將其設得夠高，以便為思考與回應文字都留出空間。請參閱引導頁面上的成本控制以及思考與上下文視窗。

關閉思考

在思考預設為開啟的 Claude Sonnet 5 上，您可以將其關閉：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "Summarize this article in one sentence."}],
)

Claude Opus 5 同樣預設開啟思考，並在 effort 為 high 或以下時接受 thinking: {type: "disabled"}。在 xhigh 或 max effort 下，思考無法關閉：將 thinking: {type: "disabled"} 與這些 effort 等級組合的請求會回傳 400 錯誤。此限制適用於 Claude Opus 5 及之後的模型，並在每個請求上強制執行。在停用思考的情況下，Claude Opus 5 偶爾會以純文字形式輸出工具呼叫，或在其可見輸出中包含內部 XML 標籤。提示方面的緩解方法請參閱在停用思考的情況下執行。

Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview 會拒絕 thinking: {type: "disabled"}。這些模型上的思考無法關閉。

如果您的模型僅支援「extended thinking」（擴展思考）（請參閱各模型設定表），請改用 type: "enabled" 搭配 budget_tokens 值來設定。擴展思考頁面涵蓋該設定。如果任何思考設定回傳 400 錯誤，思考疑難排解會將每則錯誤訊息對應到其修正方法。

讀取思考輸出

控制思考顯示

思考設定上的 display 欄位控制思考內容在 API 回應中的回傳方式。display 在兩種模式下皆可運作：可與 type: "adaptive" 或 type: "enabled" 一起設定。它接受以下值：

• "summarized"：thinking 區塊包含摘要思考文字，即 Claude 推理的可讀摘要。這是 Claude Opus 4.6、Claude Sonnet 4.6 及更早模型的預設值。
• "omitted"：thinking 區塊以空的 thinking 欄位回傳。signature 欄位仍帶有加密的完整思考，以維持多輪連續性（請參閱思考加密）。這是 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Mythos Preview 的預設值。
• "updates"（beta）：推理區塊以空的 thinking 欄位回傳，與 "omitted" 相同，而某些模型在工具呼叫之間撰寫的簡短進度更新則以可讀文字回傳。需要 beta 標頭 thinking-display-updates-2026-08-18。

當您的應用程式不向使用者呈現思考內容時，請設定 display: "omitted"。主要好處是串流時更快的首個文字 token 時間：伺服器會完全略過串流思考 token，只傳送 signature，因此最終文字回應會更早開始串流。

使用 display: "omitted" 時，回應包含 thinking 欄位為空的 thinking 區塊：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

處理省略的思考時，請記住以下幾點：

• 您仍需支付完整思考 token 的費用。省略可降低延遲，而非成本。
• 如果您在多輪對話中傳回 thinking 區塊，請原封不動地傳回。伺服器會解密 signature 以重建原始思考來建構提示（請參閱保留 thinking 區塊）。您放在往返傳回的省略區塊之 thinking 欄位中的任何文字都會被忽略。
• display 與 thinking.type: "disabled" 搭配無效（沒有東西可顯示）。
• 使用 thinking.type: "adaptive" 且模型對簡單請求略過思考時，無論 display 為何，都不會產生 thinking 區塊。
• 以 display: "omitted" 串流時，不會發出 thinking_delta 事件。使用 display: "updates" 時，只有進度更新區塊會串流 thinking_delta 事件。事件順序請參閱串流思考。

在 Ruby SDK 中，純雜湊如範例所示使用 display:。具型別的 ThinkingConfigAdaptive 類別將此參數命名為 display_（尾端底線，以避免遮蔽 Ruby 的 Kernel#display）。無論哪種方式，傳輸欄位仍為 display。

摘要思考

當 display 為 "summarized" 時，您收到的思考文字是 Claude 完整思考過程的摘要，而非原始思維鏈。摘要思考提供思考的完整智慧效益，同時防止濫用。沒有任何 display 設定會回傳原始思維鏈。

處理摘要思考時，請記住以下幾點：

• 您需支付原始請求所產生的完整思考 token 費用，而非摘要 token。計費的輸出 token 數與您在回應中看到的 token 數不一致。
• 在 Claude Opus 4.6、Claude Sonnet 4.6 及更早的模型上，思考輸出的前幾行較為詳盡，提供對提示工程特別有幫助的詳細推理。Claude Mythos Preview 從第一個 token 就開始摘要，因此其 thinking 區塊不會顯示這段詳盡的前言。
• 摘要保留了 Claude 思考過程的關鍵想法，且增加的延遲極小，因此摘要可以在抵達時即時串流。
• 摘要由與您請求所指定的模型不同的模型處理。思考模型看不到摘要輸出。
• 隨著 Anthropic 持續改進思考功能，摘要行為可能會有所變更。

若要查看模型的推理，請讀取 thinking 區塊，而非在回應文字中提示要求推理。在 Claude Fable 5.1 和 Claude Fable 5 上，試圖將模型的內部推理作為回應文字一部分引出的請求，可能會以 stop_details.category: "reasoning_extraction" 被拒絕。欄位參考與處理指引請參閱拒絕類別。

串流思考

思考可與串流搭配使用。thinking 區塊以 content_block_delta 事件內的 thinking_delta 事件串流，接著在該區塊的 content_block_stop 之前會有單一個 signature_delta 事件。text 區塊隨後照常串流。

以下範例以自適應思考串流回應，並在 thinking 與 text delta 抵達時印出：

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

若要在串流後重新組合帶有 signature 的完整 thinking 區塊，請使用您 SDK 的訊息累積輔助函式（若有提供，例如 Python 中的 stream.get_final_message() 或 TypeScript 中的 stream.finalMessage()），而非自行串接 delta。

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

設定 display: "omitted" 時，thinking 區塊開啟，單一個 signature_delta 抵達，然後該區塊在沒有任何 thinking_delta 事件的情況下關閉。文字串流隨即開始：

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

使用 display: "updates"（beta）時，推理區塊的串流方式與 "omitted" 下相同。每個進度更新區塊會在其所引介的 tool_use 區塊之前，以 thinking_delta 事件串流其文字。在進度更新區塊開啟前出現數秒的停頓是正常的：

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}}

在 "updates" 下，只要某個區塊的任一 thinking_delta 事件帶有非空文字，就將該區塊視為進度更新。

一般串流機制請參閱串流訊息。

思考與 effort

thinking 參數控制 Claude 是否在回答之前於思考區塊中進行思考；effort 參數則控制 Claude 在整個回應中投入多少工作量，在自適應模式下，這包括它思考的頻率與深度。請勿將 adaptive 作為 effort 的值傳入：adaptive 是一種思考模式，而非努力程度等級。

若要了解每個 effort 等級對思考行為的影響，請參閱引導思考頁面上的各等級思考行為表。Effort 頁面記載了該參數本身，包括每個模型支援哪些等級。在 Claude Opus 4.5（唯一支援 effort 的僅擴展思考模型）上，effort 與 budget_tokens 組合運作。請參閱預算規則與調校。

這兩項控制如此分開後，請選擇符合您目標的那一項：

• **在啟用思考的工作負載上降低成本或延遲：**先降低 effort。它會縮減整個回應，包括思考。
• **Claude 思考得太少或太淺：**提高 effort，或參閱引導頁面上的引導 Claude 思考的頻率。
• **您需要完全關閉思考：**在允許的模型上使用 thinking: {type: "disabled"}（請參閱各模型設定表）。
• **您需要支出的硬性上限：**使用 max_tokens。Effort 是軟性指引。max_tokens 是嚴格限制。

搭配工具使用的思考

思考可與工具使用並行運作，讓 Claude 推理工具選擇並處理工具結果。有兩項限制：

1. **工具選擇限制（手動模式）：**搭配手動擴展思考（thinking: {type: "enabled"}）的工具使用僅支援 tool_choice: {"type": "auto"}（預設值）或 tool_choice: {"type": "none"}。使用 tool_choice: {"type": "any"} 或 tool_choice: {"type": "tool", "name": "..."} 會導致錯誤，因為這些選項會強制工具使用，而這與手動擴展思考不相容。自適應思考（包括在思考預設開啟的模型上）支援強制工具使用，但 Claude Fable 5.1 和 Claude Mythos 5.1 除外（請參閱回應預填與強制工具使用）。
2. **保留 thinking 區塊：**當您回傳工具結果時，必須將助理訊息中的 thinking 區塊完整且未經修改地傳回 API。請參閱保留 thinking 區塊。

**一個工具使用迴圈是一個助理輪次。**從模型的角度來看，助理輪次要到 Claude 完成其完整回應才算結束，而這可能包含多次工具呼叫與結果。以下整個序列是單一個助理輪次：

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

整個輪次以單一思考模式執行：您無法在輪次中途切換思考，包括在工具使用迴圈期間。在擴展（手動）模式下，API 還會強制要求啟用思考之請求的最後一個助理輪次以 thinking 區塊開頭。自適應模式放寬了這一點：沒有任何助理輪次需要以 thinking 區塊開頭。

**輪次中途的衝突會優雅降級。**如果您在輪次中途切換思考（例如在送出工具呼叫與回傳其結果之間），API 不會報錯。相反地，它會靜默地為該請求停用思考。為了維持模型品質，API 可能會移除會造成無效輪次結構的 thinking 區塊，或在對話歷史與啟用思考不相容時停用思考。若要確認思考是否處於啟用狀態，請檢查回應中是否存在 thinking 區塊。

**在輪次之間切換，而非在輪次之內。**在每個輪次開始時規劃您的思考策略。完成助理輪次，然後為下一個輪次變更思考設定：

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

切換思考模式也會使提示快取失效。請參閱思考與提示快取。

保留 thinking 區塊

當 Claude 呼叫工具時，它會暫停建構其回應以等待外部資訊。當您回傳工具結果時，Claude 會繼續建構同一個回應，因此其先前的推理必須仍然存在。請將每個 thinking 區塊連同其伴隨的 tool_use 區塊，完整且未經修改地傳回 API。這很重要，原因有二：

1. **推理連續性：**thinking 區塊記錄了導向工具請求的逐步推理。包含它們可讓 Claude 從中斷處繼續推理。
2. **上下文維持：**工具結果在 API 結構中以使用者訊息的形式出現，但它們是一個連續推理流程的一部分。保留 thinking 區塊可在各次 API 呼叫之間維持該流程。

簡而言之：

• **必要：**在工具使用輪次內，傳回 thinking 區塊。
• **建議：**跨輪次時，傳回所有內容。
• **允許：**在工具使用之外，省略先前輪次的思考。

您不需要自行修剪舊的思考。在多輪對話中傳回所有 thinking 區塊，API 會自動過濾它們、保留維持模型推理所需的區塊，並僅對實際呈現給 Claude 的區塊計收輸入 token。保留哪些先前輪次的區塊因模型而異。請參閱各模型的 thinking 區塊保留。若要覆寫預設值，請使用 clear_thinking_20251015 上下文編輯策略。

在最新的助理訊息中，連續 thinking 區塊的序列必須與模型在原始請求中產生的內容一致：您不能重新排列、編輯或部分捨棄它們。這包括 redacted_thinking 區塊。

如需包含各 SDK 程式碼的完整兩輪逐步說明，請參閱工具與多輪工作流程中的思考。它定義一個工具、接收一個思考加工具使用的回應，並將助理輪次連同工具結果回傳。

交錯思考

「Interleaved thinking」（交錯思考）讓 Claude 在工具呼叫之間思考，在對每個工具結果採取行動之前先進行推理。透過交錯思考，Claude 可以：

• 在決定下一步之前，先推理工具呼叫的結果
• 串接多次工具呼叫，並在其間加入推理步驟
• 根據中間結果做出更細緻的決策

使用自適應思考時，交錯思考在每個支援自適應思考的模型上都是自動的。不需要 beta 標頭。在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5、Claude Opus 4.8 和 Claude Opus 4.7 上，工具呼叫之間的推理一律出現在 thinking 區塊中。Claude Haiku 4.5 不支援交錯思考。在使用手動擴展思考的模型上，交錯需要 beta 標頭，並會改變思考預算的計算方式。手動模式下的交錯思考涵蓋各模型的規則與平台特定的標頭行為。

使用交錯思考時，思考配額可以橫跨整個助理輪次，而非單一回應。交錯思考僅支援透過 Messages API 使用的工具。

如需展示交錯思考在雙工具工作流程中改變了什麼的實作比較，請參閱交錯思考如何改變流程。

工具呼叫之間的進度更新

在 Claude Fable 5.1、Claude Mythos 5.1 和 Claude Fable 5 上，模型可以在工具呼叫之間撰寫「progress update」（進度更新）。進度更新是一兩句話，說明模型剛發現了什麼以及接下來要做什麼，是寫給觀看代理的人看的，而非作為推理。每則進度更新都以各自的 thinking 區塊回傳，帶有各自的 signature，與同一位置的任何推理區塊分開。它緊接在其所引介的 tool_use 或 server_tool_use 區塊之前。每次工具呼叫之前最多有一則進度更新，且模型可以略過其中任何一則。進度更新不是交錯思考：無論工具呼叫之間是否出現推理區塊，它們都會出現，而且一個回應可以同時包含兩者。

進度更新區塊包含什麼取決於 display：

對於隱藏推理並在每個步驟向使用者顯示狀態列的代理介面，請使用 display: "updates"。在此設定下，任何帶有非空文字的 thinking 區塊都是進度更新，因此只呈現這些區塊即可。它處於 beta 階段，需要 beta 標頭 thinking-display-updates-2026-08-18（在 Amazon Bedrock、Google Cloud 和 Microsoft Foundry 上，請依 Beta 標頭所述傳遞 beta 值）。若沒有該標頭，此值會以與未知 display 值相同的 400 invalid_request_error 被拒絕。

{
  "model": "claude-fable-5-1",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": [
    {
      "name": "edit_file",
      "description": "Replace the contents of a file in the repository.",
      "input_schema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "The login test fails after an hour of uptime. Find out why and fix it."
    }
  ]
}

在 "updates" 下，接在 tool_result 之後的回應開頭如下所示。第一個區塊是推理並保持為空，如同在 "omitted" 下一樣。第二個區塊帶有文字，因此它是進度更新。在 "summarized" 下兩個區塊都帶有文字，而在 "omitted" 下兩者皆為空。

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EqMBCkYICxIM..."
    },
    {
      "type": "thinking",
      "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.",
      "signature": "Es8CCkYICxIM..."
    },
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "edit_file",
      "input": { "path": "auth.py", "content": "..." }
    }
  ]
}

處理進度更新時，請記住以下幾點：

• 將進度更新區塊連同助理輪次的其餘部分原封不動地傳回，如同任何其他 thinking 區塊。
• 您收到的文字是進度更新的摘要，通常為一兩句話。不要依賴其長度。進度更新以其完整長度計入 usage.output_tokens，而非摘要的長度。
• 在任何 display 值下，進度更新區塊都可能以空的 thinking 欄位回傳。對空區塊不呈現任何內容。在 "updates" 下，它看起來與空的推理區塊相同，不需要另外處理。
• 當回應在工具呼叫或工具結果之後不久因 max_tokens、model_context_window_exceeded 或 stop_sequence 而停止時，其最後一個區塊可能是代表模型尚未完成之工作的進度更新區塊。在 "updates" 和 "summarized" 下，其文字恰為 This part of the response was interrupted before it finished.，您可以像任何其他更新一樣顯示它。在 "omitted" 下它是空的。若要繼續，請原封不動地傳回助理輪次並附加一則新的 user 訊息（為該輪次中的每個 tool_use 區塊附上一個 tool_result）。
• 串流時，預期在進度更新區塊開啟前會有數秒的停頓。請參閱串流思考中的 "updates" 追蹤。
• 這些模型在較高的 effort 下以及在長工具鏈中撰寫的進度更新較少。如果您的介面依賴它們，請參閱要求面向使用者的進度更新。

各模型的 thinking 區塊保留

先前助理輪次的 thinking 區塊是否預設保留在上下文中，取決於模型：

• **保留所有先前輪次：**Claude Opus 4.5 及之後的 Opus 模型、Claude Sonnet 4.6 及之後的 Sonnet 模型、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5 和 Claude Mythos Preview。
• **僅保留最後一個輪次：**更早的 Opus 和 Sonnet 模型，以及直到 Claude Haiku 4.5 的所有 Haiku 模型。當您傳回較舊的 thinking 區塊時，API 會自動移除它們。您不需要自行移除。

保留帶來兩項好處：

• **快取最佳化：**保留的 thinking 區塊可在工具使用期間實現快取命中，因為它們會連同工具結果一起傳回，並在整個助理輪次中逐步快取，從而在多步驟工作流程中節省 token。
• **不影響智慧：**保留 thinking 區塊對模型表現沒有負面影響。

代價是上下文用量：在保留全部的模型上，長對話會消耗更多上下文空間，因為保留的 thinking 區塊與任何其他對話歷史一樣計為輸入（請參閱思考與上下文視窗）。兩種機制下的行為都是自動的。不需要變更程式碼或 beta 標頭，您應如保留 thinking 區塊所述，持續傳回完整、未經修改的 thinking 區塊。若要朝任一方向覆寫預設值，請使用 thinking 區塊清除。

**對話中途切換模型。**切換模型時（例如在分類器拒絕回退之後），請持續原封不動地傳回 thinking 區塊。thinking 區塊只能由產生它的模型或更新的模型讀取，而 API 會忽略或捨棄目標模型無法讀取的區塊。在 Claude Fable 5.1 和 Claude Mythos 5.1 上，方向很重要：它們能讀取每個更早模型的 thinking 區塊，而沒有任何更早的模型能讀取它們的區塊，因此向上切換到它們會保留對話的推理，向下切換則會捨棄（確切清單以及被捨棄區塊的計費與回報方式請參閱保留的思考）。僅在為了在會忽略而非捨棄區塊的模型上節省輸入 token 時，才自行移除先前的 thinking 和 redacted_thinking 區塊；而在兌換回退額度時絕不要這麼做，因為那要求請求主體保持不變。

保留的思考

Claude 僅在 thinking 區塊建立時的條件下保留該區塊，使其在後續輪次中可用。從 Claude Fable 5.1 和 Claude Mythos 5.1 開始，thinking 或 redacted_thinking 區塊僅在以下情況下被保留：

• **對產生它的模型或更新的模型。**更早的模型無法使用該區塊，API 會將其從該請求中捨棄。請參閱僅對產生它的模型或更新的模型。
• **在產生它的對話中（僅限 Claude Fable 5.1）。**如果 system 提示、tools 或任何更早的訊息有所變更，該區塊即不再有效，API 會拒絕請求或捨棄該區塊。請參閱僅在產生它的對話中。

在這兩個模型上，區塊的 signature 都記錄了這兩項條件。每當該區塊在後續請求中傳回時（包括對不同模型的請求），API 都會檢查它；Claude Mythos 5.1 僅檢查模型條件。

**原封不動地傳回區塊。**將每個助理輪次完全按照您收到的樣子送出，包括 thinking 區塊，並讓 API 決定模型可以使用哪些區塊。

僅對產生它的模型或更新的模型

此條件是單向的：Claude Fable 5.1 和 Claude Mythos 5.1 能讀取更早模型的 thinking 區塊，而沒有任何更早的模型能讀取它們的區塊。

• **移至 Claude Fable 5.1 或 Claude Mythos 5.1 的對話會保留其推理。**更早模型的 thinking 區塊仍可讀取，因此模型從切換後的第一個輪次起照常思考。
• **從它們移至任何更早模型的對話會失去推理。**更早的模型無法讀取它們的區塊，API 會為該請求捨棄這些區塊，而更早的模型會從可見訊息重新推理。如果對話之後以相同的歷史回到 Claude Fable 5.1，其自身的區塊會再次可讀。

完整而言，Claude Fable 5.1 和 Claude Mythos 5.1 能讀取彼此產生的 thinking 區塊，以及由 Claude Opus 5、Claude Fable 5 和 Claude Mythos 5 產生的區塊，還有由 Claude Opus 4.8 及更早的 Opus 模型、Claude Sonnet 模型和 Claude Haiku 4.5 產生的區塊。除了這兩個模型之外，沒有任何模型能讀取由 Claude Fable 5.1 或 Claude Mythos 5.1 產生的區塊。

**接收模型無法讀取的區塊會被捨棄。**API 會在提示到達模型之前將其移除。它不計入 input_tokens，也不計費。當您在對話中途從 Claude Fable 5.1 回退到較舊的模型時（例如在分類器拒絕回退之後），較舊的模型會從可見對話重新推理。使用控制 beta 標頭時，捨棄會在 input_transformations 中以 model_binding_mismatch 回報。若沒有該標頭，捨棄是靜默的。伺服器端回退以相同方式捨棄無法讀取的區塊。

僅限於產生它的對話中

來自 Claude Fable 5.1 的思考區塊，只有在產生它的對話前綴保持不變時才會被保留。其 signature 涵蓋了 system 提示、tools，以及該區塊之前的訊息。Claude Mythos 5.1 會記錄相同的 signature，但不會執行此檢查。

此檢查對於 2026 年 8 月 31 日當天或之後建立的新帳戶強制執行。對於更早建立的帳戶，API 會在簽章中記錄此條件，但除非請求設定了 thinking.block_binding.prefix_mismatch_behavior（選擇加入強制執行），否則不會對不符的情況採取行動。Anthropic 計劃在未來的模型上對每個組織強制執行此條件。如果您的帳戶是更早建立的，請現在就讓您的應用程式相容：相同的僅附加（append-only）模式可讓提示快取保持熱狀態，而且您可以透過傳送 prefix_mismatch_behavior: "error" 來針對此檢查進行測試。如果您發布的是供他人以自己的 API 金鑰執行的工具或框架，請以這種方式測試：您在新帳戶上的使用者會比您更早受到強制執行。保留的思考提供了整合檢查清單：如何判斷您的程式碼是否編輯了歷史記錄，以及取代每種編輯的 API 功能。

在強制執行此檢查的情況下，針對已變更的前綴重播區塊的請求會被拒絕，並回傳 400 invalid_request_error：

messages.5.content.0: 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". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

最後一句僅在請求未傳送 beta 標頭時出現。訊息結尾可能會再多一句，指出第一個發生變更的訊息。重試相同的請求主體會以相同方式失敗。若要改為在不使用已失效推理的情況下繼續，請傳送 thinking-binding-controls-2026-08-01 beta 標頭，並將 prefix_mismatch_behavior 設為 "drop_block"。API 隨後會丟棄失敗的區塊以及對話中其後的每個思考區塊，並在 input_transformations 中將每一個回報為 prefix_binding_mismatch。權杖計數端點會執行相同的檢查並回傳相同的 400。

會使後續思考區塊失效的情況：

• 編輯、重新排序或移除較早的訊息，包括移除您注入到較早使用者輪次中的每輪提醒。
• 在請求之間變更頂層 system 提示的內容，或在 tools 陣列中新增、移除或編輯工具。
• 用戶端壓縮或截斷，逐字保留最近的助理輪次（包括思考），同時重寫它們之前的輪次。
• 較早輪次中的圖片或文件 URL 在後續請求中提供了不同的位元組。此檢查涵蓋的是位元組，而非 URL 字串，因此同一檔案的輪替簽署 URL 沒有問題。對於您跨輪次參照的內容，請使用 Files API 上傳一次並傳送 file_id，或傳送 base64。

不會使其失效的情況：

• 從最舊的開始，移除開頭連續的一段思考區塊：對話中的第一個思考區塊（或最近一次壓縮區塊之後的第一個），然後是下一個，依此類推。從其他任何位置移除思考區塊，會使其後的每個思考區塊失效，包括該輪次及之後每個輪次中的區塊。
• 在請求之間變更 output_config.effort、max_tokens 或其他取樣設定。
• cache_control 標記，無論您將它們放置或移動到何處。
• 伺服器端壓縮和上下文編輯：它們不算作編輯，因為此檢查比較的是您所傳送的對話，而非伺服器編輯後的副本。壓縮之後，受檢查的前綴從壓縮區塊開始。

讓思考區塊保持有效的模式：

• 僅附加。 在 messages 的末尾新增訊息，並讓較早的輪次逐位元組保持不變。
• **使用對話中途系統訊息**和對話中途工具變更，在中途新增指示或變更工具可用性，而不是編輯頂層 system 欄位或 tools 陣列。對於只應套用於單一輪次的提醒，請將其作為輪次範圍系統訊息傳送，並將其留在歷史記錄中，而不是稍後刪除。這也能保留提示快取。
• 使用伺服器端上下文管理，而不是自行修剪歷史記錄。
• **如果請求因前綴不符而被拒絕，且您無法修復歷史記錄，**請附上 beta 標頭和 prefix_mismatch_behavior: "drop_block" 重新傳送，或從歷史記錄中移除每個 thinking 和 redacted_thinking 區塊並重試一次。

當較早的思考被丟棄時，模型會在沒有這些區塊的情況下回答該輪次。反覆使自身歷史記錄失效的用戶端每次都會重新啟動提示快取，這會提高成本。

用戶端壓縮。 此檢查並不排除在用戶端進行壓縮。規則更為狹窄：不要在您已重寫的前綴之後保留思考區塊。伺服器端壓縮是滿足此規則最簡單的方式。如果您在用戶端進行壓縮，請使用以下其中一種形式：

• 簡單壓縮（建議）： 將對話摘要為一則訊息，並以該摘要加上新的使用者輪次開始下一個請求，不重播任何較早的輪次，也不重播任何較早的思考區塊。沒有較早的思考留存，因此不會有任何失敗，模型會在壓縮後的對話上重新思考。Claude 模型是以此方案在長時程任務上訓練的，對於大多數工作負載，其表現與更複雜的方案相當。它會重設提示快取，任何壓縮都是如此。
• 保留尾端壓縮： 摘要較舊的輪次，並逐字保留最近的輪次。被保留輪次的思考區塊是針對完整歷史記錄產生的，在摘要之後會失敗。請從您帶過去的每個輪次中移除 thinking 和 redacted_thinking（其文字和工具呼叫可以保留），或設定 prefix_mismatch_behavior: "drop_block" 並讓 API 丟棄它們。
• 背景壓縮： 在關鍵路徑之外建立摘要，並在對話繼續進行時將其換入。在此期間產生的每個輪次，其思考都早於換入時間。請在每個仍帶有換入前所產生思考區塊的請求上傳送 "drop_block"（或自行移除這些區塊；換入後第一個回應上的 input_transformations 會精確列出是哪些區塊），或同步進行壓縮。

從逐字稿中間剪除個別輪次會使其後的每個思考區塊失效，沒有任何用戶端形式可以避免這一點。對於您原本要進行的指示變更，請使用對話中途系統訊息；對於選擇性移除，請使用伺服器端上下文編輯。

未保留區塊的控制項（beta）

傳送 beta 標頭 thinking-binding-controls-2026-08-01 可獲得兩項功能：每個回應上的 input_transformations 陣列，列出 API 丟棄的任何思考區塊；以及思考設定上帶有一個欄位的 block_binding 物件。

block_binding 可與 thinking.type: "adaptive" 和 thinking.type: "enabled" 一起使用。在沒有 beta 標頭的情況下傳送它會回傳 400 錯誤。不執行對話檢查的模型會接受此物件，並僅回報模型檢查的丟棄，因此同一個請求主體可跨模型使用。在 Amazon Bedrock 和 Google Cloud 上，請依照 Beta 標頭中的說明傳遞 beta 名稱。

以下請求選擇丟棄而非拒絕。在第一個輪次中沒有任何內容可重播，因此 input_transformations 回傳為空：

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

The greatest common divisor of 1071 and 462 is 21.
Input transformations: 0

被丟棄的區塊會在 input_transformations 中回報。 在 beta 標頭下，來自具備思考能力模型的每個回應都帶有此頂層陣列。當沒有任何內容被丟棄時它為空，且永遠不會是 null。每個項目會指出被丟棄區塊的位置及其未通過的檢查：

{
  "input_transformations": [
    {
      "type": "thinking_dropped",
      "path": "messages.1.content.0",
      "reason": "model_binding_mismatch"
    }
  ]
}

reason 欄位為 model_binding_mismatch 或 prefix_binding_mismatch。請忽略您無法辨識其 type 或 reason 的項目，因為後續的檢查會新增值。在串流時，input_transformations 會出現在 message_start 事件中的 message 物件上。在串流中途發生伺服器端回退之後，最終的 message_delta 事件會再次帶有此陣列，其中包含實際提供服務之模型的項目。沒有 beta 標頭時，此欄位不存在。

遭竄改或無法解密的簽章是另一種失敗：它一律回傳 400（Invalid `signature` in `thinking` block，不帶原因子句），且 prefix_mismatch_behavior 不適用於它。在訊息批次中，其區塊在 "error" 下未通過對話檢查的項目會解析為 errored。

思考與提示快取

提示快取（prompt caching）與思考有幾種特定的互動方式。以下規則適用於兩種思考模式。

設定變更會使快取失效。 思考設定和解析後的 effort 等級會被渲染到提示本身之中，因此變更其中任何一項都會開始一個新的快取前綴。在 adaptive、enabled 和 disabled 之間切換、變更 budget_tokens，以及變更 effort 值，都會使快取斷點失效：訊息層級的斷點一律未命中，而工具和系統提示的斷點也可能未命中，取決於模型在何處渲染設定。請將任何思考或頂層 effort 變更視為重新開始快取。在支援每則訊息 effort 的模型上，在 messages 內以 role: "system" 訊息攜帶的 effort 變更會讓已快取的前綴保持完整。保持相同設定的連續請求會保留快取，而將參數明確設為其預設值等同於省略它。API 在任一保留思考條件下丟棄的思考區塊，會從該區塊的位置起變更已快取的前綴。原封不動傳回的區塊會讓快取保持完整。附有用量輸出的實作示範位於引導思考頁面。

思考區塊會與工具結果一起快取。 在工具使用迴圈期間，當您發出包含工具結果的後續請求時會發生快取。此時先前的對話歷史記錄（包括其思考區塊）可以被快取，而這些已快取的思考區塊在從快取讀取時，會在您的用量指標中計為輸入權杖。即使沒有明確的 cache_control 標記，這也會自動發生，且對於一般思考和交錯思考的行為相同。取捨在於：您在回應中再也不會看到的思考區塊，在從快取讀取時仍會計入輸入權杖用量。

先前的區塊是否在上下文中，依模型而定。 保留預設值決定了這一點。在保留全部的模型上，先前輪次的思考區塊會保持快取並留在上下文中。在僅保留最後輪次的模型上，一旦您傳送了不是工具結果的使用者訊息，所有先前的思考區塊都會從上下文中移除。在這些模型上，像這樣的對話：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

會被當作思考區塊從未存在一樣處理：

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

在保留全部的模型上，相同的請求會將 thinking_block_1 和 thinking_block_2 保留在上下文和快取中。

降級會從可快取的歷史記錄中移除思考。 如果思考在輪次中途變為停用，而您在目前的工具使用輪次中傳遞了思考內容，則思考內容會被移除，且該請求的思考會保持停用（請參閱優雅降級）。交錯思考會放大快取失效的影響，因為思考區塊可能出現在多個工具呼叫之間。

思考與上下文視窗

max_tokens（包含 Claude 在目前輪次中產生的所有思考）會作為嚴格限制強制執行。在 Claude 4.5 及更新的模型上，如果輸入權杖加上 max_tokens 超過「context window」（上下文視窗）大小，API 會接受該請求。如果生成隨後達到上下文視窗限制，它會以 stop_reason: "model_context_window_exceeded" 停止，而不是回傳錯誤。在較早的模型上，API 會改為回傳驗證錯誤。請參閱處理停止原因。

思考如何計入視窗，取決於它是何時產生的：

• 目前輪次的思考一律計入 max_tokens，以輸出權杖計費，並在產生它的輪次中佔用上下文視窗空間。
• 先前輪次的思考取決於保留預設值。在保留所有先前輪次的模型上，先前的思考區塊會留在上下文中、計入視窗，並像其餘對話歷史記錄一樣以輸入權杖計費。在僅保留最後輪次的模型上，當您傳回較舊的思考區塊時，API 會自動將其移除，因此它們不會消耗視窗空間或輸入權杖。

實務上：

• 在保留全部的模型上，請將思考視為一般對話歷史記錄來規劃您的上下文視窗預算，因為它確實就是。長時間的代理工作階段會在上下文中累積思考。如果您需要回收空間，請使用思考區塊清除。
• 在僅保留最後輪次的模型上，思考只是每輪次的成本：每個輪次的思考計入該輪次的 max_tokens，然後從視窗中移出。

以下圖表說明僅保留最後輪次（移除）的機制。第一張顯示多輪對話：每個輪次的思考區塊在輸出中產生，但不會帶入後續輪次的輸入。

第二張顯示相同機制搭配工具使用的情況：思考在助理輪次期間與其工具結果一起留在上下文中，然後在下一個使用者輪次時移出。

請使用權杖計數 API 為您的特定使用案例取得準確的計數，尤其是包含思考的多輪對話。

思考加密

完整的思考內容會經過加密，並在每個思考區塊的 signature 欄位中回傳。當您傳回思考區塊時，API 會使用簽章來驗證這些思考區塊是由 Claude 產生的。

使用簽章時請記住以下幾點：

• 只有在搭配思考使用工具時，才嚴格需要傳回思考區塊。否則您可以省略先前輪次的思考區塊。如果您確實傳回它們，API 是保留還是移除它們取決於模型（請參閱依模型的思考區塊保留）。請使用上下文編輯來設定此行為。
• 傳回思考區塊時，請完全按照您收到的內容傳回所有內容，以保持一致性並避免潛在問題。
• 在串流回應時，簽章會在 content_block_stop 事件之前，以 content_block_delta 事件內的 signature_delta 形式送達。
• 在 Claude 4 及之後的模型中，signature 值比先前模型中的長得多。
• signature 欄位是不透明的：請勿解讀或剖析它。
• signature 值可跨平台相容（Claude API、Amazon Bedrock 和 Google Cloud）。在一個平台上產生的值可在另一個平台上使用。

已編修的思考區塊

除了一般的 thinking 區塊之外，當 Claude 的部分推理因安全因素被編修時，API 可能會回傳 redacted_thinking 區塊。redacted_thinking 區塊在 data 欄位中包含加密的思考內容，沒有可讀的文字：

{
  "type": "redacted_thinking",
  "data": "..."
}

data 欄位是不透明且經過加密的。與一般思考區塊上的 signature 欄位一樣，在搭配工具繼續多輪對話時，請將 redacted_thinking 區塊原封不動地傳回 API。

限制與功能相容性

取樣參數

在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5 上，非預設的 temperature、top_p 或 top_k 值會在每個請求上回傳 400 錯誤，無論是否使用思考。在較舊的模型上，此限制僅在思考開啟時適用：temperature 和 top_k 與思考不相容，而 top_p 允許介於 0.95 和 1 之間的值。

回應預填與強制工具使用

思考開啟時，您無法預填助理回應。強制工具使用（tool_choice: {"type": "any"} 或 {"type": "tool", ...}）與手動擴展思考不相容，但可與自適應思考搭配使用。例外是 Claude Fable 5.1 和 Claude Mythos 5.1，它們會在每個請求上以 400 錯誤拒絕強制工具使用。在這些模型上，請改用 tool_choice: {"type": "auto"} 搭配嚴格工具使用或結構化輸出。請參閱搭配工具使用的思考。

輸出限制

每個模型接受的 max_tokens 最高可達此處列出的上限。在 Message Batches API 上，output-300k-2026-03-24 beta 標頭會為列有批次上限的模型提高該上限。

有關舊版模型的限制，請參閱模型概覽。

長時間請求

當 max_tokens 大於 21,333 時，SDK 會要求使用串流，以避免長時間執行的請求發生 HTTP 逾時。這是用戶端驗證，而非 API 限制。如果您不需要逐步處理事件，請使用 .stream() 搭配 .get_final_message()（Python）或 .finalMessage()（TypeScript）來取得完整的 Message 物件，而無需處理個別事件。請參閱串流訊息。思考啟用時，請預期較長的回應時間，因為產生思考區塊會增加處理時間。對於將每個請求的思考推高到約 32k 權杖以上的工作負載，請使用批次處理以避免網路問題：此類請求的執行時間可能長到足以觸及系統逾時和開啟連線數限制。

後續步驟