思考

只進行單次處理就作答的模型，必須第一次就把所有事情做對：沒有草稿、沒有檢查，也無法中途改變方向。對於證明、棘手的錯誤或冗長的代理任務而言，第一個想到的方法往往不是最好的。

「Thinking」（思考）消除了這項限制。思考啟用時，Claude 會在回答前先用自己的話逐步處理問題：重述問題、嘗試不同方法、檢查中間結果，並放棄站不住腳的路徑。這些預先思考會以 thinking 內容區塊的形式出現在回應之前，Claude 會依據這些思考產生最終答案。因此，思考能提升數學、程式設計、分析以及長時間執行的代理工作等複雜任務的表現。這類任務的答案品質取決於中間過程，若沒有思考，這些過程就會被壓縮進回應本身，或直接被略過。

思考是有成本的：Claude 用於推理的 token 會以輸出 token 計費，即使思考文字沒有傳回給您也一樣，而且這些 token 會與回應文字一起計入 max_tokens。本頁說明思考在整個 API 中的行為：如何開啟思考、讀取其輸出，以及管理思考與工具、串流、快取和上下文視窗之間的互動。

思考如何運作

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

以下是預先思考在回應中的樣子：一個或多個 thinking 內容區塊會在 text 區塊之前出現。思考區塊仍然是生成的內容，就像其後的 text 區塊一樣，但它與正式回應是分開的。每個思考區塊也帶有一個 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..."
    }
  ]
}

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

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

設定思考

在大多數模型上，思考預設為開啟，或只需一個參數即可開啟。下表顯示每個模型對請求可傳送的每個 thinking 值的處理方式。400 錯誤表示 API 拒絕該請求，思考疑難排解列出了每個錯誤及其修正方式。

在表格中，「在 high 或更低 effort 下」表示該請求在 low、medium 和 high effort 下可正常運作，而在 xhigh 或 max 下會回傳 400 錯誤。

在 Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5、Claude Sonnet 5、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Mythos Preview 和 Claude Haiku 5.5 上，思考已經開啟，無需任何設定。這些模型上的 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-5-5",
    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:
    match block.type:
        case "thinking":
            print(f"\nThinking: {block.thinking}")
        case "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 偶爾可能會以純文字形式發出工具呼叫，或在其可見輸出中包含內部 XML 標籤。請參閱在停用思考的情況下執行以了解提示方面的緩解措施。

Claude Sonnet 5.5 的思考也預設為開啟，且它會以 400 錯誤拒絕 thinking: {type: "disabled"}。若要關閉預先思考，請改為傳送 thinking: {type: "between_tools"}。這是 Claude Sonnet 5.5 上最低的思考設定，並在 effort 為 high 或更低時被接受。模型仍會回傳其工具呼叫之間的進度更新。在沒有工具的情況下，回應只包含文字，就像在 Claude Sonnet 5 上使用 disabled 一樣。請參閱在沒有預先思考的情況下執行以取得提示指引。

Claude Haiku 5.5 的思考也預設為開啟，並在 effort 為 high 或以下時接受 thinking: {type: "disabled"}。在 xhigh 或 max effort 下，該組合會回傳 400 錯誤。若要減少思考，請先降低 effort 等級。在思考關閉的情況下，當您同時要求 JSON 輸出時，模型可能會略過它需要的工具呼叫。在思考關閉期間，與目前生效等級不同的每則訊息 output_config.effort 也會回傳 400 錯誤。請參閱使用 effort 控制思考以及搭配 JSON 輸出與您自己的工具使用自適應思考。

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

若要在傳送請求之前檢查模型是否接受 "disabled"，請從 Models API 讀取其 capabilities.thinking.types.disabled.supported 值。使用 Models API 說明了該欄位。

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

讀取思考輸出

控制思考顯示

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

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

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

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

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

使用省略的思考時，請注意以下事項：

• 您仍需為完整的思考 token 付費。省略可降低延遲，而非成本。
• 如果您在多輪對話中傳回思考區塊，請原封不動地傳回。伺服器會解密 signature 以重建原始思考，用於建構提示（請參閱保留思考區塊）。您在往返傳遞的省略區塊的 thinking 欄位中放入的任何文字都會被忽略。
• display 在 thinking.type: "disabled" 時無效（沒有可顯示的內容），在 thinking.type: "between_tools"（僅限 Claude Sonnet 5.5）時也無效，因為後者不接受其他欄位。使用 between_tools 時，進度更新仍會帶有摘要文字回傳，就像在 display: "updates" 下一樣（請參閱進度更新）。
• 使用 thinking.type: "adaptive" 且模型針對簡單請求略過思考時，無論 display 為何，都不會產生思考區塊。
• 使用 display: "omitted" 進行串流時，不會串流任何思考文字。每個思考區塊會串流一個 thinking 字串為空的 thinking_delta，然後是其 signature_delta。使用 display: "updates" 時，只有進度更新區塊會串流帶有文字的 thinking_delta 事件。請參閱串流思考以了解事件順序。

摘要思考

當 display 為 "summarized" 時，您收到的思考文字是 Claude 完整思考過程的摘要，而非原始的思維鏈。「Summarized thinking」（摘要思考）在提供思考的完整智慧優勢的同時，也能防止濫用。沒有任何 display 設定會回傳原始的思維鏈。

使用摘要思考時，請注意以下事項：

• 您需要為原始請求所產生的完整思考 token 付費，而非摘要 token。計費的輸出 token 數量與您在回應中看到的 token 數量並不相符。
• 在 Claude Opus 4.6、Claude Sonnet 4.6 及更早的模型上，思考輸出的前幾行會較為詳細，提供對提示工程特別有幫助的詳細推理。Claude Mythos Preview 從第一個 token 就開始摘要，因此其思考區塊不會顯示這段詳細的開頭。
• 摘要會以最少的額外延遲保留 Claude 思考過程的關鍵概念，因此摘要可以在產生時即時串流。
• 摘要是由與您在請求中指定的模型不同的模型處理的。思考模型看不到摘要後的輸出。
• 隨著 Anthropic 持續改進思考功能，摘要行為可能會有所變更。

若要查看模型的推理，請讀取 thinking 區塊，而不是在回應文字中提示模型提供推理。在 Claude Fable 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Fable 5 上，試圖在回應文字中引出模型內部推理的請求可能會被拒絕，並帶有 stop_details.category: "reasoning_extraction"。請參閱拒絕類別以取得欄位參考，並參閱將推理保留在思考區塊中以了解應改為要求什麼。

串流思考

思考可與串流搭配使用。思考區塊會以 content_block_delta 事件中的 thinking_delta 事件進行串流，並在區塊的 content_block_stop 之前緊接著一個 signature_delta 事件。文字區塊隨後照常串流。

以下範例使用自適應思考串流回應，並在思考和文字 delta 到達時將其印出：

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    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:
        match event.type:
            case "content_block_start":
                print(f"\nStarting {event.content_block.type} block...")
            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "thinking_delta":
                        print(delta.thinking, end="", flush=True)
                    case "text_delta":
                        print(delta.text, end="", flush=True)

若要在串流後重新組合完整的思考區塊及其簽章，請使用您 SDK 的訊息累積輔助工具 stream.get_final_message()，而不是自行串接 delta。

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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 字串為空的 thinking_delta 到達，接著是單一 signature_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":"thinking_delta","thinking":""}}

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"}（請參閱各模型設定表）。Claude Sonnet 5.5 會拒絕 "disabled"。其最低設定為 thinking: {type: "between_tools"}，可關閉預先思考。
• 您需要嚴格的支出上限： 使用 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 Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 Claude Mythos 5.1 除外（請參閱回應預填與強制工具使用）。在接受強制工具使用的情況下，回應會以工具呼叫開始，且沒有 thinking 區塊。
2. 保留思考區塊： 當您回傳工具結果時，必須將助理訊息中的思考區塊完整且未經修改地傳回 API。請參閱保留思考區塊。

工具使用迴圈是一個助理輪次。 從模型的角度來看，助理輪次要等到 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 還會強制要求啟用思考之請求的最後一個助理輪次必須以思考區塊開頭。自適應模式放寬了這項要求：任何助理輪次都不需要以思考區塊開頭。

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

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

保留思考區塊

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

1. 推理連續性： 思考區塊記錄了導致工具請求的逐步推理。包含這些區塊能讓 Claude 從中斷處繼續推理。
2. 上下文維護： 在 API 結構中，工具結果會以使用者訊息的形式出現，但它們屬於同一個連續的推理流程。保留思考區塊能在多次 API 呼叫之間維持該流程。

簡而言之：

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

您不需要自行修剪舊的思考內容。在多輪對話中傳回所有思考區塊，API 會自動篩選，保留維持模型推理所需的區塊，並且只針對實際呈現給 Claude 的區塊收取輸入 token 費用。保留哪些先前輪次的區塊因模型而異。請參閱各模型的思考區塊保留方式。若要覆寫預設行為，請使用 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.5、Claude Opus 5、Claude Sonnet 5.5、Claude Opus 4.8 和 Claude Opus 4.7 上，工具呼叫之間的推理一律會出現在思考區塊中。Claude Haiku 4.5 不支援交錯思考。在使用手動擴展思考的模型上，交錯思考需要 beta 標頭，並會改變思考預算的計算方式。手動模式下的交錯思考涵蓋了各模型的規則和特定平台的標頭行為。

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

如需展示交錯思考在雙工具工作流程中帶來哪些改變的實際比較，請參閱交錯思考如何改變流程。

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

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

進度更新區塊包含的內容取決於 display：

在 Claude Sonnet 5.5 上，最低的思考設定是 thinking: {type: "between_tools"}。它會關閉預先思考，而每則進度更新都會帶著其摘要文字回傳，就像在 display: "updates" 下一樣。between_tools 僅在 effort 為 high 或更低時被接受。在 xhigh 或 max 下，使用它的請求會回傳 400 錯誤。between_tools 不接受其他欄位：與其一起傳送的 display、budget_tokens 或 block_binding 會回傳 400 錯誤。此設定不需要 beta 標頭，並可在所有提供 Claude Sonnet 5.5 的平台上運作。請原封不動地傳回區塊：您傳回的進度更新區塊會提供模型它所撰寫的完整註記，而非摘要。

對於隱藏推理、並在每個步驟向使用者顯示狀態列的代理介面，請使用 display: "updates"。在此設定下，任何帶有非空文字的 thinking 區塊都是進度更新，因此只需呈現這些區塊即可。此功能處於 beta 階段，需要 beta 標頭 thinking-display-updates-2026-08-18（若要在 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 上傳送，請參閱其他平台上的 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 下以及在長工具鏈中撰寫的進度更新較少。如果您的介面依賴它們，請參閱要求面向使用者的進度更新，或針對 Claude Opus 5.5 參閱面向使用者的進度更新。針對 Claude Sonnet 5.5，請參閱面向使用者的進度更新。

各模型的思考區塊保留方式

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

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

保留思考區塊帶來兩項好處：

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

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

在對話中途切換模型。 當您切換模型時（例如在分類器拒絕備援之後），請持續將思考區塊原封不動地傳回。思考區塊只能由產生它的模型及特定其他模型讀取，API 會忽略或捨棄目標模型無法讀取的區塊。在 Claude Fable 5.1 和 Claude Mythos 5.1 上，方向很重要：它們可讀取較早模型的思考區塊，且只有這兩者能讀取彼此的區塊，因此切換到它們會保留對話的推理，而從它們切換到任何其他模型則會捨棄推理（請參閱被捨棄區塊的計費與回報方式）。Claude Opus 5.5 可讀取 Claude Opus 5 的思考區塊，以及較早的 Opus、Sonnet 和 Haiku 模型的思考區塊，並且在 Claude API 和 Google Cloud 上可讀取 Claude Haiku 5.5 的思考區塊，但無法讀取 Claude Fable 和 Claude Mythos 模型的思考區塊；在 Claude API 上，Claude Fable 5.1 和 Claude Mythos 5.1 可讀取 Claude Opus 5.5 的區塊。在 Claude API 上從 Claude Opus 5.5 升級切換到 Claude Fable 5.1 會保留先前輪次的推理；從 Claude Fable 5.1 切換到 Claude Opus 5.5 則會捨棄推理。Claude Sonnet 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及較早模型的思考區塊，並且在 Claude API 和 Google Cloud 上可讀取來自 Claude Haiku 5.5 的思考區塊，但無法讀取來自 Claude Opus 5、Claude Opus 5.5 或任何 Claude Fable 或 Claude Mythos 模型的思考區塊。在 Claude API 和 Google Cloud 上，Claude Opus 5.5 可讀取 Claude Sonnet 5.5 的區塊，其他模型則都無法讀取：在 Claude API 和 Google Cloud 上從 Claude Sonnet 5.5 升級切換到 Claude Opus 5.5 會保留先前輪次的推理，而從 Claude Sonnet 5.5 進行的任何其他切換都會捨棄推理。Claude Haiku 5.5 可讀取來自 Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5 及較早模型的思考區塊，但無法讀取來自 Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5 或任何 Claude Fable 或 Claude Mythos 模型的思考區塊。在 Claude API 和 Google Cloud 上，Claude Opus 5.5 和 Claude Sonnet 5.5 可讀取 Claude Haiku 5.5 的區塊，其他模型則都無法讀取。只有在模型會忽略而非捨棄先前的 thinking 和 redacted_thinking 區塊時，才為了節省輸入 token 而自行移除它們；而在兌換備援抵免時絕對不要這麼做，因為兌換需要請求主體保持不變。

保留思考

保留思考決定模型是否能使用您從先前輪次傳回的思考區塊。從 Claude Fable 5.1 開始，API 會檢查請求中每個 thinking 或 redacted_thinking 區塊的 signature，確認兩件事：

• 產生它的模型。 每個模型都能讀取自己的思考區塊，以及一組固定的其他模型的思考區塊。Claude Fable 5.1 可讀取來自 Claude Opus 5 的區塊，在 Claude API 上也可讀取來自 Claude Opus 5.5 的區塊；Claude Opus 5 和 Claude Opus 5.5 都無法讀取來自 Claude Fable 5.1 的區塊。API 會捨棄目前模型無法讀取的區塊，不會產生錯誤，也不會對其計費。請參閱在對話中途切換模型。
• 在它之前傳送的所有內容。 只有在頂層 system 提示、tools 以及它之前的訊息都保持不變時，區塊才會維持有效。如果其中任何一項發生變更，該區塊及之後的所有思考區塊都會失效，API 會依您的選擇，以 400 錯誤拒絕請求或捨棄失效的區塊。請參閱保持前綴不變。

來自 Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考區塊也與產生它們的帳戶綁定。請參閱思考區塊僅限產生它們的帳戶使用，了解 API 在何處強制執行此規則。

模型檢查適用於所有帳戶。對於在 2026 年 8 月 31 日 00:00 UTC 或之後建立的帳戶，API 預設會強制執行前綴檢查。在較舊的帳戶上，API 僅對設定了 thinking.block_binding.prefix_mismatch_behavior 的請求強制執行此檢查。無論您的帳戶建立時間為何，都請讓您的整合採用僅附加（append-only）的方式，如此相同的程式碼就能在所有帳戶上運作，包括預設強制執行檢查的較新帳戶。

若要讓思考保持有效，請將每個助理輪次完全按照您收到的樣子傳回，並且只在 messages 的末尾新增訊息。如果您的程式碼會自行建構 messages 陣列，保留思考頁面涵蓋以下內容：

• 哪些變更算是編輯，以及如何檢查您的程式碼是否進行了編輯。
• 取代各種常見編輯的 API 功能：用於新指示和每輪提醒的對話中途系統訊息、用於工具變更的 tool_addition 和 tool_removal 區塊、用於 effort 變更的每則訊息 output_config，以及用於修剪的伺服器端壓縮和上下文編輯。
• 用戶端壓縮：哪些模式能讓思考保持有效，哪些則不能。
• thinking-binding-controls-2026-08-01 beta 標頭。它會在思考設定中新增 block_binding.prefix_mismatch_behavior 欄位（"error" 或 "drop_block"），並在每個回應中新增 input_transformations 陣列。該陣列會列出 API 捨棄的每個思考區塊，或未通過前綴檢查但仍被放行的每個思考區塊。

思考與提示快取

提示快取與思考之間有幾種特定的交互作用。以下規則適用於兩種思考模式。

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

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

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

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 及更新的模型上，如果輸入 token 加上 max_tokens 超過上下文視窗大小，API 仍會接受請求。如果生成過程隨後達到上下文視窗上限，它會以 stop_reason: "model_context_window_exceeded" 停止，而不是傳回錯誤。在較早的模型上，API 則會傳回驗證錯誤。請參閱處理停止原因。

思考如何計入視窗取決於其產生的時間：

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

實務上：

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

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

第二張圖顯示相同機制搭配「tool use」（工具使用）的情況：在助理輪次期間，思考會與其「tool result」（工具結果）一起留在上下文中，然後在下一個使用者輪次時被移除。

請使用 token 計數 API 取得您特定使用情境的準確計數，特別是包含思考的多輪對話。

思考加密

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

使用簽章時，請留意以下事項：

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

已編修的思考區塊

除了一般的 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.5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Sonnet 5.5、Claude Sonnet 5 和 Claude Haiku 5.5 上，非預設的 temperature、top_p 或 top_k 值在每個請求上都會傳回 400 錯誤，無論是否使用思考。在這些模型上，top_p 的預設值為 0.99，因此 top_p 為 1 會傳回 400 錯誤，同時包含 temperature 和 top_p 的請求也會如此，即使它們都是預設值。請參閱移除取樣參數。在較舊的模型上，此限制僅在思考開啟時適用：temperature 和 top_k 與思考不相容，而 top_p 允許介於 0.95 到 1 之間的值。

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

Claude 4.6 及之後的模型以及 Claude Mythos Preview 會以 400 錯誤拒絕預填的最終助理輪次，無論思考是否開啟（請參閱不支援預填）。在較早的模型上，思考開啟時無法預填助理回應。強制工具使用（tool_choice: {"type": "any"} 或 {"type": "tool", ...}）與手動擴展思考不相容，但可搭配自適應思考使用。例外情況是 Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1 和 Claude Mythos 5.1，它們會在每個請求上以 400 錯誤拒絕強制工具使用。在這些模型上，請改用 tool_choice: {"type": "auto"} 搭配嚴格工具使用或結構化輸出。在接受強制工具使用的情況下，回應會以工具呼叫開始，且沒有 thinking 區塊。若要讓模型在呼叫工具之前先思考，請使用 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() 來取得完整的 Message 物件，而無需自行從個別事件組合。請參閱串流訊息。思考啟用時，回應時間預期會較長，因為產生思考區塊會增加處理時間。對於每個請求的思考量超過約 32k token 的工作負載，請使用批次處理以避免網路問題：此類請求的執行時間可能長到觸及系統逾時和開放連線數限制。

後續步驟