遷移至 Claude Opus 5

Claude Opus 5 相較於 Claude Opus 4.8 是一次跨越式的改進，在深度推理、代理式與長時程任務，以及測試時運算擴展（test-time compute scaling）方面表現強勁。關於行為差異與模型專屬的提示模式，請參閱 Claude Opus 5 提示指南。

Claude Opus 5 是 Claude Opus 4.8 的直接替換升級，定價相同，為每百萬輸入 token 5 美元、每百萬輸出 token 25 美元；請參閱 Claude 定價。對於已在 Claude Opus 4.8 上執行的程式碼，有兩項重大變更，詳見重大變更。Claude Opus 5 支援與 Claude Opus 4.8 相同的功能集，包括 1M token 上下文視窗（預設值，無需 beta 標頭）、128k 最大輸出 token、自適應思考、提示快取、批次處理、Files API、PDF 支援、視覺，以及伺服器端與用戶端工具，但有兩個例外：web fetch 在 Claude Opus 5 上不可用，且 Claude Opus 5 不支援 Priority Tier。各工具的模型可用性請參閱各工具頁面。

從 Claude Opus 4.8 遷移至 Claude Opus 5

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 是不帶日期後綴的固定模型 ID，與 claude-opus-4-8 和 claude-sonnet-5 採用相同的命名方式。

重大變更

1. **思考預設開啟：**在 Claude Opus 4.8 上，不含 thinking 欄位的請求會在不思考的情況下執行；在 Claude Opus 5 上，相同的請求會以自適應思考（adaptive thinking）執行。max_tokens 仍然是總輸出（思考加上回應文字）的硬性上限，因此對於在 Claude Opus 4.8 上不思考執行的工作負載，請重新檢視此設定。即使思考文字未回傳給您，思考 token 仍會以輸出 token 計費，因此儘管每 token 定價不變，在 Claude Opus 4.8 上不思考執行的工作負載在 Claude Opus 5 上每次請求可能會產生更多輸出 token；請參閱成本控制。若要保留舊有行為，請傳入 thinking: {type: "disabled"}，但須受下一項所述的 effort 上限約束；請注意，在停用思考的情況下，模型偶爾可能會以純文字形式輸出工具呼叫，或在其可見輸出中包含內部 XML 標籤，因此在可行的情況下，請優先使用較低的 effort 等級並保持思考開啟；若無法做到，請參閱在停用思考的情況下執行以了解緩解措施。

   回應的結構也隨之改變。開啟思考時，回應可能會在第一個 text 區塊之前以一個或多個 thinking 區塊開頭，而且由於 thinking.display 在 Claude Opus 5 上預設為 "omitted"，這些區塊送達時會帶有空的 thinking 欄位以及其 signature。依位置讀取回覆的程式碼（例如 content[0].text，或將第一個 content_block_start 事件視為文字的串流處理程式）在這些回應上會出錯。請改為依 type 欄位選取內容區塊：從 type 為 "text" 的區塊讀取 text，並在處理串流事件時依區塊類型分支。若要接收可讀的思考摘要而非空的 thinking 欄位，請設定 display: "summarized"；請參閱控制思考顯示。

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

2. **停用思考的上限為 high effort：**您仍然可以使用 thinking: {type: "disabled"} 關閉思考，但僅限於 effort 等級為 high 或以下時。將 thinking: {type: "disabled"} 與 effort xhigh 或 max 組合的請求會回傳 400 錯誤。Claude Opus 4.8 接受此組合，因此請在遷移前稽核停用思考的請求。

   此檢查會在每個請求上強制執行：每個請求的 effort 與思考設定都會獨立驗證，因此在停用思考的情況下將 effort 提高至 xhigh 或 max 的請求會被拒絕，即使對話中較早的請求已被接受。

   之前（Claude Opus 4.8 接受，Claude Opus 5 拒絕）：

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

   

   之後（Claude Opus 5），可以移除 thinking 欄位以重新啟用思考：

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   或保持停用思考並降低 effort：

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

   

建議變更

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

1. **針對能力關鍵型工作測試 max effort：**Claude Opus 5 支援完整的 effort 等級（low、medium、high、xhigh、max）。在最大能力比 token 花費更重要的情況下，請測試 max effort。它能在最具挑戰性的任務上帶來提升，但可能因 token 用量增加而出現報酬遞減，且在較簡單的任務上容易過度思考。如果您以 xhigh 或 max effort 執行，請設定較大的 max_tokens，讓模型有空間思考與行動；從 64k token 開始並據此調整。

2. **考慮自動備援：**Claude Opus 5 隨附網路安全安全分類器，其網路安全類別的拒絕可備援至 Claude Opus 4.8。若要自動在另一個模型上重新執行被拒絕的請求，請考慮使用 fallbacks 參數搭配 "default" 模式（fallbacks: "default"），它會根據拒絕類別選取建議的備援模型，而非使用手動維護的模型清單。伺服器端備援目前為 beta；"default" 模式需要 server-side-fallback-2026-07-01 beta 標頭。請參閱拒絕與備援。

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

4. **在對話中途變更工具（beta）：**您可以在對話的輪次之間新增或移除工具，而不會使較早輪次的提示快取命中失效。請傳送 beta 標頭 mid-conversation-tool-changes-2026-07-01。這對於隨任務進展逐步公開工具或淘汰工具的代理式工作負載很有用；若不使用此功能，變更後的工具清單會使已快取的前綴失效。

5. **重新調整長度與詳細程度提示：**Claude Opus 5 上預設的可見回應與書面交付成果比 Claude Opus 4.8 更長，而降低 effort 會減少思考量，但無法可靠地縮短可見回應。請改為明確提示要求簡潔或目標長度。請參閱回應長度與詳細程度與書面交付成果長度。

6. **移除沿用的驗證指示並限制範圍：**Claude Opus 5 無需指示即會驗證自己的工作，因此請移除從針對較早模型調整的提示中沿用的明確驗證或自我檢查指示；保留它們會導致過度驗證。對於範圍狹窄的任務，請明確限制任務範圍。在多代理框架中，請明確指引哪些情境需要委派，或限制子代理的數量，因為 Claude Opus 5 比較早的模型更容易進行委派。請參閱任務範圍與過度驗證與控制子代理生成。

遷移檢查清單

• 將模型名稱從 claude-opus-4-8 更新為 claude-opus-5。
• 檢視不含 thinking 欄位執行的工作負載：它們在 Claude Opus 5 上會以思考執行。重新檢視 max_tokens（它仍然是總輸出（思考加上回應文字）的硬性上限），或在 effort high 或以下傳入 thinking: {type: "disabled"} 以保留舊有行為。如果您停用思考，請檢視在停用思考的情況下執行，了解可能出現的輸出異常及其提示緩解措施。
• 更新依位置讀取內容的回應解析程式碼，例如 content[0].text 或假設第一個內容區塊為文字的串流處理程式：開啟思考時，thinking 區塊會在 text 區塊之前送達。請改為依 type 選取內容區塊。
• 如果您執行工具使用迴圈，請在回傳工具結果時將 thinking 區塊完整且未經修改地傳回；經修改的區塊會回傳 400 錯誤。請參閱保留思考區塊。
• 確認任何解析 thinking 欄位的程式碼僅將其視為顯示文字。thinking.display 在 Claude Opus 5 上預設為 "omitted"，與 Claude Opus 4.8 相同，因此思考區塊送達時帶有空的 thinking 欄位；設定 display: "summarized" 以接收可讀的摘要。請參閱控制思考顯示。
• 稽核停用思考的請求：thinking: {type: "disabled"} 搭配 effort xhigh 或 max 會回傳 400 錯誤，並在每個請求上強制執行。請重新啟用思考或將 effort 降至 high 或以下。
• 重新評估您的 effort 設定：在您自己的評估上執行全新的 effort 掃描，而非沿用針對較早模型調整的設定。low 與 medium effort 值得作為成本與延遲控制進行測試，並在最大能力比 token 花費更重要的情況下測試 max effort。如果您以 xhigh 或 max effort 執行，請將 max_tokens 提高至至少 64k 作為起點。
• 檢視接近快取最小值的提示：512 token 或以上的提示現在可以建立快取項目，低於 Claude Opus 4.8 上的 1,024 token。
• 處理 stop_reason: "refusal"，並考慮使用 fallbacks: "default"（beta）自動在建議的備援模型上重新執行被拒絕的請求。
• 如果您的組織有 Priority Tier 承諾，請另行規劃容量：Claude Opus 5 不支援 Priority Tier，而 Claude Opus 4.8 則保留支援。
• 對於代理式工作負載，請考慮任務預算（beta）與對話中途工具變更（beta）。
• 重新調整長度與詳細程度提示：Claude Opus 5 上預設的可見回應與書面交付成果更長，而降低 effort 會減少思考量，但無法可靠地縮短可見回應。請明確提示要求簡潔或目標長度。請參閱回應長度與詳細程度與書面交付成果長度。
• 移除從針對較早模型調整的提示中沿用的驗證與自我檢查指示（它們在 Claude Opus 5 上會導致過度驗證），對範圍狹窄的任務明確限制任務範圍，並在多代理框架中引導或限制子代理委派。請參閱任務範圍與過度驗證與控制子代理生成。
• 在您自己的工作負載上重新建立成本與延遲基準。每 token 定價與 Claude Opus 4.8 相同，但思考 token 以輸出 token 計費，因此原本不思考執行的工作負載每次請求可能會產生更多輸出 token。

從 Claude Opus 4.7 遷移至 Claude Opus 5

Claude Opus 5 在現有的 Claude Opus 4.7 提示與評估上應具有強勁的開箱即用效能，定價相同，為每百萬輸入 token 5 美元、每百萬輸出 token 25 美元。它支援與 Claude Opus 4.7 相同的功能集，包括 1M token 上下文視窗、128k 最大輸出 token、自適應思考、提示快取、批次處理、Files API、PDF 支援、視覺，以及伺服器端與用戶端工具，但有兩個例外：web fetch 在 Claude Opus 5 上不可用，且 Claude Opus 5 不支援 Priority Tier。它還新增了對話中途系統訊息，並公開記載了拒絕停止詳細資訊。在 Claude API 與 Google Cloud 上，Claude Opus 5 還支援以穩定的 computer_toolset_20260801 工具集形式提供的電腦使用，以及用於網頁內任務的瀏覽器使用工具，這兩者 Claude Opus 4.7 皆不支援；使用較早 computer_20251124 版本的現有整合在兩個模型上皆可繼續正常運作。若要升級現有整合，請參閱從 computer_20251124 遷移。

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After

重大變更

1. **思考預設開啟：**在 Claude Opus 4.7 上，不含 thinking 欄位的請求會在不思考的情況下執行；在 Claude Opus 5 上，相同的請求會以自適應思考執行。max_tokens 仍然是總輸出（思考加上回應文字）的硬性上限，因此對於在 Claude Opus 4.7 上不思考執行的工作負載，請重新檢視此設定。即使思考文字未回傳給您，思考 token 仍會以輸出 token 計費，因此儘管每 token 定價不變，在 Claude Opus 4.7 上不思考執行的工作負載在 Claude Opus 5 上每次請求可能會產生更多輸出 token；請參閱成本控制。若要保留舊有行為，請傳入 thinking: {type: "disabled"}，但須受下一項所述的 effort 上限約束；請注意，在停用思考的情況下，模型偶爾可能會以純文字形式輸出工具呼叫，或在其可見輸出中包含內部 XML 標籤，因此在可行的情況下，請優先使用較低的 effort 等級並保持思考開啟；若無法做到，請參閱在停用思考的情況下執行以了解緩解措施。

   回應的結構也隨之改變。開啟思考時，回應可能會在第一個 text 區塊之前以一個或多個 thinking 區塊開頭，而且由於 thinking.display 在 Claude Opus 5 上預設為 "omitted"，這些區塊送達時會帶有空的 thinking 欄位以及其 signature。依位置讀取回覆的程式碼（例如 content[0].text，或將第一個 content_block_start 事件視為文字的串流處理程式）在這些回應上會出錯。請改為依 type 欄位選取內容區塊：從 type 為 "text" 的區塊讀取 text，並在處理串流事件時依區塊類型分支。若要接收可讀的思考摘要而非空的 thinking 欄位，請設定 display: "summarized"；請參閱控制思考顯示。

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

2. **停用思考的上限為 high effort：**您可以使用 thinking: {type: "disabled"} 關閉思考，但僅限於 effort 等級為 high 或以下時。將 thinking: {type: "disabled"} 與 effort xhigh 或 max 組合的請求會回傳 400 錯誤。Claude Opus 4.7 接受此組合，因此請在遷移前稽核停用思考的請求。

   此檢查會在每個請求上強制執行：每個請求的 effort 與思考設定都會獨立驗證，因此在停用思考的情況下將 effort 提高至 xhigh 或 max 的請求會被拒絕，即使對話中較早的請求已被接受。

   之前（Claude Opus 4.7 接受，Claude Opus 5 拒絕）：

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

   

   之後（Claude Opus 5），可以移除 thinking 欄位以開啟思考執行：

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   或保持停用思考並降低 effort：

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

   

變更內容

以下項目並非重大變更；它們描述了在您更換模型 ID 後值得檢查的行為差異。

1. **取樣參數（未變更）：**將 temperature、top_p 或 top_k 設為非預設值在 Claude Opus 5 上會回傳 400 錯誤，與 Claude Opus 4.7 相同。大多數 SDK 為了與較早模型相容仍定義這些欄位，因此設定它們的程式碼可通過型別檢查，即使 API 會拒絕該請求。Python SDK（v1.0 及更新版本）未定義這些欄位，傳入它們會引發 TypeError。如果您在遷移至 Opus 4.7 時已移除這些參數，則無需進一步變更。

2. **Effort 預設為 high：**Claude Opus 5 上的 effort 參數在 Claude API 與 Claude Code 上預設為 high。如果您已明確設定 effort，您的設定不變。

3. **Effort 等級重新校準：**與 Claude Opus 4.7 相比，Claude Opus 5 上每個 effort 等級背後的 token 分配有所改變，且 Claude Opus 5 支援完整的 effort 等級（low、medium、high、xhigh、max）。請在您自己的評估上執行全新的 effort 掃描，而非沿用針對 Claude Opus 4.7 調整的設定。low 與 medium effort 值得作為成本與延遲控制進行測試，並在最大能力比 token 花費更重要的情況下測試 max effort。如果您以 xhigh 或 max effort 執行，請設定較大的 max_tokens，讓模型有空間思考與行動；從 64k token 開始並據此調整。請參閱 Effort。

4. **1M 上下文視窗為預設值：**Claude Opus 5 預設提供完整的 1M token 上下文視窗，無需 beta 標頭，也無長上下文加價。如果您的用戶端為了與較舊模型相容而傳送上下文視窗 beta 標頭，您可以在 Claude Opus 5 上將其移除。

5. **對話中途系統訊息：**Claude Opus 5 接受在 messages 陣列中緊接於使用者輪次之後的 role: "system" 訊息（須遵守放置規則）。對於從一開始就適用的指示，請使用頂層 system 欄位。Claude Opus 4.7 會以 400 錯誤拒絕 messages 中的 role: "system"。如果您維護著為了更新指示而重建完整訊息歷史的程式碼路徑，您可以將其簡化，並保留較早輪次的提示快取命中。

6. **拒絕停止詳細資訊：**拒絕回應上的 stop_details 物件（自 Claude Opus 4.7 起可用）現已公開記載。當模型拒絕請求時，除了現有的 refusal 停止原因外，它還會識別拒絕的類別。無需 beta 標頭，也無法選擇退出。請參閱處理停止原因。

7. **較低的提示快取最小值：**Claude Opus 5 上可快取的最小提示長度為 512 token，低於 Claude Opus 4.7。在 Claude Opus 4.7 上因過短而無法快取的提示現在可以建立快取項目，無需變更程式碼。各模型的最小值請參閱提示快取。

8. **快速模式：**Claude Opus 5 支援快速模式（研究預覽）；快速模式在 Claude Opus 4.7 上不可用，帶有 speed: "fast" 的請求會回傳錯誤。speed: "fast" 參數與 fast-mode-2026-02-01 beta 標頭在 Claude Opus 5 上可照常運作。

建議變更

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

1. **考慮自動備援：**Claude Opus 5 隨附網路安全安全分類器，其網路安全類別的拒絕可備援至 Claude Opus 4.8。若要自動在另一個模型上重新執行被拒絕的請求，請考慮使用 fallbacks 參數搭配 "default" 模式（fallbacks: "default"），它會根據拒絕類別選取建議的備援模型，而非使用手動維護的模型清單。伺服器端備援目前為 beta；"default" 模式需要 server-side-fallback-2026-07-01 beta 標頭。請參閱拒絕與備援。

2. **在對話中途變更工具（beta）：**您可以在對話的輪次之間新增或移除工具，而不會使較早輪次的提示快取命中失效。請傳送 beta 標頭 mid-conversation-tool-changes-2026-07-01。這對於隨任務進展逐步公開工具或淘汰工具的代理式工作負載很有用；若不使用此功能，變更後的工具清單會使已快取的前綴失效。

3. **重新調整長度與詳細程度提示：**Claude Opus 5 上預設的可見回應與書面交付成果比較早的 Opus 模型更長，而降低 effort 會減少思考量，但無法可靠地縮短可見回應。請改為明確提示要求簡潔或目標長度。請參閱回應長度與詳細程度與書面交付成果長度。

4. **移除沿用的驗證指示並限制範圍：**Claude Opus 5 無需指示即會驗證自己的工作，因此請移除從針對較早模型調整的提示中沿用的明確驗證或自我檢查指示；保留它們會導致過度驗證。對於範圍狹窄的任務，請明確限制任務範圍。在多代理框架中，請明確指引哪些情境需要委派，或限制子代理的數量，因為 Claude Opus 5 比較早的模型更容易進行委派。請參閱任務範圍與過度驗證與控制子代理生成。

遷移檢查清單

• 將模型名稱從 claude-opus-4-7 更新為 claude-opus-5（或更新別名）。
• 檢視不含 thinking 欄位執行的工作負載：它們在 Claude Opus 5 上會以思考執行。重新檢視 max_tokens（它仍然是總輸出（思考加上回應文字）的硬性上限），或在 effort high 或以下傳入 thinking: {type: "disabled"} 以保留舊有行為。如果您停用思考，請檢視在停用思考的情況下執行，了解可能出現的輸出異常及其提示緩解措施。
• 更新依位置讀取內容的回應解析程式碼，例如 content[0].text 或假設第一個內容區塊為文字的串流處理程式：開啟思考時，thinking 區塊會在 text 區塊之前送達。請改為依 type 選取內容區塊。
• 如果您執行工具使用迴圈，請在回傳工具結果時將 thinking 區塊完整且未經修改地傳回；經修改的區塊會回傳 400 錯誤。請參閱保留思考區塊。
• 確認任何解析 thinking 欄位的程式碼僅將其視為顯示文字。thinking.display 在 Claude Opus 5 上預設為 "omitted"，與 Claude Opus 4.7 相同，因此思考區塊送達時帶有空的 thinking 欄位；設定 display: "summarized" 以接收可讀的摘要。請參閱控制思考顯示。
• 稽核停用思考的請求：thinking: {type: "disabled"} 搭配 effort xhigh 或 max 會回傳 400 錯誤，並在每個請求上強制執行。請重新啟用思考或將 effort 降至 high 或以下。
• 如果您在 Opus 4.7 遷移期間已移除取樣參數，則無需採取任何動作。如果您以 400 重試路徑重新加入了它們，請移除該重試路徑。
• 重新評估您的 effort 設定：在您自己的評估上執行全新的 effort 掃描，而非沿用針對 Claude Opus 4.7 調整的設定。測試 low 與 medium effort 作為成本與延遲控制，並在最大能力比 token 花費更重要的情況下測試 max effort。如果您以 xhigh 或 max effort 執行，請將 max_tokens 提高至至少 64k 作為起點。
• 移除任何上下文視窗 beta 標頭。1M 上下文視窗在 Claude API、Amazon Bedrock、Google Cloud 與 Microsoft Foundry 上皆為預設值。
• 如果您為了更新指示而重建對話歷史，請考慮改用對話中途系統訊息以保留提示快取命中。
• 確認您的停止原因處理會在拒絕時讀取 stop_details（自 Claude Opus 4.7 起可用；現已公開記載），並考慮使用 fallbacks: "default"（beta）自動在建議的備援模型上重新執行被拒絕的請求。
• 檢視接近快取最小值的提示：512 token 或以上的提示現在可以建立快取項目。
• 如果您使用 web fetch，請規劃替代方案：它在 Claude Opus 5 上不可用。
• 如果您的組織有 Priority Tier 承諾，請注意 Claude Opus 5 不支援 Priority Tier。
• 如果您在 Claude Opus 4.7 上使用快速模式，除了模型 ID 之外無需變更請求：speed: "fast" 與 fast-mode-2026-02-01 beta 標頭在 Claude Opus 5 上可照常運作。
• 對於代理式工作負載，請考慮任務預算（beta）與對話中途工具變更（beta）。
• 重新調整長度與詳細程度提示，並移除從針對較早模型調整的提示中沿用的驗證與自我檢查指示。
• 在您選擇的 effort 等級上重新建立成本與延遲基準。每 token 定價與 Claude Opus 4.7 相同，但思考 token 以輸出 token 計費，因此原本不思考執行的工作負載每次請求可能會產生更多輸出 token。

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

Claude Opus 5 在現有的 Claude Opus 4.6 提示與評估上應具有強勁的開箱即用效能，且定價相同，但在遷移時有一些值得了解的行為與 API 變更。這些變更大多在 Claude Opus 4.7 中生效；另外兩項（思考預設開啟，以及停用思考的 effort 上限）則在 Claude Opus 5 上生效。本節涵蓋所有這些變更，因此對於直接從 Claude Opus 4.6 遷移的程式碼而言是完整的。Claude Opus 5 支援與 Claude Opus 4.6 相同的功能集，包括：

• 1M token 上下文視窗，採標準 API 定價，無長上下文加價
• 128k 最大輸出 token
• 自適應思考
• 提示快取
• 批次處理
• Files API
• PDF 支援
• 視覺
• 伺服器端與用戶端工具（bash、程式碼執行、電腦使用、文字編輯器、網頁搜尋、MCP 連接器、記憶）

兩個例外：web fetch 在 Claude Opus 5 上不可用，且 Claude Opus 5 不支援 Priority Tier。在 Claude API 與 Google Cloud 上，Claude Opus 5 還支援以穩定的 computer_toolset_20260801 工具集形式提供的電腦使用，以及用於網頁內任務的瀏覽器使用工具，這兩者 Claude Opus 4.6 或更早的 Opus 模型皆不支援；使用較早 computer_20251124 版本的現有整合在 Claude Opus 5 上可繼續正常運作。若要升級現有整合，請參閱從 computer_20251124 遷移。

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

重大變更

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

   之前（Claude Opus 4.6）：

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

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

   之後（Claude Opus 5）：

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

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

   自適應思考可透過提示與 effort 參數進行引導；請參閱選擇 effort 等級。

2. 思考預設為開啟： 在 Claude Opus 4.6 與 Claude Opus 4.7 上，沒有 thinking 欄位的請求會在不思考的情況下執行；在 Claude Opus 5 上，相同的請求會以自適應思考執行。max_tokens 仍然是總輸出（思考加上回應文字）的硬性上限，因此對於先前不使用思考執行的工作負載，請重新檢視此設定。即使思考文字未回傳給您，思考 token 仍會以輸出 token 計費，因此儘管每 token 的定價不變，先前不使用思考執行的工作負載在 Claude Opus 5 上每個請求可能會產生更多輸出 token；請參閱成本控制。若要保留舊有行為，請傳入 thinking: {type: "disabled"}，但須受下一項所述的 effort 上限約束；請注意，在停用思考的情況下，模型偶爾可能會以純文字形式輸出工具呼叫，或在其可見輸出中包含內部 XML 標籤，因此在可行的情況下，請優先選擇啟用思考並搭配較低的 effort 等級；若無法這麼做，請參閱在停用思考的情況下執行以了解緩解措施。

   回應的結構也會隨之改變。在思考開啟的情況下，回應可能會在第一個 text 區塊之前以一個或多個 thinking 區塊開頭，而且由於 Claude Opus 5 預設會省略思考內容（本清單第 5 項），這些區塊送達時其 thinking 欄位為空，並附帶其 signature。依位置讀取回覆的程式碼（例如 content[0].text，或將第一個 content_block_start 事件視為文字的串流處理程式）在處理這些回應時會出錯。請改為依 type 欄位選取內容區塊：從 type 為 "text" 的區塊讀取 text，並在處理串流事件時依區塊類型進行分支。

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

3. 停用思考的上限為 high effort： 您可以使用 thinking: {type: "disabled"} 關閉思考，但僅限於 effort 等級為 high 或以下時。在 Claude Opus 5 上，將 thinking: {type: "disabled"} 與 effort xhigh 或 max 結合的請求會回傳 400 錯誤，且會對每個請求強制執行。在遷移之前，請稽核停用思考的請求：重新啟用思考，或將 effort 降低至 high 或以下。

4. 取樣參數已移除： 在 Claude Opus 4.7 或更新的模型（包括 Claude Opus 5）上，將 temperature、top_p 或 top_k 設定為任何非預設值都會回傳 400 錯誤。Python SDK（v1.0 及更新版本）未定義這些參數，傳入它們會引發 TypeError。最安全的遷移路徑是從請求負載中完全省略這些參數。在 Claude Opus 5 上，建議使用提示來引導模型行為。如果您先前使用 temperature = 0 來追求確定性，請注意它在先前的模型上從未保證產生完全相同的輸出。

5. 思考內容預設省略： 在 Claude Opus 4.7 及更新的模型上，思考區塊仍會出現在回應串流中，但除非您明確選擇加入，否則其 thinking 欄位為空。這是相對於 Claude Opus 4.6 的一項靜默變更，在 Claude Opus 4.6 上預設會回傳摘要後的思考文字。若要恢復摘要後的思考內容，請將 thinking.display 設定為 "summarized"：

   PythonTypeScriptC#GoJavaPHPRuby

   

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

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

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

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

   提示介入、task_budget 與 effort 有助於控制成本並確保適當的 token 使用量。這些控制項可能會以模型智慧作為取捨。請更新您的 max_tokens 參數以提供額外的餘裕，包括壓縮觸發條件。Claude Opus 5 以標準 API 定價提供 1M 的上下文視窗，無長上下文加價。

7. 預填移除（沿用自 Opus 4.6）： 在 Claude Opus 4.7 及更新的模型（包括 Claude Opus 5）上，預填助理訊息會回傳 400 錯誤。請改用結構化輸出、系統提示指令或 output_config.format。

選擇 effort 等級

effort 參數讓您能夠在 Claude 的智慧與 token 花費之間進行調整，以能力換取更快的速度與更低的成本。Claude Opus 5 支援完整的 effort 等級集合，預設為 high。請在您自己的評估上重新進行一次 effort 掃描，而非沿用為早期模型調校的設定：

• max： 可在最嚴苛的任務上帶來增益，但可能因 token 使用量增加而呈現遞減的回報，且在較簡單的任務上容易過度思考。請在最大能力比 token 花費更重要的情境中測試它。
• xhigh： 為需要比預設更深入的長時間執行代理與程式設計工作提供擴展能力。
• high： 預設值。在大多數任務上平衡 token 使用量與智慧。
• medium： 相對於預設值的節省成本降級選項，值得作為成本與延遲控制進行測試。
• low： 最有效率。保留給簡短、範圍明確的任務以及對延遲敏感的工作負載。

如果您以 xhigh 或 max effort 執行，請設定較大的 max_tokens，讓模型有空間思考與行動；從 64k token 開始，再從那裡進行調校。對此模型而言，effort 比任何先前的 Opus 都更重要。升級時請積極地對其進行實驗。

行為變更

Claude Opus 4.7 引入了數項與 Claude Opus 4.6 不同的行為差異，這些並非 API 重大變更，但可能需要更新提示或移除鷹架。它們延續至 Claude Opus 5，並附帶本清單中註明的調整。

1. 回應長度因使用情境而異： Claude Opus 4.7 會根據其判斷的任務複雜度來校準回應長度，而非預設採用固定的詳盡程度。這通常意味著在簡單查詢上回答較短，而在開放式分析上回答長得多。

   如果您的產品依賴特定風格或詳盡程度的輸出，您可能需要調校您的提示。例如，若要降低詳盡程度，請加入：「Provide concise, focused responses. Skip non-essential context, and keep examples minimal.」如果您看到特定類型的過度解釋，請在提示中加入針對性的指令以防止它們。

   展示 Claude 如何以適當簡潔程度進行溝通的正面範例，往往比負面範例或告訴模型不要做什麼的指令更有效。在 Claude Opus 5 上，預設的可見回應與書面交付成果比早期 Opus 模型更長，而降低 effort 會減少思考量，但無法可靠地縮短可見回應；請明確提示要求簡潔或目標長度。請參閱回應長度與詳盡程度。

2. 更字面化的指令遵循： Claude Opus 4.7 比 Claude Opus 4.6 更字面化且更明確地解讀提示，尤其是在較低的 effort 等級下。它不會靜默地將一項指令從一個項目推廣到另一個項目，也不會推斷您未提出的請求。這種字面化的好處是精確且較少反覆。對於具有精心調校提示的 API 使用情境、結構化擷取，以及您希望行為可預測的管線，它通常表現更好。對於遷移至 Claude Opus 5，進行提示與測試框架審查可能特別有幫助。

3. 更直接的語氣： 與任何新模型一樣，長篇寫作的散文風格可能會有所改變。Claude Opus 4.7 更直接且更有主見，與 Claude Opus 4.6 較溫暖的風格相比，較少以認同為先的措辭，表情符號也較少。如果您的產品依賴特定的語調，請針對新的基準重新評估風格提示。

4. 代理追蹤中內建的進度更新： Claude Opus 4.7 在長時間的代理追蹤過程中，會向使用者提供更規律、更高品質的更新。如果您曾加入鷹架來強制產生中間狀態訊息（「After every 3 tool calls, summarize progress」），請嘗試移除它。如果您發現 Claude Opus 4.7 面向使用者的更新在長度或內容上未能妥善校準至您的使用情境，請在提示中明確描述這些更新應有的樣貌並提供範例。

5. 子代理產生方式已變更： Claude Opus 4.7 預設傾向比 Claude Opus 4.6 產生更少的子代理，而 Claude Opus 5 則比早期模型更樂於委派給子代理。此行為可透過提示朝任一方向引導；請針對何時需要子代理給予明確指引，或限制子代理的數量。請參閱控制子代理產生。

6. 更嚴格的 effort 校準： 與 Claude Opus 4.6 相比有顯著改變，Claude Opus 4.7 嚴格遵守 effort 等級，尤其是在低端。在 low 與 medium 下，模型會將其工作範圍限定於所要求的內容，而非做得比要求更多。

   這對延遲與成本有利，但對於以 low effort 執行的中等複雜任務，存在一些思考不足的風險。如果您在複雜問題上觀察到淺層推理，請將 effort 提高至 high 或 xhigh，而非透過提示來繞過它。

   如果您為了延遲需要將 effort 維持在 low，請加入針對性的指引：「This task involves multistep reasoning. Think carefully through the problem before responding.」請參閱 Claude Opus 4.7 的建議 effort 等級。

7. 預設較少的工具呼叫： Claude Opus 4.7 傾向比 Claude Opus 4.6 更少使用工具，而更多使用推理。這在大多數情況下會產生更好的結果。

   若要增加工具使用量，請提高 effort 設定。high 或 xhigh effort 設定在代理搜尋與程式設計中顯示出明顯更多的工具使用。您也可以調整提示，明確指示模型何時以及如何正確使用其工具。

8. 即時網路安全防護措施： Claude Opus 4.7 新增的功能，涉及禁止或高風險主題的請求可能會導致拒絕。對於合法的安全工作，例如滲透測試、漏洞研究或紅隊演練，請申請 Cyber Verification Program 以請求降低限制。申請途徑取決於您存取 Claude 的方式。

9. 高解析度影像支援： 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 上的高解析度影像支援。

建議變更

這些並非必要，但會改善您的體驗：

1. 重新評估 max_tokens： 由於相同的文字在 Claude Opus 4.7 及更新的模型上會產生更高的 token 計數，請更新您的 max_tokens 參數以提供額外的餘裕，包括壓縮觸發條件。提示介入、task_budget 與 effort 有助於控制成本並確保適當的 token 使用量。

2. 稽核 token 計數預期： 任何在用戶端估算 token 或假設固定 token 對字元比率的程式碼路徑，都應針對 Claude Opus 5 重新測試。請使用 Token 計數端點進行驗證。

3. 採用 task budgets（任務預算）（beta）： Claude Opus 4.7 引入了任務預算。這些預算讓您能夠告知 Claude 它在完整的代理迴圈中有多少 token 可用，包括思考、工具呼叫、工具結果與最終輸出。模型會看到持續的倒數計數，並利用它來排定工作優先順序，並在預算消耗時優雅地完成任務。若要使用，請設定 beta 標頭 task-budgets-2026-03-13，並將以下內容加入您的輸出設定：

   PythonTypeScriptC#GoJavaPHPRuby

   

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   您可能需要針對您的使用情境實驗不同的任務預算。如果給予模型的任務預算過於嚴格，它可能會較不徹底地完成任務，並將其預算視為限制條件。

   對於品質比速度更重要的開放式代理任務，請勿設定任務預算。請將任務預算保留給您需要模型將其工作範圍限定於 token 配額的工作負載。任務預算的最小值為 20k token。

   任務預算並非硬性上限；它是模型所知悉的建議。它與 max_tokens 不同：

   • task_budget： 橫跨完整代理迴圈的建議性上限。模型會看到它並利用它來調整自己的步調。
   • max_tokens： 每個請求所產生 token 的硬性上限。它不會傳遞給模型，因此模型不知道它的存在。

   當您希望模型自我調節時使用 task_budget，並使用 max_tokens 作為限制使用量的硬性上限。

4. 在 max 或 xhigh effort 下設定較大的 max_tokens： 如果您以 max 或 xhigh effort 執行 Claude Opus 4.7 或更新的模型，請設定較大的最大輸出 token 預算，讓模型有空間在其子代理與工具呼叫之間思考與行動。從 64k token 開始，再從那裡進行調校。

5. 若不需要高解析度，請對影像進行降採樣： Claude Opus 4.7 及更新的模型支援最高 2576px / 3.75MP 的影像。高解析度影像會使用更多 token。如果不需要額外的影像保真度，請在傳送給 Claude 之前對影像進行降採樣，以避免 token 使用量增加。請參閱影像與視覺。

6. 考慮自動備援： Claude Opus 5 隨附網路安全安全分類器，其網路類別的拒絕可以備援至 Claude Opus 4.8。若要自動在另一個模型上重新執行被拒絕的請求，請考慮使用 fallbacks 參數搭配 "default" 模式（fallbacks: "default"），它會根據拒絕類別選擇建議的備援模型，而非使用手動維護的模型清單。伺服器端備援處於 beta 階段；"default" 模式需要 server-side-fallback-2026-07-01 beta 標頭。請參閱拒絕與備援。

7. 快取較短的提示： Claude Opus 5 上可快取的最小提示長度為 512 個 token，低於早期的 Opus 模型。先前因太短而無法快取的提示現在可以建立快取項目，無需變更程式碼。各模型的最小值請參閱提示快取。

8. 在對話中途變更工具（beta）： 您可以在對話的輪次之間新增或移除工具，而不會使先前輪次的提示快取命中失效。請傳送 beta 標頭 mid-conversation-tool-changes-2026-07-01。這對於隨著任務推進而逐步公開工具或淘汰工具的代理工作負載很有用；若沒有它，變更後的工具清單會使快取的前綴失效。

9. 移除沿用的驗證指令並限制範圍： Claude Opus 5 會在未被告知的情況下驗證自己的工作，因此請移除從為早期模型調校的提示中沿用而來的明確驗證或自我檢查指令；保留它們會導致過度驗證。對於範圍狹窄的任務，請明確限制任務範圍。請參閱任務範圍與過度驗證。

遷移檢查清單

• 將模型名稱從 claude-opus-4-6 更新為 claude-opus-5（或更新別名）。
• 從請求負載中移除 temperature、top_p 與 top_k。
• 將 thinking: {type: "enabled", budget_tokens: N} 替換為 thinking: {type: "adaptive"} 加上 effort 參數，或完全移除 thinking 欄位；自適應思考在 Claude Opus 5 上預設為開啟。
• 檢視先前在沒有 thinking 欄位的情況下執行的工作負載：它們在 Claude Opus 5 上會以思考模式執行。重新檢視 max_tokens（它仍然是總輸出（思考加上回應文字）的硬性上限），或在 effort high 或以下傳入 thinking: {type: "disabled"} 以保留舊有行為。
• 更新依位置讀取內容的回應解析，例如 content[0].text 或假設第一個內容區塊為文字的串流處理程式：在思考開啟的情況下，thinking 區塊會在 text 區塊之前送達。請改為依 type 選取內容區塊。
• 如果您執行工具使用迴圈，請在回傳工具結果時將 thinking 區塊完整且未經修改地傳回；經修改的區塊會回傳 400 錯誤。請參閱保留思考區塊。
• 稽核停用思考的請求：thinking: {type: "disabled"} 搭配 effort xhigh 或 max 會回傳 400 錯誤，且會對每個請求強制執行。重新啟用思考，或將 effort 降低至 high 或以下。
• 移除任何助理訊息預填。
• 如果您的 UI 會顯示思考內容，請明確選擇加入思考摘要。
• 在更新的分詞方式下重新對端對端成本與延遲進行基準測試；思考 token 以輸出 token 計費，因此先前不使用思考執行的工作負載每個請求也可能產生更多輸出 token。
• 重新調校 max_tokens 以因應更新的分詞方式。
• 重新測試任何用戶端 token 計數估算。
• 如果您的應用程式會傳送影像，請為高解析度影像支援重新規劃預算（每張全解析度影像的影像 token 最多約多出 3 倍）。如果您不需要額外的保真度，請在傳送前進行降採樣。
• 如果您使用模型回傳的指向或邊界框座標，請移除任何縮放係數轉換；在 Claude Opus 4.7 及更新的模型上，座標與實際影像像素為 1:1。
• 針對行為變更檢視提示（回應長度、字面化、語氣、進度更新、子代理、effort 校準、工具觸發、網路安全防護措施、高解析度影像處理）。
• 在移除現有長度控制提示的情況下重新建立回應長度基準，然後明確進行調校。
• 如果使用 xhigh 或 max effort，請將 max_tokens 提高至至少 64k 作為起點。
• 考慮為代理工作流程採用任務預算（beta）與對話中途工具變更（beta）。
• 處理 stop_reason: "refusal"，並考慮使用 fallbacks: "default"（beta）以自動在建議的備援模型上重新執行被拒絕的請求。
• 檢視接近快取最小值的提示：512 個 token 或以上的提示現在可以在 Claude Opus 5 上建立快取項目。
• 如果您使用 web fetch，請規劃替代方案：它在 Claude Opus 5 上不可用。
• 如果您的組織有 Priority Tier 承諾，請注意 Claude Opus 5 不支援 Priority Tier。
• 移除從為早期模型調校的提示中沿用而來的驗證與自我檢查指令；它們會在 Claude Opus 5 上導致過度驗證。
• 如果您的產品從事合法的安全工作，請申請 Cyber Verification Program 以取得較低的網路安全內容限制。

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

如果您要從 Claude Opus 4.5、Opus 4.1 或更早的模型直接遷移至 Claude Opus 5，請套用本節前述的所有變更，再加上以下在 Opus 4.5 與 Opus 4.7 之間生效的累積變更。如果您是從 Opus 4.6 遷移，本節前述的變更就是您所需的全部。

更新您的模型名稱

# Opus 遷移
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

重大變更

1. 預填移除已涵蓋於從 Claude Opus 4.6 遷移的重大變更中。

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

建議變更

這些變更會改善您在 Claude Opus 4.7 及更新模型上的體驗。標記為**（Opus 4.7 上為必要）**的項目在 Opus 4.6 推出時是選擇性建議，但現在是強制性的；其餘仍為建議。

1. 遷移至自適應思考（Opus 4.7 上為必要）： thinking: {type: "enabled", budget_tokens: N} 在 Claude Opus 4.7 及更新的模型上會回傳 400 錯誤。請改用 thinking: {type: "adaptive"} 並使用 effort 參數來控制思考深度；在 Claude Opus 5 上，thinking: {type: "adaptive"} 等同於省略 thinking 欄位，後者預設會以自適應思考執行。請參閱思考。

   cURLBeforeAfterCLITypeScriptC#GoJavaPHPRuby

   

   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[{"role": "user", "content": "Your prompt here"}],
   )

   請注意，此遷移也會從 client.beta.messages.create 移至 client.messages.create。自適應思考與 effort 不需要 beta SDK 命名空間或任何 beta 標頭。

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

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

4. 移除交錯思考 beta 標頭： 自適應思考會在 Claude Opus 4.7、Opus 4.6 與 Sonnet 4.6 上自動啟用交錯思考。請從您的請求中移除 betas=["interleaved-thinking-2025-05-14"]。此標頭在 Sonnet 4.6 上搭配手動擴展思考仍然有效，但手動模式已被棄用。

5. 遷移至 output_config.format： 如果使用結構化輸出，請將 output_format={...} 更新為 output_config={"format": {...}}。API 仍接受已棄用的 output_format 參數，但它將在未來的模型版本中移除。Python SDK（v1.0 及更新版本）在 client.beta.messages.create() 或 count_tokens() 上不接受 output_format={...}。parse() 與 stream() 輔助函式的 output_format=Model 引數維持不變。

從 Claude 4.1 或更早版本遷移

如果您要從 Opus 4.1 或更早的模型直接遷移至 Claude Opus 5，請套用本節前述的所有變更，再加上本小節中的額外變更。

# 從 Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# 從 Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

額外的重大變更

1. 移除取樣參數

   從 Claude Opus 4.7 開始，將 temperature、top_p 或 top_k 設定為任何非預設值都會回傳 400 錯誤。Python SDK（v1.0 及更新版本）未定義這些參數，傳入它們會引發 TypeError。最安全的遷移路徑是從請求中完全省略這些參數，並使用提示來引導模型的行為。如果您先前使用 temperature = 0 來追求確定性，請注意它從未保證產生完全相同的輸出。

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 之前 - 這在 Claude 4+ 模型中會發生錯誤
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
       # ...
   )
   
   # 之後
   response = client.messages.create(
       model="claude-opus-5",
       # ...
   )

2. 更新工具版本

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 之前
   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。遷移說明請參閱程式碼執行工具文件。

3. 處理 refusal 停止原因

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   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

   

   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 Opus 4.5 或更早版本）

• 將模型 ID 更新為 claude-opus-5
• 套用所有從 Claude Opus 4.6 遷移的重大變更（移除擴展思考、預設開啟思考、停用思考時的 effort 上限、移除取樣參數、預設省略思考顯示、更新的分詞方式）
• 重大變更： 移除助手訊息預填（會回傳 400 錯誤）；請改用結構化輸出或 output_config.format
• 在 Opus 4.7 上為重大變更： 將 thinking: {type: "enabled", budget_tokens: N} 替換為 thinking: {type: "adaptive"} 並搭配 effort 參數（在 Opus 4.7 上會回傳 400）
• 確認工具呼叫的 JSON 解析使用標準 JSON 解析器
• 移除 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 或更早版本遷移：移除 temperature、top_p 和 top_k（非預設值在 Opus 4.7 上會回傳 400）
• 若從 Claude 4.1 或更早版本遷移：更新工具版本（text_editor_20250728、code_execution_20260521）
• 若從 Claude 4.1 或更早版本遷移：處理 refusal 停止原因
• 若從 Claude 4.1 或更早版本遷移：處理 model_context_window_exceeded 停止原因
• 若從 Claude 4.1 或更早版本遷移：確認工具字串參數對結尾換行符的處理
• 若從 Claude 4.1 或更早版本遷移：移除舊版 beta 標頭（token-efficient-tools-2025-02-19、output-128k-2025-02-19）
• 依照提示最佳實務檢視並更新提示
• 在部署至正式環境前，先於開發環境中測試

從 Claude Sonnet 5 遷移至 Claude Opus 5

Claude Opus 5 與 Claude Sonnet 5 共用相同的 API 介面：兩者皆預設開啟 adaptive thinking（自適應思考），兩者在 Claude API 與 Claude Code 上皆將 effort 參數預設為 high，兩者皆預設提供 1M token 的上下文視窗以及 128k 最大輸出 token，且兩者皆不支援 Priority Tier。手動擴展思考與非預設取樣參數在兩個模型上皆會回傳 400 錯誤，助手預填亦然。

更新您的模型名稱

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

變更內容

1. 定價： Claude Opus 5 的定價為每百萬輸入 token 5 美元、每百萬輸出 token 25 美元。Claude Sonnet 5 的定價為每百萬輸入／輸出 token 2／10 美元。完整定價請參閱 Claude 定價。

2. 停用思考的上限為 high effort： 在 Claude Sonnet 5 上，thinking: {type: "disabled"} 在任何 effort 等級皆可接受。在 Claude Opus 5 上，僅在 effort 等級為 high 或以下時才可接受；將 thinking: {type: "disabled"} 與 effort xhigh 或 max 結合的請求會回傳 400 錯誤，且會在每個請求上強制執行。請在遷移前稽核停用思考的請求。

3. 對話中途的系統訊息： Claude Opus 5 接受在 messages 陣列中緊接於使用者回合之後的 role: "system" 訊息（須遵守放置規則）。此功能在 Claude Sonnet 5 上不可用。若您維護了會重建完整訊息歷史以更新指令的程式碼路徑，您可以將其簡化，並保留先前回合的提示快取命中。

4. Web fetch 不可用： web fetch 工具在 Claude Sonnet 5 上可用，但在 Claude Opus 5 上不可用。

遷移檢查清單

• 將模型名稱從 claude-sonnet-5 更新為 claude-opus-5。
• 稽核停用思考的請求：thinking: {type: "disabled"} 搭配 effort xhigh 或 max 在 Claude Opus 5 上會回傳 400 錯誤。請重新啟用思考，或將 effort 降至 high 或以下。
• 若您使用 web fetch，請規劃替代方案：它在 Claude Opus 5 上不可用。
• 針對 Claude Opus 5 重新執行 token 計數，而非重複使用針對 Claude Sonnet 5 測得的計數，並在您自己的工作負載上重新建立成本與延遲的基準；每 token 的定價有所不同。