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、Google Cloud 和 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 {"type": "auto"}（預設）或 {"type": "none"}。以 {"type": "any"} 或 {"type": "tool", "name": "..."} 強制工具呼叫會被拒絕。請參閱工具選擇的變更前後對照。
• 取樣參數： 省略 temperature、top_p 和 top_k，或將其保留為預設值：任何其他值都會被拒絕。請使用提示來引導模型的行為。
• 預填： 不要以預填的助理回合結束 messages：這會被拒絕。請改用結構化輸出或系統提示指示。在 Amazon Bedrock 上，Claude Opus 5.5 無法使用結構化輸出，因此請在該平台使用系統提示指示。
• 電腦使用： 在 Claude API 和 Google Cloud 上，請將「computer use」（電腦使用）宣告為 computer_toolset_20260801 工具集；較早的 computer_20251124 工具在這些平台上會被拒絕。請參閱電腦使用的重大變更。
• 上下文視窗： 不需要上下文視窗 beta 標頭。1M token 上下文視窗是預設值，為舊模型傳送的標頭不會產生任何效果。

以下請求滿足清單中的每一項：已設定 effort，且沒有 thinking 欄位。會列印文字的 SDK 分頁依區塊類型選取文字，因為 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 加上嚴格工具使用或結構化輸出，或在 Amazon Bedrock 上僅使用 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 API 與 Google Cloud 上來自 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 作為起點。
• 對於代理式工作負載，請考慮使用任務預算（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 計數估算。
• 如果您的應用程式會傳送影像，請針對高解析度影像支援重新編列預算（每張全解析度影像的影像 token 最多約多出 3 倍）。如果您不需要額外的保真度，請在傳送前進行降採樣。
• 如果您會使用模型回傳的指向或邊界框座標，請移除任何縮放係數轉換；在 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 停止原因。
• 確認工具字串參數對結尾換行字元的處理。
• 移除舊版 beta 標頭（token-efficient-tools-2025-02-19、output-128k-2025-02-19）。
• 依照提示最佳實踐檢視並更新提示。

僅限 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、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 會以 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 搭配嚴格工具使用或結構化輸出，並在提示中說明何時適用該工具。嚴格工具使用接受 JSON Schema 的子集，因此在加入 strict: true 之前，請檢查每個工具的 input_schema。結構描述中的每個物件都必須設定 additionalProperties: false；請參閱 JSON Schema 限制。在 Amazon Bedrock 上，Claude Opus 5.5 無法使用結構化輸出（包括嚴格工具使用）。在該平台上，請傳送不含 strict 的 auto，在提示中說明何時適用該工具，並在您的程式碼中驗證工具輸入。請參閱不支援強制工具使用。

變更前。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 與 Google Cloud 上來自 Claude Sonnet 5.5 與 Claude Haiku 5.5 的思考區塊，但無法讀取來自 Claude Fable 或 Claude Mythos 模型的思考區塊。請讓對話保持僅附加（不在對話中途編輯 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 電腦使用工具。

變更前。Claude Opus 5 接受此請求，而在 Claude API 和 Google Cloud 上，Claude Opus 5.5 會以 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 標頭；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" 和 "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）： 對於代理式工作負載，任務預算會告訴模型在完整的代理迴圈中有多少 token 可用。此功能需要 task-budgets-2026-03-13 beta 標頭。

2. 考慮使用對話中途的工具變更（beta）： 對話中途的工具變更可讓您在對話的回合之間新增或移除工具，而不會使較早回合的提示快取命中失效。直接變更 tools 陣列本身會使快取的前綴失效。在 Claude API 上，請傳送 inline-tools-2026-09-15 beta 標頭。較舊的 mid-conversation-tool-changes-2026-07-01 標頭仍可用於以參照方式指定工具的變更，適用於 Claude API、Amazon Bedrock 和 Google Cloud。

從 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 上下文視窗，不需要 beta 標頭。如果您的用戶端為了與舊模型相容而傳送上下文視窗 beta 標頭，請將其移除。

3. 對話中途的系統訊息： 在 Claude API、Amazon Bedrock 和 Google Cloud 上，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 上支援快速模式。Claude Opus 4.7 不提供快速模式，帶有 speed: "fast" 的請求會傳回錯誤。請在您的請求中設定 speed: "fast"。Claude Opus 5.5 不需要 beta 標頭。

6. 電腦使用工具集與瀏覽器使用工具： 在 Claude API 和 Google Cloud 上，Claude Opus 5.5 支援以 computer_toolset_20260801 工具集形式提供的電腦使用，以及用於網頁內任務的瀏覽器使用工具。Claude Opus 4.7 兩者皆不支援。在這些平台上，Claude Opus 5.5 不接受較早的 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 中的變更，並以 claude-opus-4-6 作為您要替換的模型 ID。其兩個子章節補充在此之前的變更，供使用 Claude Opus 4.5 或更早版本和 Claude 4.1 或更早版本的讀者參考。如需檢查清單，請參閱遷移檢查清單中直到列出您模型的群組為止的內容。

重大變更

1. 「Extended thinking」（擴展思考）已移除： thinking: {"type": "enabled", "budget_tokens": N} 在 Claude Opus 4.7 及更新的模型上不再受支援，並會傳回 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. 「Sampling parameters」（取樣參數）已移除： 在 Claude Opus 4.7 及更新的模型（包括 Claude Opus 5.5）上，將 temperature、top_p 或 top_k 設為任何非預設值都會傳回 400 錯誤。Python SDK（v1.0 及更新版本）未定義這些參數，傳入它們會引發 TypeError。最安全的遷移方式是從請求酬載中完全省略這些參數。在 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%，依內容而異）。

   /v1/messages/count_tokens 為 Claude Opus 5.5 傳回的 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 或更早版本遷移時，這才是一項變更。請改用結構化輸出或系統提示指示。在 Amazon Bedrock 上，Claude Opus 5.5 不提供結構化輸出，因此請在該平台使用系統提示指示。

行為變更

Claude Opus 4.7 引入了與 Claude Opus 4.6 不同的行為差異，這些並非 API 重大變更。以下三項會影響程式碼或「scaffolding」（輔助架構）：

1. 「agentic traces」（代理追蹤）中的內建進度更新： 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. 遷移至自適應思考（必要）： thinking: {"type": "enabled", "budget_tokens": N} 在 Claude Opus 4.7 及更新的模型上會傳回 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。遷移說明請參閱程式碼執行工具文件。
   • 電腦使用： 在 Claude API 與 Google Cloud 上，Claude Opus 5.5 僅接受以 computer_toolset_20260801 工具集形式使用電腦使用功能：較早的 computer_20250124 與 computer_20251124 工具在這些平台上會遭到拒絕。請參閱電腦使用重大變更。

3. 處理 refusal 停止原因

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

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

4. 處理 model_context_window_exceeded 停止原因

   當生成因達到「context window」（上下文視窗）限制（而非請求的 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 的「tool use」（工具使用）功能，這些標頭不會產生任何作用。

從 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"}，且就 Claude Sonnet 5 而言，在任何 effort 等級下皆可使用。
• 接受強制工具選擇與 computer_20251124 工具。
• 將工具呼叫之間的文字以 text 區塊傳回。
• 預設為 high effort。

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

變更內容

1. 對話中途的系統訊息： 在 Claude API、Amazon Bedrock 與 Google Cloud 上，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 上因過短而無法快取的提示現在可以建立快取項目，無需變更任何程式碼。各模型的最低門檻請參閱提示快取。