Claude Opus 5.5 遷移指南

本頁列出從 Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6 及更早的 Opus 模型或 Claude Sonnet 5 遷移至 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.5 的新功能。關於行為差異與模型特定的提示模式，請參閱提示 Claude Opus 5.5。

每個傳送至 Claude Opus 5.5 的請求必須滿足的條件

無論您從哪個模型遷移，傳送至 claude-opus-5-5 的請求都必須符合以下條件。若某項目指出某設定會被拒絕，API 會傳回 400 錯誤。

• 模型 ID： 使用 claude-opus-5-5，這是一個沒有日期後綴的固定模型 ID。在 Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed)、Claude Models on Google Cloud (Google managed) 和 Microsoft Foundry 上，請使用該平台的模型 ID；請參閱可用性。
• 思考： 不傳送 thinking 欄位，或傳送 thinking: {"type": "adaptive"}，兩者等效：「adaptive thinking」（自適應思考）始終處於開啟狀態。thinking: {"type": "disabled"} 和手動思考預算（thinking: {"type": "enabled", "budget_tokens": N}）會被拒絕。請參閱思考的前後對照。
• Effort： 使用 effort 參數控制思考深度，這是唯一能控制思考深度的請求參數。五個等級（low、medium、high、xhigh、max）全部支援，預設值為 medium。請參閱 Claude Opus 5.5 的建議 effort 等級。
• Tool choice（工具選擇）： 使用 tool_choice {"type": "auto"}（預設值）或 {"type": "none"}。使用 {"type": "any"} 或 {"type": "tool", "name": "..."} 強制工具呼叫會被拒絕。請參閱工具選擇的前後對照。
• Sampling parameters（取樣參數）： 省略 temperature、top_p 和 top_k。請使用提示來引導模型的行為。
• Prefill（預填）： 不要以預填的助理回合結束 messages：這會被拒絕。請改用「structured outputs」（結構化輸出）或系統提示指示。
• Computer use（電腦使用）： 將電腦使用宣告為 computer_toolset_20260801 工具集。在 Amazon Bedrock 上，computer_20251124 也可以使用。請參閱電腦使用的破壞性變更。
• Context window（上下文視窗）： 不需要上下文視窗 beta 標頭。1M token 上下文視窗為預設值，為舊模型傳送的標頭不會產生任何效果。

以下請求滿足清單中的每個項目：已設定 effort，且沒有 thinking 欄位。在範例印出文字之處，它會依類型尋找文字區塊，因為 thinking 區塊會排在最前面。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

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

在每個回應中處理思考

每個 Claude Opus 5.5 請求都會執行思考，因此每個回應都可能以 thinking 區塊開頭，且 max_tokens 涵蓋思考加上文字。如果您的程式碼已在開啟思考的情況下執行，第 1 到 3 項可能已就緒：請檢查第 4 和第 5 項。如果您的程式碼在任何較早的模型上都是在沒有思考的情況下執行，則每一項都是一項變更。

1. max_tokens 涵蓋思考加上文字： 在 Claude Opus 4.8 及更早的 Opus 模型上，沒有 thinking 欄位的請求會在沒有思考的情況下執行。Claude Opus 5 與 Claude Sonnet 5 接受 thinking: {"type": "disabled"}。在 Claude Opus 5.5 上，每個請求都會以自適應思考執行。max_tokens 仍是總輸出（思考加上回應文字）的硬性上限，因此請針對原本在沒有思考情況下執行的工作負載重新檢視此值。即使思考文字未傳回給您，思考 token 仍以輸出 token 計費，因此此類工作負載每個請求可能產生更多輸出 token。請參閱成本控制。若要在思考上花費較少 token，請降低 effort 等級。如果您以 xhigh 或 max effort 執行，請設定較大的 max_tokens，讓模型有空間思考與行動；從 64k token 開始，再依需求調整。如果您的提示是針對沒有思考的執行情境調校，請參閱為停用思考而撰寫的提示。

2. 回應以思考區塊開頭： 回應可能在第一個 text 區塊之前以一個或多個 thinking 區塊開頭。依位置讀取回覆的程式碼，例如 content[0].text，或將第一個 content_block_start 事件視為文字的串流處理程式，在這些回應上會出錯。請改為依內容區塊的 type 欄位選取：從 type 為 "text" 的區塊讀取 text，並在處理串流事件時依區塊類型分支。

3. 在工具使用迴圈中原封不動地傳回思考區塊： 如果您執行工具使用迴圈，在傳回工具結果時，請將每個助理回應中的 thinking 區塊完整且未經修改地傳回 API，包括 thinking 欄位為空的區塊。請照原樣回傳收到的助理訊息，而不是依類型篩選其內容區塊或重建訊息：API 會以 400 錯誤拒絕經編輯、重新排序或部分捨棄的思考區塊。請參閱保留思考區塊。

4. 思考文字預設會被省略： thinking.display 預設為 "omitted"，因此 thinking 區塊送達時，其 thinking 欄位為空，並附帶 signature。請僅將 thinking 欄位視為顯示用文字。若要改為接收可讀的摘要，請將 thinking.display 設為 "summarized"：

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   如果您的產品會將推理過程串流給使用者，預設值會表現為輸出開始前的長時間停頓；請設定 display: "summarized" 以在思考期間恢復可見的進度。請參閱控制思考顯示。

5. 工具呼叫之間的文字會以思考區塊傳回： 模型在工具呼叫之間撰寫的簡短說明會以 thinking 區塊傳回，在預設顯示設定下這些區塊為空。請參閱工具呼叫之間的文字會以思考區塊傳回。

依起始模型分類的遷移檢查清單

請依序往下處理各組，並在列出您目前模型的那一組之後停止：到該處為止的每個項目都適用於您。如果您使用的是 Claude Opus 5，第一組就是完整清單。如果您使用的是 Claude Sonnet 5，請套用第一組與最後一組。

所有起始模型

• 將模型 ID 更新為 claude-opus-5-5。
• 移除 thinking: {"type": "disabled"} 和 thinking: {"type": "enabled", ...}；改為選擇一個 effort 等級。
• 明確設定 effort：預設值為 medium，而 Claude Opus 5 的預設值為 high。
• 將 tool_choice 類型 any 和 tool 替換為 auto 加上嚴格工具使用或結構化輸出。
• 如果您使用較早的電腦使用工具版本，請改為宣告 computer_toolset_20260801（不需要 beta 標頭），並針對該工具集更新您的代理迴圈。在 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 API 和 Claude Models on Google Cloud (Google managed) 上，也可讀取來自 Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考內容，但無法讀取來自 Claude Fable 或 Claude Mythos 模型的思考內容。
• 依據 type 讀取內容區塊，並在工具使用迴圈中原封不動地傳回 thinking 區塊。
• 如果您的介面會呈現工具呼叫之間的文字，請設定 display: "updates"（beta）或 "summarized"，並呈現非空的 thinking 區塊。
• 如果您的程式碼會在對話中途編輯較早的回合、system 提示或 tools，請遵循保留思考。
• 處理 stop_reason: "refusal" 並設定備援機制。
• 在您選擇的 effort 等級下重新建立成本和延遲的基準。
• 如果您的程式碼曾停用思考，請重新檢視 max_tokens，它涵蓋思考加上回應文字；在 xhigh 或 max effort 下，請從 64k 開始。請參閱在每個回應中處理思考。

Claude Opus 4.8 或更早版本

• 檢視原本在沒有 thinking 欄位情況下執行的工作負載：在 Claude Opus 5.5 上它們會以思考執行，且思考無法停用。請重新檢視 max_tokens，它仍是總輸出（思考加上回應文字）的硬性上限，並在您希望減少思考之處降低 effort。思考 token 以輸出 token 計費，因此這些工作負載每個請求可能產生更多輸出 token。
• 確認任何解析 thinking 欄位的程式碼都僅將其視為顯示用文字。設定 display: "summarized" 以接收可讀的摘要。
• 檢視接近快取最小值的提示：512 個 token 以上的提示即可建立快取項目。
• 如果您的組織有 Priority Tier 承諾，請另行規劃容量：Claude Opus 5.5 不支援 Priority Tier。
• 如果您以 xhigh 或 max effort 執行，請將 max_tokens 提高到至少 64k 作為起點。
• 對於代理式工作負載，請考慮 task budgets（任務預算，beta）與對話中途的工具變更（beta）。

Claude Opus 4.7 或更早版本

• 在您自己的評估上重新執行 effort 掃描，而不是沿用為較早模型調校的設定。
• 移除任何上下文視窗 beta 標頭。
• 如果您會重建對話歷史以更新指示，請考慮改用對話中途的系統訊息，以保留提示快取命中。
• 確認您的停止原因處理會在拒絕時讀取 stop_details。
• 如果您需要 Claude Opus 4.7 會拒絕的快速模式，請在您的 Claude API 請求上設定 speed: "fast"。Claude Opus 5.5 不需要 beta 標頭。

Claude Opus 4.6 或更早版本

• 從請求酬載中移除 temperature、top_p 和 top_k。
• 將 thinking: {"type": "enabled", "budget_tokens": N} 替換為 thinking: {"type": "adaptive"} 加上 effort 參數，或完全移除 thinking 欄位；自適應思考永遠開啟。
• 如果您的 UI 會顯示思考內容，請明確選擇啟用思考摘要。
• 在更新後的斷詞方式下重新評測端到端成本與延遲。
• 重新調整 max_tokens 以考量更新後的斷詞方式，包括壓縮觸發條件。
• 重新測試任何用戶端的 token 數估算。
• 如果您的應用程式會傳送圖片，請針對高解析度圖片支援重新編列預算（每張全解析度圖片最多約多 3 倍的圖片 token）。如果您不需要額外的精細度，請在傳送前先降低取樣。
• 如果您使用模型提供的指向或邊界框座標，請移除任何縮放係數轉換；在 Claude Opus 4.7 及更新的模型上，座標與實際圖片像素為 1:1。
• 檢視從 Claude Opus 4.7 開始的行為變更。
• 如果您的產品從事正當的資安工作，請申請 Cyber Verification Program，以取得對資安內容較寬鬆限制的存取權。

Claude Opus 4.5 或更早版本

• 移除任何助理訊息預填；Claude Opus 4.6 已會拒絕它們。
• 確認工具呼叫 JSON 解析使用標準 JSON 解析器。
• 從 client.beta.messages.create() 改為 client.messages.create()：自適應思考與 effort 不需要 beta 命名空間。
• 移除 effort-2025-11-24 beta 標頭（effort 參數不需要它）。
• 移除 fine-grained-tool-streaming-2025-05-14 beta 標頭。
• 移除 interleaved-thinking-2025-05-14 beta 標頭（自適應思考會自動啟用交錯思考）。
• 將 output_format 遷移至 output_config.format（如適用）。

Claude 4.1 或更早版本

• 更新工具版本（text_editor_20250728、code_execution_20260521）。
• 處理 refusal 停止原因。
• 處理 model_context_window_exceeded 停止原因。
• 確認工具字串參數對結尾換行字元的處理。
• 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19 beta 標頭。
• 依照提示最佳實踐檢視並更新提示。

僅限 Claude Sonnet 5

• 如果您會重建對話歷史以更新指示，請考慮改用對話中途的系統訊息，以保留提示快取命中。
• 檢視接近快取最小值的提示：512 個 token 以上的提示即可建立快取項目。

從 Claude Opus 5 遷移至 Claude Opus 5.5

請先完成每個傳送至 Claude Opus 5.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、Claude Models on Google Cloud (Anthropic managed)、Claude Models on Google Cloud (Google managed) 和 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 會以 400 錯誤拒絕：

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 搭配 strict tool use（嚴格工具使用）或結構化輸出，並在提示中說明何時適用該工具。嚴格工具使用僅接受 JSON Schema 的子集，因此在加入 strict: true 之前，請先檢查每個工具的 input_schema。結構描述中的每個物件都必須設定 additionalProperties: false；請參閱 JSON Schema 限制。請參閱不支援強制工具使用。

變更前。Claude Opus 5 接受此請求，而 Claude Opus 5.5 會以 400 錯誤拒絕：

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 API 和 Claude Models on Google Cloud (Google managed) 上，也可讀取來自 Claude Sonnet 5.5 和 Claude Haiku 5.5 的思考區塊，但無法讀取來自 Claude Fable 或 Claude Mythos 模型的思考區塊。請讓對話保持僅附加（append-only）的方式（不要在對話中途編輯 system 提示、tools 或先前的訊息），以確保這些區塊維持有效；Claude Code、claude.ai、Claude Managed Agents 和 Claude Agent SDK 已經採用此方式。對於在 2026 年 8 月 31 日 00:00 UTC 當時或之後建立的帳戶，在 Claude API 和雲端平台上，若請求在此類編輯之後重新傳送思考區塊，且未設定 thinking.block_binding.prefix_mismatch_behavior，將會收到 400 錯誤。僅附加式的整合無需變更任何程式碼。請參閱思考區塊與模型和對話綁定和保留的思考。

部分電腦使用工具版本不受支援

Claude Opus 5.5 透過 computer_toolset_20260801 工具集支援電腦使用。在 Amazon Bedrock 上，Claude Opus 5.5 也接受搭配 computer-use-2025-11-24 beta 標頭的 computer_20251124 工具。對於任何不接受的電腦使用工具版本，例如 Claude API 上的 computer_20251124，Claude Opus 5.5 都會傳回 400 錯誤。它在任何平台上都不接受 computer_20250124。在 Claude API 上，錯誤訊息以 'claude-opus-5-5' does not support tool types: computer_20251124. 開頭，接著列出該模型接受的工具類型。

使用工具集的整合不需要任何變更。若要將 computer_20251124 整合轉移到工具集，請移除 beta 標頭，並傳送不含 name 或顯示尺寸的 computer_toolset_20260801 項目。在您的代理迴圈中，處理一個回合中的每個成員 tool_use 區塊，並在每個結果中回傳 toolset_name。請從每個區塊的 name 讀取動作，而非從 input.action 讀取。從 computer_20251124 遷移列出了代理迴圈的變更。

變更前。Claude Opus 5 接受此請求，而 Claude Opus 5.5 在 Claude API 上會以 400 錯誤拒絕它：

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 標頭；工具集項目不接受名稱或顯示尺寸
    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 欄位為空。沒有任何請求會失敗，但會將這些文字作為進度更新串流給使用者的應用程式，在工具呼叫之間會變得沉默。若要恢復這些更新，請從 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" 和 "reasoning_extraction" 之外，也請預期會出現 "bio" 等 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. 在開發環境中測試，再切換正式環境流量。

從 Claude Opus 4.8 遷移至 Claude Opus 5.5

請先完成每個傳送至 Claude Opus 5.5 的請求必須滿足的條件、在每個回應中處理思考與從 Claude Opus 5 遷移至 Claude Opus 5.5。使用 claude-opus-4-8 作為您要替換的模型 ID。最後一節的內容可直接套用於 Claude Opus 4.8 上的程式碼，因為 Claude Opus 4.8 與 Claude Opus 5 一樣：

• 接受 thinking: {"type": "disabled"}、強制工具選擇，以及 computer_20251124 工具。
• 以 text 區塊傳回工具呼叫之間的文字。
• 預設為 high effort。

本節補充 Claude Opus 4.8 與 Claude Opus 5 之間的變更。檢查清單請參閱遷移檢查清單中的前兩組。

變更內容

1. 原本省略思考的請求會執行思考： 在 Claude Opus 4.8 上，除非您要求，否則思考是關閉的。在 Claude Opus 5.5 上，沒有 thinking 欄位的請求會以思考執行，因此在每個回應中處理思考中的每個項目對這類程式碼而言都是一項變更。如果您的程式碼從未傳送 thinking 欄位，則在思考的變更前後對照中沒有需要移除的內容。

2. 較低的提示快取最小值： Claude Opus 5.5 上的最小可快取提示長度為 512 個 token，低於 Claude Opus 4.8 上的 1,024 個 token。在 Claude Opus 4.8 上過短而無法快取的提示，現在可以建立快取項目，不需要任何程式碼變更。各模型的最小值請參閱提示快取。

3. 不支援 Priority Tier： Claude Opus 5.5 不支援 Priority Tier，而 Claude Opus 4.8 保留此功能。如果您的組織有 Priority Tier 承諾，請另行規劃容量。

建議變更

這些並非必要，但能改善您的使用體驗：

1. 考慮使用任務預算（beta）： 對於代理式工作負載，「task budgets」（任務預算）會告訴模型在完整的代理迴圈中可使用多少 token。此功能需要 task-budgets-2026-03-13 beta 標頭。

2. 考慮在對話中途變更工具（beta）： 對話中途的工具變更可讓您在對話的各輪之間新增或移除工具，而不會使先前各輪的「prompt cache」（提示快取）命中失效。直接變更 tools 陣列本身則會使已快取的前綴失效。在 Claude API、Claude Platform on AWS 以及 Claude Models on Google Cloud (Anthropic managed) 上，請傳送 inline-tools-2026-09-15 beta 標頭。mid-conversation-tool-changes-2026-07-01 標頭適用於以參照方式指名工具的變更，可用於 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 以及 Claude Models on Google Cloud (Google managed)。

從 Claude Opus 4.7 遷移至 Claude Opus 5.5

請先完成每個傳送至 Claude Opus 5.5 的請求必須滿足的條件、在每個回應中處理思考、從 Claude Opus 5 遷移至 Claude Opus 5.5與從 Claude Opus 4.8 遷移至 Claude Opus 5.5。使用 claude-opus-4-7 作為您要替換的模型 ID。這些章節的內容可直接套用於 Claude Opus 4.7 上的程式碼。與 Claude Opus 4.8 一樣，它接受 thinking: {"type": "disabled"}、強制工具選擇，以及 computer_20251124 工具。它預設為 high effort，且除非您要求，否則會在沒有思考的情況下執行。

本節補充 Claude Opus 4.7 之後的變更。如果您的程式碼使用的是 Claude Opus 4.6 或更早版本，請在本節之後繼續閱讀從 Claude Opus 4.6 及更早的 Opus 模型遷移至 Claude Opus 5.5。該節補充在 Claude Opus 4.7 中生效的破壞性變更。檢查清單請參閱遷移檢查清單中的前三組。

變更內容

這些項目都不會在先前章節的破壞性變更之外新增其他破壞性變更；在您替換模型 ID 之後，值得檢查這些項目。

1. 重新校準 effort 等級： 與 Claude Opus 4.7 相比，Claude Opus 5.5 上每個 effort 等級背後的 token 分配有所變更。預設值為 medium，而 Claude Opus 4.7 的預設值為 high。請在您自己的評估上重新執行 effort 掃描，而不要沿用針對 Claude Opus 4.7 調校的設定。請參閱 Effort。

2. 預設為 1M 上下文視窗： Claude Opus 5.5 預設提供完整的 1M token 「context window」（上下文視窗），無需 beta 標頭。如果您的用戶端為了與較舊模型相容而傳送上下文視窗 beta 標頭，請將其移除。

3. 對話中途的系統訊息： 在 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 以及 Claude Models on Google Cloud (Google managed) 上，Claude Opus 5.5 接受在 messages 陣列中緊接在使用者輪次之後的 role: "system" 訊息（須遵守放置規則）。對於從一開始就適用的指示，請使用頂層的 system 欄位。Claude Opus 4.7 會以 400 錯誤拒絕 messages 中的 role: "system"。如果您維護的程式碼路徑會為了更新指示而重建完整的訊息歷史，您可以將其簡化，並保留先前各輪的提示快取命中。

4. 拒絕的停止詳細資訊： 當模型拒絕請求時，Claude Opus 5.5 會在 refusal 停止原因之外，另外傳回一個指出拒絕類別的 stop_details 物件。Claude Opus 4.7 也會傳回相同的物件，因此只有在您的停止原因處理邏輯尚未讀取它時，這點才有影響。此功能不需要 beta 標頭，也無法選擇停用。如果您的停止原因處理邏輯尚未讀取它，請參閱處理停止原因。Claude Opus 5.5 會在更多類別中拒絕請求；請參閱安全分類器與備援。

5. 快速模式： Claude Opus 5.5 在 Claude API 上支援「fast mode」（快速模式）。Claude Opus 4.7 不提供快速模式，帶有 speed: "fast" 的請求會傳回錯誤。請在您的請求中設定 speed: "fast"。Claude Opus 5.5 不需要 beta 標頭。

6. 電腦使用工具組與瀏覽器使用工具： Claude Opus 5.5 支援以 computer_toolset_20260801 工具組形式提供的「computer use」（電腦使用），以及用於網頁內任務的「browser use tool」（瀏覽器使用工具）。Claude Opus 4.7 兩者皆不支援。若要將 computer_20251124 整合移轉至工具組，請參閱電腦使用的重大變更。

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

首先請依頁面順序完成每個前面的章節。這些章節包括每個對 Claude Opus 5.5 的請求都必須滿足的條件、在每個回應中處理思考，以及 Claude Opus 5、Claude Opus 4.8 和 Claude Opus 4.7 的章節。這些章節原樣適用於在 Claude Opus 4.6 上執行的程式碼。與 Claude Opus 4.7 一樣，它接受 thinking: {"type": "disabled"}、強制工具選擇以及 computer_20251124 工具。它預設使用 high effort，且除非您要求，否則不會進行思考。Claude Opus 4.5 及更早的 Opus 模型同樣接受 thinking: {"type": "disabled"} 和強制工具選擇，且除非您要求，否則不會進行思考，因此這些章節也適用於它們。

本節補充 Claude Opus 4.7 中的變更，您要替換的模型 ID 為 claude-opus-4-6。其兩個子章節則補充在此之前的變更，供使用 Claude Opus 4.5 或更早版本以及 Claude 4.1 或更早版本的讀者參考。如需檢查清單，請參閱遷移檢查清單中直到列出您所用模型的群組為止的內容。

破壞性變更

1. 移除 extended thinking（擴展思考）： Claude Opus 4.7 及更新的模型不再支援 thinking: {"type": "enabled", "budget_tokens": N}，使用時會傳回 400 錯誤。請改用 adaptive thinking（自適應思考）（thinking: {"type": "adaptive"}），並使用 effort 參數來控制思考深度。在 Claude Opus 5.5 上，自適應思考始終開啟：thinking: {"type": "adaptive"} 是有效的，且等同於完全省略 thinking 欄位。

   之前（Claude Opus 4.6）：

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-4-6",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[{"role": "user", "content": "..."}],
   )

   之後（Claude Opus 5.5），其中模型 ID、thinking 和 output_config 這幾行有所不同：

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-5-5",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   自適應思考可透過提示和 effort 參數來引導，effort 參數取代了思考預算，成為控制模型推理量的方式。請在您自己的評估上進行 effort 掃描，而不是換算 budget_tokens 值。effort 等級表說明了各等級的使用時機，而 Claude Opus 5.5 的建議 effort 等級則涵蓋此模型。

2. 移除取樣參數： 請省略 temperature、top_p 和 top_k。 在 Claude Opus 5.5 上，建議透過提示來引導模型行為。如果您先前使用 temperature = 0 來追求確定性，請注意，它在先前的模型上也從未保證輸出完全相同。

3. 預設省略思考內容： 在 Claude Opus 4.7 及更新的模型上，思考區塊仍會出現在回應串流中，但除非您明確選擇加入，否則其 thinking 欄位為空。這是相對於 Claude Opus 4.6 的無聲變更，Claude Opus 4.6 的預設行為是傳回摘要後的思考文字。若要恢復此行為，請參閱在每個回應中處理思考的第 4 項。

4. 更新的 token 計數： Claude Opus 4.7 引入了新的 tokenizer（分詞器），之後的 Opus 模型（包括 Claude Opus 5.5）也使用此分詞器。它有助於在廣泛的任務上提升效能，且與 Claude Opus 4.7 之前的模型相比，處理文字時可能使用約 1 至 1.35 倍的 token（最多多出約 35%，依內容而異）。

   對於 Claude Opus 5.5，/v1/messages/count_tokens 傳回的 token 數量會與 Claude Opus 4.6 不同。token 效率可能因工作負載型態而異。

   請更新您的 max_tokens 參數以提供額外的餘裕（包括壓縮觸發條件），並重新測試任何在用戶端估算 token 或假設固定 token 與字元比例的程式碼路徑。請使用 Token 計數端點進行驗證。提示介入、task_budget 和 effort 可協助控制成本；這些控制項可能會以模型智慧作為取捨。

5. 移除預填（已在 Claude Opus 4.6 上生效）： 在 Claude Opus 4.6 及更新的 Opus 模型（包括 Claude Opus 5.5）上，預填助理訊息會傳回 400 錯誤，因此只有在您從 Claude Opus 4.5 或更早版本遷移時，這才是一項變更。請改用 structured outputs（結構化輸出）或系統提示指示。

行為變更

Claude Opus 4.7 引入了與 Claude Opus 4.6 不同、但不屬於 API 破壞性變更的行為差異。以下三項會影響程式碼或輔助架構：

1. 代理式追蹤中的內建進度更新： Claude Opus 4.7 在長時間的代理式追蹤過程中，會向使用者提供更規律、品質更高的更新。如果您已加入強制產生中途狀態訊息的輔助架構（「每 3 次工具呼叫後，摘要進度」），請嘗試將其移除。在 Claude Opus 5.5 上，這些更新會出現在 thinking 區塊中，而在預設的 thinking.display 下這些區塊為空。若要接收這些更新，請參閱工具呼叫之間的文字會在思考區塊中傳回。若要調整其長度與內容，請參閱面向使用者的進度更新。

2. 即時網路安全防護措施： 這些防護措施是 Claude Opus 4.7 新增的：涉及禁止或高風險主題的請求可能會遭到拒絕。對於滲透測試、漏洞研究或紅隊演練等正當的安全工作，請申請 Cyber Verification Program 以請求放寬限制。申請途徑取決於您存取 Claude 的方式。

3. 高解析度影像支援： Claude Opus 4.7 是第一個支援高解析度影像的 Claude 模型。最大影像解析度為長邊 2,576 像素，先前模型則為 1,568 像素。這能為視覺密集的工作負載帶來效益，對於電腦使用、螢幕截圖理解和文件分析尤其有價值。

   高解析度支援為自動啟用，不需要 beta 標頭或用戶端選擇加入。有兩件事需要規劃：

   • 全解析度影像使用的影像 token 可能比先前模型多出約 3 倍（每張影像最多 4,784 個 token，先前上限約為 1,600 個 token）。請針對影像密集的工作負載重新規劃 max_tokens 和成本預期，若不需要額外的精細度，請在傳送前降低取樣。
   • 在 Claude Opus 4.7 上，模型傳回的指向和邊界框座標與實際影像像素為 1:1 對應，因此不需要進行縮放比例換算。

   詳情請參閱 Claude Opus 4.7 的高解析度影像支援。

有關提示方面的差異，請參閱提示 Claude Opus 5.5 和提示最佳實務。

從 Claude Opus 4.5 或更早版本遷移

如果您要從 Claude Opus 4.5、Claude Opus 4.1 或更早的模型直接遷移至 Claude Opus 5.5，請從頁面頂端開始閱讀：首先依頁面順序完成每個前面的章節。接著完成本節前面的從 Claude Opus 4.6 遷移的破壞性變更。然後套用以下累積變更，這些變更在 Claude Opus 4.5 到 Claude Opus 4.7 之間生效。如果您使用的是 Claude Opus 4.1 或更早版本，請在完成此子章節後繼續閱讀從 Claude 4.1 或更早版本遷移。

破壞性變更

1. 移除預填已在從 Claude Opus 4.6 遷移的破壞性變更中說明。

2. 工具參數引號處理： Claude Opus 4.6 及更新的模型在工具呼叫引數中可能會產生略有不同的 JSON 字串跳脫（例如，對 Unicode 跳脫或正斜線跳脫的處理不同）。如果您將工具呼叫的 input 當作原始字串解析，而不是使用 JSON 解析器，請檢查您的解析邏輯。標準 JSON 解析器（例如 json.loads() 或 JSON.parse()）會自動處理這些差異。

建議變更

第一項在 Claude Opus 5.5 上為必要；其餘為建議。

1. 遷移至自適應思考（必要）： 在 Claude Opus 4.7 及更新的模型上，thinking: {"type": "enabled", "budget_tokens": N} 會傳回 400 錯誤。變更前後的對照請參閱從 Claude Opus 4.6 遷移的破壞性變更第 1 項。此遷移也會從 client.beta.messages.create() 改為 client.messages.create()：自適應思考和 effort 不需要 beta SDK 命名空間或任何 beta 標頭。

2. 移除 effort beta 標頭： effort 參數不需要 beta 標頭。請從您的請求中移除 effort-2025-11-24 beta。

3. 移除細粒度工具串流 beta 標頭： 細粒度工具串流不需要 beta 標頭。請從您的請求中移除 fine-grained-tool-streaming-2025-05-14 beta。

4. 移除交錯思考 beta 標頭： 使用自適應思考時，交錯思考在每個支援自適應思考的模型上都會自動啟用。請從您的請求中移除 interleaved-thinking-2025-05-14 beta。

5. 遷移至 output_config.format： 如果您使用結構化輸出，請將 output_format={...} 更新為 output_config={"format": {...}}。output_format 參數已被棄用，並將在未來移除。若仍要使用，請加入 structured-outputs-2025-11-13 beta 標頭。若未加入，API 會傳回 400 錯誤。Python SDK（v1.0 及更新版本）在 client.beta.messages.create() 或 count_tokens() 上不接受 output_format={...}。parse() 和 stream() 輔助函式的 output_format=Model 引數維持不變。

從 Claude 4.1 或更早版本遷移

如果您要從 Claude Opus 4.1 或更早的模型直接遷移至 Claude Opus 5.5，請先套用從 Claude Opus 4.5 或更早版本遷移中的所有內容。該子章節從每個前面的章節開始，因此實際上您是從頁面頂端開始閱讀。接著套用本子章節中的額外變更。

額外的破壞性變更

1. 移除取樣參數： 詳見已移除取樣參數。

2. 更新工具版本

   更新至目前的工具版本。移除任何使用 undo_edit 命令的程式碼。

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # 之前
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # 之後
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   • 文字編輯器： 使用 text_editor_20250728 和 str_replace_based_edit_tool。詳情請參閱文字編輯器工具文件。
   • 程式碼執行： 升級至 code_execution_20260521。遷移說明請參閱程式碼執行工具文件。
   • 電腦使用： 使用 computer_toolset_20260801 工具集取代 Claude Opus 5.5 不接受的 computer_20250124。在 Amazon Bedrock 上，computer_20251124 也可以使用。請參閱電腦使用的破壞性變更。

3. 處理 refusal 停止原因

   更新您的應用程式以處理 refusal 停止原因：

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # 適當處理拒絕回應
       pass

4. 處理 model_context_window_exceeded 停止原因

   當生成因達到上下文視窗限制而停止，而非因達到請求的 max_tokens 限制而停止時，Claude 4.5 及更新的模型會傳回 model_context_window_exceeded 停止原因。更新您的應用程式以處理這個新的停止原因：

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # 妥善處理上下文視窗限制
       pass

5. 驗證工具參數處理（結尾換行字元）

   Claude 4.5 及更新的模型會保留工具呼叫字串參數中先前會被移除的結尾換行字元。如果您的工具依賴於對工具呼叫參數進行精確字串比對，請驗證您的邏輯能正確處理結尾換行字元。

6. 針對行為變更更新您的提示

   Claude 4 及更新的模型具有更簡潔、直接的溝通風格，並且需要明確的指示。請參閱提示最佳實務以取得最佳化指引。

額外的建議變更

• Beta 標頭： 移除 token-efficient-tools-2025-02-19 和 output-128k-2025-02-19。所有 Claude 4 及更新的模型都內建了 token 高效的工具使用，這些標頭已不再有任何作用。

從 Claude Sonnet 5 遷移至 Claude Opus 5.5

請完成每個對 Claude Opus 5.5 的請求都必須滿足的條件、在每個回應中處理思考以及從 Claude Opus 5 遷移至 Claude Opus 5.5。請使用 claude-sonnet-5 作為您要替換的模型 ID。最後一個章節原樣適用於在 Claude Sonnet 5 上執行的程式碼，因為 Claude Sonnet 5 與 Claude Opus 5 一樣：

• 預設開啟思考，並接受 thinking: {"type": "disabled"}，且在任何 effort 等級下皆可。
• 接受強制工具選擇和 computer_20251124 工具。
• 以 text 區塊傳回工具呼叫之間的文字。
• 預設使用 high effort。

手動擴展思考、取樣參數以及助理預填在兩個模型上都會回傳 400 錯誤，因此這方面沒有任何變化。Claude Opus 4.8、Claude Opus 4.7 和 Claude Opus 4.6 章節中的必要變更都不適用於您。

變更內容

1. 對話中途的系統訊息： 在 Claude API、Amazon Bedrock、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 以及 Claude Models on Google Cloud (Google managed) 上，Claude Opus 5.5 接受在 messages 陣列中緊接在使用者輪次之後的 role: "system" 訊息（須遵守放置規則）。此功能在 Claude Sonnet 5 上無法使用。如果您維護的程式碼路徑會為了更新指示而重建完整的訊息歷史，您可以將其簡化，並保留先前各輪的提示快取命中。

2. 降低提示快取的最低門檻： Claude Opus 5.5 上可快取提示的最低長度為 512 個 token，低於 Claude Sonnet 5 上的 1,024 個 token。在 Claude Sonnet 5 上因過短而無法快取的提示，現在可以建立快取項目，且無需變更任何程式碼。各模型的最低門檻請參閱提示快取。