遷移至 Claude Opus 5.5

如需了解行為差異與特定模型的提示模式，請參閱為 Claude Opus 5.5 撰寫提示。

Claude Opus 5.5 的費用低於 Claude Opus 5（每百萬輸入／輸出 token 為 $4 / $20 美元，Claude Opus 5 則為 $5 / $25；請參閱 Claude 定價），並保留 Claude Opus 5 的 1M token「context window」（上下文視窗）與 128k 最大輸出 token。對於已在 Claude Opus 5 上執行的程式碼，共有四項「breaking changes」（重大變更），詳見重大變更。如需了解功能支援，請參閱 Claude Opus 5.5 的新功能。

從 Claude Opus 5 遷移至 Claude Opus 5.5

更新您的模型名稱

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 是不含日期後綴的固定模型 ID，與 claude-opus-5 採用相同的命名方式。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 與 Microsoft Foundry 上，請使用該平台的模型 ID；請參閱可用性。

重大變更

每項變更的說明請見 Claude Opus 5.5 的新功能；本節提供每項變更所需的程式碼修改。

思考無法停用

thinking: {"type": "disabled"} 與 thinking: {"type": "enabled", "budget_tokens": N} 都會傳回 400 錯誤（"thinking.type.disabled" is not supported for this model. 或 "thinking.type.enabled" is not supported for this model.）。請移除 thinking 欄位，並選擇一個 effort（投入程度）等級；若您先前停用思考是為了節省 token，請改用較低的等級。回應接著會以 thinking 區塊開頭，因此請依 type 選取內容區塊，並將 thinking 區塊連同工具結果原封不動地傳回。請參閱思考無法停用。

變更前（Claude Opus 5 接受，Claude Opus 5.5 拒絕）：

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

變更後：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

不支援強制工具使用

tool_choice 類型 any 與 tool 會傳回 400 錯誤（tool_choice: type "tool" and "any" are not supported for this model.），在 token 計數端點上也是如此。請使用 auto 搭配嚴格工具使用或結構化輸出，並在提示中說明何時適用該工具。請參閱不支援強制工具使用。

變更前：

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

變更後：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

思考區塊與模型及對話綁定

在 Claude API 上，Claude Fable 5.1 與 Claude Mythos 5.1 可讀取 Claude Opus 5.5 的思考區塊；其他模型皆無法讀取。若路由器或備援機制將對話從 Claude Opus 5.5 移至任何其他模型，這些回合將在沒有這些區塊的情況下執行。反過來說，Claude Opus 5.5 可讀取來自 Claude Opus 5 及更早的 Opus、Sonnet 與 Haiku 模型的思考區塊，但無法讀取來自 Claude Fable 或 Claude Mythos 模型的思考區塊。請讓對話保持「append-only」（僅附加）（不要在對話中途編輯 system 提示、tools 或先前的訊息），以確保這些區塊維持有效；Claude Code、claude.ai、Claude Managed Agents 與 Claude Agent SDK 已經這麼做。所有平台上的強制執行方式皆與 Claude Fable 5.1 相同：對於在 2026 年 8 月 31 日 00:00 UTC 或之後建立的帳戶，在此類編輯後重播思考區塊，預設會傳回 400 錯誤。僅附加的整合不需要修改程式碼。請參閱思考區塊與模型及對話綁定與保留思考。

Claude API 與 Google Cloud 不支援 computer_20251124 電腦使用工具

在 Claude API 與 Google Cloud 上，類型為 computer_20251124 的 tools 項目會傳回 400 錯誤（'claude-opus-5-5' does not support tool types: computer_20251124.，後面接著該模型接受的工具類型）。請改為宣告 computer_toolset_20260801 工具集：移除 beta 標頭，並在傳送該項目時不包含 name 或顯示尺寸。在您的代理迴圈中，請處理成員 tool_use 區塊（動作是區塊的 name，而非 input.action），每個回合可能有多個此類區塊，並在每個結果中回傳 toolset_name。請求的變更如下所示；代理迴圈的變更列於從 computer_20251124 遷移。在 Amazon Bedrock 上，較早的 computer_20251124 工具在 Claude Opus 5.5 上仍可如同在 Claude Opus 5 上一樣運作，因此無需變更；其他平台請參閱電腦使用工具的相容性章節。請參閱Claude API 與 Google Cloud 不支援 computer_20251124 電腦使用工具。

變更前：

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

變更後：

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # 不需要 beta 標頭；toolset 項目不需指定名稱或顯示尺寸
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

工具呼叫之間的文字會在思考區塊中傳回

在 Claude Opus 5 上，模型在工具呼叫之間撰寫的文字會以 text 區塊傳回。在 Claude Opus 5.5 上，與 Claude Fable 5.1 相同，這些敘述會以進度更新 thinking 區塊傳回，每次工具呼叫之前最多一個。在預設的 thinking.display 值 "omitted" 下，其 thinking 欄位為空。雖然不會有請求失敗，但若應用程式會將這些文字以「streaming」（串流）方式作為進度更新傳送給使用者，則在工具呼叫之間將不再有任何輸出。若要恢復這些更新，請從 thinking 區塊讀取它們，並設定會傳回其文字的 display 值："updates"（beta，需使用 thinking-display-updates-2026-08-18 標頭）會傳回進度更新，同時保持推理內容隱藏；"summarized" 則會將兩者混合一併傳回。接著，請將每個非空的 thinking 區塊呈現在其後方的 tool_use 區塊之前，並將這些區塊連同助理回合的其餘內容原封不動地傳回。請參閱面向使用者的進度更新。

安全分類器與備援

Claude Opus 5.5 可能會傳回帶有 stop_details 類別的 stop_reason: "refusal"。其分類器涵蓋的類別比 Claude Opus 5 更廣，因此除了 "cyber" 之外，也可能出現 "bio" 與 "reasoning_extraction" 等 stop_details.category 值；請參閱拒絕類別表。請處理拒絕情況，並設定伺服器端備援或您自己的重試機制（伺服器端備援不會重試因 "reasoning_extraction" 而被拒絕的請求；該拒絕會直接傳回給您）；請參閱拒絕與備援與安全防護拒絕。

建議變更

1. 重新進行 effort 掃描測試。 Effort 是 Claude Opus 5.5 上唯一的思考控制項，其預設值為 medium，而 Claude Opus 5 的預設值為 high，因此省略 effort 的請求現在會以 medium 執行。在品質維持不變的情況下調低等級，並針對要求最高的工作調高等級。請參閱 Effort。
2. 重新評估特定模型的提示指示。 針對 Claude Opus 5 行為調整的指示可能已不再需要；請參閱為 Claude Opus 5.5 撰寫提示。如果您先前在停用思考的情況下執行，也請參閱為停用思考而撰寫的提示。
3. 在切換正式環境流量之前，先在開發環境中測試。

遷移檢查清單

• 將模型 ID 更新為 claude-opus-5-5。
• 移除 thinking: {"type": "disabled"} 與 thinking: {"type": "enabled", ...}；改為選擇一個 effort 等級。
• 明確設定 effort：預設值為 medium，而 Claude Opus 5 的預設值為 high。
• 將 tool_choice 類型 any 與 tool 替換為 auto，並搭配嚴格工具使用或結構化輸出。
• 如果您在 Claude API 或 Google Cloud 上使用電腦使用功能，請宣告 computer_toolset_20260801（不需 beta 標頭）以取代 computer_20251124，並針對該工具集更新您的代理迴圈。在 Amazon Bedrock 上，請繼續使用 computer_20251124；其他平台請查看電腦使用工具的相容性章節。
• 如果路由器或備援機制可能將對話從 Claude Opus 5.5 移至其他模型，請預期該模型會在沒有 Claude Opus 5.5 思考區塊的情況下執行（Claude API 上的 Claude Fable 5.1 與 Claude Mythos 5.1 是例外，會保留這些區塊）。Claude Opus 5.5 本身可讀取來自 Claude Opus 5 及更早的 Opus、Sonnet 與 Haiku 模型的思考內容，但無法讀取來自 Claude Fable 或 Claude Mythos 模型的思考內容。
• 依 type 讀取內容區塊，並在工具使用迴圈中將 thinking 區塊原封不動地傳回。
• 如果您的介面會呈現工具呼叫之間的文字，請設定 display: "updates"（beta）或 "summarized"，並呈現非空的 thinking 區塊。
• 如果您的程式碼會在對話中途編輯先前的回合、system 提示或 tools，請遵循保留思考。
• 處理 stop_reason: "refusal" 並設定備援。
• 在您選擇的 effort 等級下，重新建立成本與延遲的基準。

從 Claude Opus 4.8 遷移至 Claude Opus 5.5

請先完成從 Claude Opus 4.8 遷移至 Claude Opus 5：其中涵蓋預設啟用思考，以及隨之而來的回應結構變更。接著再套用從 Claude Opus 5 遷移。該處提到的第二項 Claude Opus 5 重大變更（僅能在 high effort 或以下停用思考）不適用於此：在 Claude Opus 5.5 上完全無法停用思考。

遷移檢查清單

• Claude Opus 4.8 → Claude Opus 5 檢查清單中的所有項目，但 thinking: {"type": "disabled"} 不是可用選項。
• Claude Opus 5 → Claude Opus 5.5 檢查清單中的所有項目。

從 Claude Opus 4.7 及更早的 Opus 模型遷移至 Claude Opus 5.5

Claude Opus 5 遷移指南涵蓋您目前的模型與 Claude Opus 5 之間的重大變更：取樣參數遭拒絕、手動擴展思考遭拒絕、預填功能移除，以及較新的分詞器。請完成該指南中對應您模型的章節，並以 claude-opus-5-5 取代 claude-opus-5 作為目標，接著再套用從 Claude Opus 5 遷移。該指南中提到可在 high effort 或以下停用思考之處，在 Claude Opus 5.5 上並不適用；而該指南中提到現有 computer_20251124 整合可繼續運作之處，在 Claude API 與 Google Cloud 上的 Claude Opus 5.5 並不適用，因為在這些平台上 Claude Opus 5.5 僅接受以 computer_toolset_20260801 工具集形式使用電腦使用功能（請參閱該重大變更）；在 Amazon Bedrock 上則可繼續運作。

從 Claude Sonnet 5 遷移至 Claude Opus 5.5

請參閱從 Claude Sonnet 5 遷移至 Claude Opus 5，了解升級至更高模型等級時會有哪些變更，接著再套用從 Claude Opus 5 遷移。