---
title: Claude Opus 5.5 遷移指南
url: https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide
description: 透過本遷移指南，從較早的 Opus 模型或 Claude Sonnet 5 切換至 Claude Opus 5.5。啟用 Claude Opus 5.5 的指引包括會傳回錯誤的請求設定、每個回應中的思考區塊，以及針對每個起始模型的檢查清單。
---
本指南涵蓋遷移 [Messages API](https://platform.claude.com/docs/zh-TW/build-with-claude/working-with-messages) 程式碼的相關內容。如果您使用 [Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)，除了更新模型名稱之外，不需要進行任何其他變更。
**使用 Claude API skill 自動化您的遷移。** 在 Claude Code 中，執行 `/claude-api migrate` 以呼叫內建的 [Claude API skill](https://platform.claude.com/docs/zh-TW/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)。它適用於以任何目前的 Claude 模型作為目標：
讓 Claude Code 為您遷移程式碼
```text
/claude-api migrate 將此專案遷移至 claude-opus-5-5
```
此 skill 會在您的整個程式碼庫中套用模型 ID 替換，並視需要處理破壞性參數變更、prefill（預填）替換，以及針對目標模型的 effort（努力程度）校準，然後產生一份需要手動驗證的項目清單。在編輯任何檔案之前，它會請您確認遷移範圍（整個工作目錄、某個子目錄，或特定的檔案清單）。此 skill 也會偵測 Amazon Bedrock 與 Claude Platform on AWS 用戶端，並針對這些平台調整模型 ID 格式與功能變更。
本頁列出從 [Claude Opus 5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)、[Claude Opus 4.8](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8)、[Claude Opus 4.7](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-47)、[Claude Opus 4.6 及更早的 Opus 模型](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-46)或 [Claude Sonnet 5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-sonnet-5) 遷移至 Claude Opus 5.5 所需的程式碼變更。所有讀者都需要閱讀[每個 Claude Opus 5.5 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)和[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)。接著前往您目前模型對應的章節：該章節的第一句會列出其他適用於您的章節。[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migration-checklist)依起始模型列出所有變更。
Claude Opus 5.5 的費用低於 Claude Opus 5（每百萬輸入／輸出 token 為 $4 / $20 美元，相較之下 Claude Opus 5 為 $5 / $25；請參閱 [Claude 定價](https://platform.claude.com/docs/zh-TW/about-claude/pricing)）。關於功能支援，請參閱 [Claude Opus 5.5 的新功能](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#feature-support)。關於行為差異和模型專屬的提示模式，請參閱[為 Claude Opus 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-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；請參閱[可用性](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#availability)。
* **思考：** 不傳送 `thinking` 欄位，或傳送 `thinking: {"type": "adaptive"}`，兩者等效：「[adaptive thinking](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)」（自適應思考）始終開啟。`thinking: {"type": "disabled"}` 和手動思考預算（`thinking: {"type": "enabled", "budget_tokens": N}`）會被拒絕。請參閱[思考設定的變更前後對照](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-cant-be-disabled)。
* **Effort：** 使用 [effort 參數](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)控制思考深度，這是唯一能控制思考深度的請求參數。支援全部五個等級（`low`、`medium`、`high`、`xhigh`、`max`），預設為 `medium`。請參閱 [Claude Opus 5.5 的建議 effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5)。
* **工具選擇：** 使用 `tool_choice` `{"type": "auto"}`（預設）或 `{"type": "none"}`。以 `{"type": "any"}` 或 `{"type": "tool", "name": "..."}` 強制工具呼叫會被拒絕。請參閱[工具選擇的變更前後對照](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#forced-tool-use)。
* **取樣參數：** 省略 `temperature`、`top_p` 和 `top_k`，或將其保留為預設值：任何其他值都會被拒絕。請使用提示來引導模型的行為。
* **預填：** 不要以預填的助理回合結束 `messages`：這會被拒絕。請改用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)或系統提示指示。在 Amazon Bedrock 上，Claude Opus 5.5 無法使用結構化輸出，因此請在該平台使用系統提示指示。
* **電腦使用：** 在 Claude API 和 Google Cloud 上，請將「computer use」（電腦使用）宣告為 `computer_toolset_20260801` 工具集；較早的 `computer_20251124` 工具在這些平台上會被拒絕。請參閱[電腦使用的重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#computer-use-toolset)。
* **上下文視窗：** 不需要上下文視窗 beta 標頭。[1M token 上下文視窗](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows)是預設值，為舊模型傳送的標頭不會產生任何效果。
以下請求滿足清單中的每一項：已設定 effort，且沒有 `thinking` 欄位。會列印文字的 SDK 分頁依區塊類型選取文字，因為 `thinking` 區塊會先出現。
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"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"
}
}'
```
```bash CLI
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--output-config '{effort: medium}' \
--message '{role: user, content: "Analyze the trade-offs between microservices and monolithic architectures"}'
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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"
}
});
const textBlock = response.content.find(
(block): block is Anthropic.TextBlock => block.type === "text"
);
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
Content = "Analyze the trade-offs between microservices and monolithic architectures"
}
],
OutputConfig = new OutputConfig
{
Effort = Effort.Medium
}
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the trade-offs between microservices and monolithic architectures")),
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortMedium,
},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
import com.anthropic.models.messages.OutputConfig;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Analyze the trade-offs between microservices and monolithic architectures")
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.MEDIUM)
.build())
.build();
Message response = client.messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
],
model: 'claude-opus-5-5',
outputConfig: ['effort' => 'medium'],
);
foreach ($message->content as $block) {
if ($block->type === 'text') {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
message = 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"
}
)
message.content.each do |block|
puts block.text if block.type == :text
end
```
## 處理每個回應中的思考
每個 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 上，每個請求都會以[自適應思考](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)執行。`max_tokens` 仍是總輸出（思考加上回應文字）的硬性上限，因此請針對原本不思考的工作負載重新檢視此值。即使思考文字未傳回給您，思考 token 仍會以輸出 token 計費，因此這類工作負載每個請求可能產生更多輸出 token。請參閱[成本控制](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost#cost-control)。若要減少花在思考上的 token，請降低 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 等級。如果您以 `xhigh` 或 `max` effort 執行，請設定較大的 `max_tokens`，讓模型有空間思考和行動；從 64k token 開始，再依需求調整。如果您的提示是針對不思考的情況調校的，請參閱[為停用思考而撰寫的提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled)。
2. **回應以思考區塊開頭：** 回應可能在第一個 `text` 區塊之前，以一個或多個 `thinking` 區塊開頭。依位置讀取回覆的程式碼，例如 `content[0].text`，或將第一個 `content_block_start` 事件視為文字的串流處理常式，在這些回應上會出錯。請改為依 `type` 欄位選取內容區塊：從 `type` 為 `"text"` 的區塊讀取 `text`，並在處理串流事件時依區塊類型進行分支。
3. **在工具使用迴圈中原封不動地傳回思考區塊：** 如果您執行工具使用迴圈，在傳回工具結果時，請將每個助理回應中的 `thinking` 區塊完整且未經修改地傳回 API，包括 `thinking` 欄位為空的區塊。請按收到的原樣回傳助理訊息，而不是依類型篩選其內容區塊或重新建構它：API 會以 400 錯誤拒絕經過編輯、重新排序或部分遺漏的思考區塊。請參閱[保留思考區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#preserving-thinking-blocks)。
4. **思考文字預設會被省略：** `thinking.display` 預設為 `"omitted"`，因此 `thinking` 區塊送達時，其 `thinking` 欄位為空，並附帶 `signature`。請僅將 `thinking` 欄位視為顯示用文字。若要改為接收可讀的摘要，請將 `thinking.display` 設為 `"summarized"`：
```python Python
thinking = {
"type": "adaptive",
"display": "summarized",
}
```
```typescript TypeScript
const thinking = {
type: "adaptive",
display: "summarized"
};
```
```csharp C#
var thinking = new ThinkingConfigAdaptive { Display = Display.Summarized };
```
```go Go
thinking := anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{
Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized,
},
}
```
```java Java
ThinkingConfigAdaptive thinking = ThinkingConfigAdaptive.builder()
.display(ThinkingConfigAdaptive.Display.SUMMARIZED)
.build();
```
```php PHP
$thinking = ['type' => 'adaptive', 'display' => 'summarized'];
```
```ruby Ruby
thinking = {
type: "adaptive",
display: "summarized"
}
```
如果您的產品會將推理過程串流給使用者，預設值會表現為輸出開始前的長時間停頓；請設定 `display: "summarized"` 以在思考期間恢復可見的進度。請參閱[控制思考顯示](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#controlling-thinking-display)。
5. **工具呼叫之間的文字會以思考區塊傳回：** 模型在工具呼叫之間撰寫的簡短說明會以 `thinking` 區塊傳回，在預設顯示設定下這些區塊為空。請參閱[工具呼叫之間的文字會在思考區塊中傳回](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#text-between-tool-calls)。
## 依起始模型分類的遷移檢查清單
請依序往下處理各群組，並在列出您目前模型的群組之後停止：到該處為止的每一項都適用於您。如果您使用的是 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`；其他平台請查看電腦使用工具的[相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#compatibility)章節。
* 如果路由器或備援機制可能將對話從 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`，請遵循[保留思考](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking)。
* 處理 `stop_reason: "refusal"` 並設定備援。
* 在您選擇的 effort 等級下重新建立成本和延遲的基準。
* 如果您的程式碼曾停用思考，請重新檢視 `max_tokens`，它涵蓋思考加上回應文字；在 `xhigh` 或 `max` effort 下，請從 64k 開始。請參閱[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)。
### Claude Opus 4.8 或更早版本
* 檢視原本沒有 `thinking` 欄位的工作負載：在 Claude Opus 5.5 上，它們會以思考模式執行，且思考無法停用。請重新檢視 `max_tokens`，它仍是總輸出（思考加上回應文字）的硬性上限，並在希望減少思考的地方降低 `effort`。思考 token 會以輸出 token 計費，因此這些工作負載每個請求可能產生更多輸出 token。
* 確認任何解析 `thinking` 欄位的程式碼僅將其視為顯示用文字。設定 `display: "summarized"` 以接收可讀的摘要。
* 檢視接近快取最低門檻的提示：512 個 token 以上的提示即可建立快取項目。
* 如果您的組織有 [Priority Tier](https://platform.claude.com/docs/zh-TW/api/service-tiers#supported-models) 承諾，請另行規劃容量：Claude Opus 5.5 不支援 Priority Tier。
* 如果您以 `xhigh` 或 `max` effort 執行，請將 `max_tokens` 提高到至少 64k 作為起點。
* 對於代理式工作負載，請考慮使用[任務預算](https://platform.claude.com/docs/zh-TW/build-with-claude/task-budgets)（beta）和對話中途工具變更（beta）。
### Claude Opus 4.7 或更早版本
* 在您自己的評估上重新進行 [effort](https://platform.claude.com/docs/zh-TW/build-with-claude/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 參數](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)，或完全移除 `thinking` 欄位；自適應思考始終開啟。
* 如果您的 UI 會顯示思考內容，請明確選擇啟用思考摘要。
* 在更新後的分詞方式下，重新對端到端成本和延遲進行基準測試。
* 重新調整 `max_tokens` 以因應更新後的分詞方式，包括壓縮觸發條件。
* 重新測試任何用戶端的 token 計數估算。
* 如果您的應用程式會傳送影像，請針對[高解析度影像支援](https://platform.claude.com/docs/zh-TW/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)重新編列預算（每張全解析度影像的影像 token 最多約多出 3 倍）。如果您不需要額外的保真度，請在傳送前進行降採樣。
* 如果您會使用模型回傳的指向或邊界框座標，請移除任何縮放係數轉換；在 Claude Opus 4.7 及更新的模型上，座標與實際影像像素為 1:1 對應。
* 檢視從 Claude Opus 4.7 開始的[行為變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#behavior-changes)。
* 如果您的產品從事正當的安全工作，請申請 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet)，以放寬對網路安全內容的限制。
### Claude Opus 4.5 或更早版本
* 移除任何助理訊息預填；Claude Opus 4.6 已會拒絕這些預填。
* 確認工具呼叫的 JSON 解析使用標準 JSON 解析器。
* 從 `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) 改為 `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant 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`）。
* 依照[提示最佳實踐](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices)檢視並更新提示。
### 僅限 Claude Sonnet 5
* 如果您會重建對話歷史以更新指示，請考慮改用對話中途的系統訊息，以保留提示快取命中。
* 檢視接近快取最低門檻的提示：512 個 token 以上的提示即可建立快取項目。
## 從 Claude Opus 5 遷移至 Claude Opus 5.5
請先完成[每個 Claude Opus 5.5 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)和[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)。所有起始模型都需要本節中的變更。這些變更是 Claude Opus 5.5 會拒絕的請求設定，以及隨之而來的回應變更。本節的檢查清單是[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migration-checklist)的第一個群組。
### 更新您的模型名稱
```python
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；請參閱[可用性](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#availability)。
### 重大變更
每項變更的說明請見 [Claude Opus 5.5 的新功能](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#breaking-changes)；本節提供每項變更所需的程式碼修改。
#### 思考無法停用
`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](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)（投入程度）等級；若您先前停用思考是為了節省 token，請改用較低的等級。回應接著會以 `thinking` 區塊開頭，因此請依 `type` 選取內容區塊，並將 `thinking` 區塊連同工具結果原封不動地傳回。請參閱[思考無法停用](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#thinking-cant-be-disabled)。
變更前。Claude Opus 5 接受此請求，而 Claude Opus 5.5 會以 400 錯誤拒絕：
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 16000,
"thinking": {"type": "disabled"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
ant messages create \
--model claude-opus-5 \
--max-tokens 16000 \
--thinking '{type: disabled}' \
--message '{role: user, content: "..."}'
```
```python Python
client.messages.create(
model="claude-opus-5",
max_tokens=16000,
thinking={"type": "disabled"},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 16000,
thinking: { type: "disabled" },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 16000,
Thinking = new ThinkingConfigDisabled(),
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfDisabled: &anthropic.ThinkingConfigDisabledParam{},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(16000L)
.thinking(ThinkingConfigDisabled.builder().build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 16000,
thinking: ThinkingConfigDisabled::with(),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 16000,
thinking: Anthropic::ThinkingConfigDisabled.new,
messages: [{ role: "user", content: "..." }]
)
```
變更後：
```bash cURL
# thinking 一律啟用；以 effort 進行控制
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"output_config": {"effort": "low"},
"messages": [{"role": "user", "content": "..."}]
}'
```
```bash CLI
# thinking 一律啟用；以 effort 進行控制
ant messages create \
--model claude-opus-5-5 \
--max-tokens 16000 \
--output-config '{effort: low}' \
--message '{role: user, content: "..."}'
```
```python Python
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": "..."}],
)
```
```typescript TypeScript
await 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: "..." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
OutputConfig = new() { Effort = Effort.Low }, // thinking is always on; effort is the control
Messages = [new() { Role = Role.User, Content = "..." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow, // thinking is always on; effort is the control
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
// thinking 一律開啟；由 effort 控制
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessage("...")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 16000,
// thinking 一律啟用；以 effort 控制
outputConfig: OutputConfig::with(effort: Effort::LOW),
messages: [['role' => 'user', 'content' => '...']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 16000,
# thinking 一律開啟；以 effort 進行控制
output_config: { effort: Anthropic::OutputConfig::Effort::LOW },
messages: [{ role: "user", content: "..." }]
)
```
#### 不支援強制工具使用
`tool_choice` 類型 `any` 和 `tool` 會傳回 400 錯誤（`tool_choice: type "tool" and "any" are not supported for this model.`），包括在 token 計數端點上。請使用 `auto` 搭配[嚴格工具使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/strict-tool-use)或[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)，並在提示中說明何時適用該工具。嚴格工具使用接受 JSON Schema 的子集，因此在加入 `strict: true` 之前，請檢查每個工具的 `input_schema`。結構描述中的每個物件都必須設定 `additionalProperties: false`；請參閱 [JSON Schema 限制](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs#json-schema-limitations)。在 Amazon Bedrock 上，Claude Opus 5.5 無法使用結構化輸出（包括嚴格工具使用）。在該平台上，請傳送不含 `strict` 的 `auto`，在提示中說明何時適用該工具，並在您的程式碼中驗證工具輸入。請參閱[不支援強制工具使用](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#forced-tool-use-is-not-supported)。
變更前。Claude Opus 5 接受此請求，而 Claude Opus 5.5 會以 400 錯誤拒絕：
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
}
}],
"tool_choice": {"type": "tool", "name": "get_weather"},
"messages": [{"role": "user", "content": "What'\''s the weather in Paris?"}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
tool_choice:
type: tool
name: get_weather
messages:
- role: user
content: What's the weather in Paris?
YAML
```
```python Python
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?"}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5",
max_tokens: 1024,
tools,
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather in Paris?" }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [.. tools],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [new() { Role = Role.User, Content = "What's the weather in Paris?" }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: tools,
ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.tools(tools)
.toolChoice(ToolChoiceTool.of("get_weather"))
.addUserMessage("What's the weather in Paris?")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 1024,
tools: $tools,
toolChoice: ToolChoiceTool::with(name: 'get_weather'),
messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 1024,
tools: tools,
tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
messages: [{ role: "user", content: "What's the weather in Paris?" }]
)
```
變更後：
```bash cURL
# 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"],
"additionalProperties": false
},
"strict": true
}],
"tool_choice": {"type": "auto"},
"messages": [{
"role": "user",
"content": "What'\''s the weather in Paris? Use the get_weather tool."
}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
tools:
- name: get_weather
description: Get the current weather in a given location
input_schema:
type: object
properties:
location:
type: string
description: The city and state, e.g. San Francisco, CA
required: [location]
additionalProperties: false
# 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
strict: true
tool_choice:
type: auto
messages:
- role: user
content: What's the weather in Paris? Use the get_weather tool.
YAML
```
```python Python
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.",
}
],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
// strict tool use（嚴格工具使用）：每次呼叫皆符合該工具的 input_schema
tools: tools.map((tool) => ({ ...tool, strict: true })),
tool_choice: { type: "auto" },
messages: [
{
role: "user",
content: "What's the weather in Paris? Use the get_weather tool."
}
]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
// 嚴格的 tool use（工具使用）：每次呼叫皆符合該工具的 input_schema
Tools = [.. tools.Select(tool => tool with { Strict = true })],
ToolChoice = new ToolChoiceAuto(),
Messages =
[
new()
{
Role = Role.User,
Content = "What's the weather in Paris? Use the get_weather tool.",
},
],
});
```
```go Go
// strict tool use（嚴格工具使用）：每次呼叫都符合該工具的 input_schema
var strictTools []anthropic.ToolUnionParam
for _, tool := range tools {
strictTool := *tool.OfTool
strictTool.Strict = anthropic.Bool(true)
strictTools = append(strictTools, anthropic.ToolUnionParam{OfTool: &strictTool})
}
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: strictTools,
ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
// strict tool use（嚴格工具使用）：每次呼叫都符合該工具的 input_schema
.tools(tools.stream()
.map(tool -> tool.tool()
.map(customTool -> customTool.toBuilder().strict(true).build())
.map(ToolUnion::ofTool)
.orElse(tool))
.toList())
.toolChoice(ToolChoiceAuto.builder().build())
.addUserMessage("What's the weather in Paris? Use the get_weather tool.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
// 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
tools: array_map(fn (Tool $tool) => $tool->withStrict(true), $tools),
toolChoice: ToolChoiceAuto::with(),
messages: [
[
'role' => 'user',
'content' => "What's the weather in Paris? Use the get_weather tool.",
],
],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
# 嚴格工具使用：每次呼叫皆符合該工具的 input_schema
tools: tools.map { |tool| tool.merge(strict: true) },
tool_choice: Anthropic::ToolChoiceAuto.new,
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 錯誤。僅附加的整合不需要修改程式碼。請參閱[思考區塊與模型及對話綁定](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them)與[保留思考](https://platform.claude.com/docs/zh-TW/build-with-claude/preserved-thinking)。
#### 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` 遷移](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)。在 Amazon Bedrock 上，較早的 `computer_20251124` 工具在 Claude Opus 5.5 上仍可如同在 Claude Opus 5 上一樣運作，因此無需變更；其他平台請參閱電腦使用工具的[相容性](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool#compatibility)章節。請參閱[Claude API 與 Google Cloud 不支援 `computer_20251124` 電腦使用工具](https://platform.claude.com/docs/zh-TW/models/opus-5-5/whats-new-opus-5-5#computer-20251124-is-not-supported)。
變更前。Claude Opus 5 接受此請求，而在 Claude API 和 Google Cloud 上，Claude Opus 5.5 會以 400 錯誤拒絕：
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: computer-use-2025-11-24" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 4096,
"tools": [{
"type": "computer_20251124",
"name": "computer",
"display_width_px": 1024,
"display_height_px": 768
}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
ant beta:messages create \
--model claude-opus-5 \
--max-tokens 4096 \
--beta computer-use-2025-11-24 \
--tool '{
type: computer_20251124,
name: computer,
display_width_px: 1024,
display_height_px: 768
}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
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."}],
)
```
```typescript TypeScript
await 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." }]
});
```
```csharp C#
await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 4096,
Betas = [AnthropicBeta.ComputerUse2025_11_24],
Tools =
[
new BetaToolComputerUse20251124
{
DisplayWidthPx = 1024,
DisplayHeightPx = 768,
},
],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaComputerUse2025_11_24},
Tools: []anthropic.BetaToolUnionParam{
{OfComputerUseTool20251124: &anthropic.BetaToolComputerUse20251124Param{
DisplayWidthPx: 1024,
DisplayHeightPx: 768,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(4096L)
.addBeta(AnthropicBeta.COMPUTER_USE_2025_11_24)
.addTool(BetaToolComputerUse20251124.builder()
.displayWidthPx(1024L)
.displayHeightPx(768L)
.build())
.addUserMessage("Open the display settings.")
.build();
client.beta().messages().create(params);
```
```php PHP
$client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
maxTokens: 4096,
betas: [AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
BetaToolComputerUse20251124::with(
displayWidthPx: 1024,
displayHeightPx: 768,
),
],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPUTER_USE_2025_11_24],
tools: [
Anthropic::Beta::BetaToolComputerUse20251124.new(
name: :computer,
display_width_px: 1024,
display_height_px: 768
)
],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
變更後：
```bash cURL
# 不需要 beta 標頭；toolset 項目不接受名稱或顯示尺寸
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"tools": [{"type": "computer_toolset_20260801"}],
"messages": [{"role": "user", "content": "Open the display settings."}]
}'
```
```bash CLI
# 不需要 beta 標頭；toolset 項目不接受名稱或顯示尺寸
ant messages create \
--model claude-opus-5-5 \
--max-tokens 4096 \
--tool '{type: computer_toolset_20260801}' \
--message '{role: user, content: "Open the display settings."}'
```
```python Python
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."}],
)
```
```typescript TypeScript
await 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." }]
});
```
```csharp C#
await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
// 不需 beta 標頭；toolset 項目不接受名稱或顯示尺寸
Tools = [new ComputerToolset20260801()],
Messages = [new() { Role = Role.User, Content = "Open the display settings." }],
});
```
```go Go
client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
// 不需 beta 標頭；toolset 項目不接受名稱或顯示尺寸
Tools: []anthropic.ToolUnionParam{
{OfComputerToolset20260801: &anthropic.ComputerToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open the display settings.")),
},
})
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
// 不需 beta 標頭；toolset 項目不接受名稱或顯示尺寸
.addTool(ComputerToolset20260801.builder().build())
.addUserMessage("Open the display settings.")
.build();
client.messages().create(params);
```
```php PHP
$client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 4096,
// 不需 beta 標頭；toolset 項目不接受名稱或顯示尺寸
tools: [ComputerToolset20260801::with()],
messages: [['role' => 'user', 'content' => 'Open the display settings.']],
);
```
```ruby Ruby
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 4096,
# 不需要 beta 標頭；toolset 項目不接受名稱或顯示尺寸
tools: [Anthropic::ComputerToolset20260801.new],
messages: [{ role: "user", content: "Open the display settings." }]
)
```
### 工具呼叫之間的文字會在思考區塊中傳回
在 Claude Opus 5 上，模型在工具呼叫之間撰寫的文字會以 `text` 區塊傳回。在 Claude Opus 5.5 上，與 Claude Fable 5.1 相同，這些敘述會以[進度更新 `thinking` 區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#progress-updates)傳回，每次工具呼叫之前最多一個。在預設的 `thinking.display` 值 `"omitted"` 下，其 `thinking` 欄位為空。雖然不會有請求失敗，但若應用程式會將這些文字以「streaming」（串流）方式作為進度更新傳送給使用者，則在工具呼叫之間將不再有任何輸出。若要恢復這些更新，請從 `thinking` 區塊讀取它們，並設定會傳回其文字的 `display` 值：`"updates"`（beta，需使用 `thinking-display-updates-2026-08-18` 標頭）會傳回進度更新，同時保持推理內容隱藏；`"summarized"` 則會將兩者混合一併傳回。接著，請將每個非空的 `thinking` 區塊呈現在其後方的 `tool_use` 區塊之前，並將這些區塊連同助理回合的其餘內容原封不動地傳回。請參閱[面向使用者的進度更新](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)。
### 安全分類器與備援
Claude Opus 5.5 可能傳回帶有 `stop_details` 類別的 `stop_reason: "refusal"`。其分類器涵蓋的類別比 Claude Opus 5 更廣，因此除了 `"cyber"` 和 `"reasoning_extraction"` 之外，請預期會出現 `"bio"` 等 `stop_details.category` 值；請參閱[拒絕類別表](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#refusal-response)。請處理拒絕並設定[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)或您自己的重試機制（伺服器端備援不會重試以 `"reasoning_extraction"` 拒絕的請求；該拒絕會傳回給您）；請參閱[拒絕與備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback)和[安全防護拒絕](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals)。
### 建議變更
1. **重新進行 effort 掃描測試。** Effort 是 Claude Opus 5.5 上唯一的思考控制項，其預設值為 `medium`，而 Claude Opus 5 的預設值為 `high`，因此省略 `effort` 的請求現在會以 `medium` 執行。在品質維持不變的情況下調低等級，並針對要求最高的工作調高等級。請參閱 [Effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)。
2. **重新評估特定模型的提示指示。** 針對 Claude Opus 5 行為調整的指示可能已不再需要；請參閱[為 Claude Opus 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)。如果您先前在停用思考的情況下執行，也請參閱[為停用思考而撰寫的提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled)。
3. 在切換正式環境流量之前，**先在開發環境中測試**。
## 從 Claude Opus 4.8 遷移至 Claude Opus 5.5
請先完成[每個 Claude Opus 5.5 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)、[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)和[從 Claude Opus 5 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-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 之間的變更。如需檢查清單，請參閱[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migration-checklist)的前兩個群組。
### 變更內容
1. **原本省略思考的請求會執行思考：** 在 Claude Opus 4.8 上，除非您要求，否則思考是關閉的。在 Claude Opus 5.5 上，沒有 `thinking` 欄位的請求會以思考模式執行，因此[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)中的每一項對該程式碼而言都是需要進行的變更。如果您的程式碼從未傳送 `thinking` 欄位，則在[思考設定的變更前後對照](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-cant-be-disabled)中沒有需要移除的內容。
2. **較低的提示快取最低門檻：** Claude Opus 5.5 上可快取提示的最小長度為 512 個 token，低於 Claude Opus 4.8 上的 1,024 個 token。在 Claude Opus 4.8 上因太短而無法快取的提示，現在可以建立快取項目，且不需要修改程式碼。各模型的最低門檻請參閱[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-limitations)。
3. **不支援 Priority Tier：** Claude Opus 5.5 不支援 [Priority Tier](https://platform.claude.com/docs/zh-TW/api/service-tiers#supported-models)，而 Claude Opus 4.8 仍保有此支援。如果您的組織有 Priority Tier 承諾，請另行規劃容量。
### 建議變更
這些變更並非必要，但能改善您的使用體驗：
1. **考慮使用任務預算（beta）：** 對於代理式工作負載，[任務預算](https://platform.claude.com/docs/zh-TW/build-with-claude/task-budgets)會告訴模型在完整的代理迴圈中有多少 token 可用。此功能需要 `task-budgets-2026-03-13` beta 標頭。
2. **考慮使用對話中途的工具變更（beta）：** 對話中途的工具變更可讓您在對話的回合之間新增或移除工具，而不會使較早回合的[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)命中失效。直接變更 `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 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)、[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)、[從 Claude Opus 5 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)和[從 Claude Opus 4.8 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8)。請將 `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](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-46)。該節補充了從 Claude Opus 4.7 開始生效的重大變更。如需檢查清單，請參閱[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migration-checklist)的前三個群組。
### 變更內容
這些項目都不會在前面章節所列的重大變更之外再新增重大變更；替換模型 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](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)。
2. **1M 上下文視窗為預設值：** Claude Opus 5.5 預設提供完整的 1M token [上下文視窗](https://platform.claude.com/docs/zh-TW/build-with-claude/context-windows)，不需要 beta 標頭。如果您的用戶端為了與舊模型相容而傳送上下文視窗 beta 標頭，請將其移除。
3. **對話中途的系統訊息：** 在 Claude API、Amazon Bedrock 和 Google Cloud 上，Claude Opus 5.5 接受在 `messages` 陣列中緊接在使用者回合之後的 `role: "system"` 訊息（須遵守[放置規則](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages#limitations)）。對於從一開始就適用的指示，請使用頂層的 `system` 欄位。Claude Opus 4.7 會以 400 錯誤拒絕 `messages` 中的 `role: "system"`。如果您維護的程式碼路徑會重建完整的訊息歷史以更新指示，您可以簡化這些路徑，並保留較早回合的[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)命中。
4. **拒絕停止詳細資訊：** 當模型拒絕請求時，Claude Opus 5.5 會在 `refusal` 停止原因之外，傳回一個指出拒絕類別的 `stop_details` 物件。Claude Opus 4.7 也會傳回相同的物件，因此只有在您的停止原因處理尚未讀取它時，這一點才有影響。不需要 beta 標頭，也無法選擇退出。如果您的停止原因處理尚未讀取它，請參閱[處理停止原因](https://platform.claude.com/docs/zh-TW/build-with-claude/handling-stop-reasons)。Claude Opus 5.5 會在更多類別中拒絕請求；請參閱[安全分類器與備援](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#safety-classifiers-and-fallback)。
5. **快速模式：** Claude Opus 5.5 在 Claude API 上支援[快速模式](https://platform.claude.com/docs/zh-TW/build-with-claude/fast-mode)。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` 工具集形式提供的[電腦使用](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/computer-use-tool)，以及用於網頁內任務的[瀏覽器使用工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/browser-use-tool)。Claude Opus 4.7 兩者皆不支援。在這些平台上，Claude Opus 5.5 不接受較早的 `computer_20251124` 工具；請參閱[電腦使用的重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#computer-use-toolset)。
## 從 Claude Opus 4.6 及更早的 Opus 模型遷移至 Claude Opus 5.5
請先依頁面順序完成前面的每一節。這些章節是[每個 Claude Opus 5.5 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)、[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)，以及 [Claude Opus 5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-5)、[Claude Opus 4.8](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8) 和 [Claude Opus 4.7](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-47) 的章節。這些章節的內容可直接套用於 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 或更早版本](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-45)和 [Claude 4.1 或更早版本](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier)的讀者參考。如需檢查清單，請參閱[遷移檢查清單](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migration-checklist)中直到列出您模型的群組為止的內容。
### 重大變更
1. **「Extended thinking」（擴展思考）已移除：** `thinking: {"type": "enabled", "budget_tokens": N}` 在 Claude Opus 4.7 及更新的模型上不再受支援，並會傳回 400 錯誤。請改用[「adaptive thinking」（自適應思考）](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)（`thinking: {"type": "adaptive"}`），並使用 [effort 參數](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)來控制思考深度。在 Claude Opus 5.5 上，自適應思考始終開啟：`thinking: {"type": "adaptive"}` 是有效的，且等同於完全省略 `thinking` 欄位。
變更前（Claude Opus 4.6）：
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 16000
thinking:
type: enabled
budget_tokens: 10000
messages:
- role: user
content: "..."
YAML
```
```python Python
client.messages.create(
model="claude-opus-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
```
```typescript TypeScript
await client.messages.create({
model: "claude-opus-4-6",
max_tokens: 16000,
thinking: { type: "enabled", budget_tokens: 10000 },
messages: [{ role: "user", content: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus4_6,
MaxTokens = 16000,
Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_6,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamOfEnabled(10000),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_6)
.maxTokens(16000L)
.enabledThinking(10000L)
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-4-6',
thinking: ['type' => 'enabled', 'budget_tokens' => 10000],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = 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` 這幾行有所不同：
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 16000,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "..."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 16000
thinking:
type: adaptive
output_config:
effort: high
messages:
- role: user
content: "..."
YAML
```
```python 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": "..."}],
)
```
```typescript TypeScript
await 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: "..." }]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig { Effort = Effort.High }, // or Max, Xhigh, Medium, Low
Messages = [new() { Role = Role.User, Content = "..." }]
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortHigh, // or Max, Xhigh, Medium, Low
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("...")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.HIGH) // or MAX, XHIGH, MEDIUM, LOW
.build())
.addUserMessage("...")
.build();
Message response = client.messages().create(params);
IO.println(response);
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 16000,
messages: [['role' => 'user', 'content' => '...']],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'high'], // or 'max', 'xhigh', 'medium', 'low'
);
```
```ruby Ruby
client = Anthropic::Client.new
message = 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 參數](https://platform.claude.com/docs/zh-TW/build-with-claude/effort)加以引導，effort 參數取代了思考預算，成為控制模型推理程度的方式。請在您自己的評估上執行 effort 掃描，而不是換算 `budget_tokens` 值。[effort 等級表](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#effort-levels)說明了各等級的使用時機，而 [Claude Opus 5.5 的建議 effort 等級](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#recommended-effort-levels-for-claude-opus-5-5)則涵蓋此模型。
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 的預設行為是傳回摘要後的思考文字。若要恢復此行為，請參閱[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)的第 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`](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting) 為 Claude Opus 5.5 傳回的 token 數量與 Claude Opus 4.6 不同。token 效率可能因工作負載型態而異。
請更新您的 `max_tokens` 參數以預留額外空間（包括壓縮觸發條件），並重新測試任何在用戶端估算 token 或假設固定 token 與字元比例的程式碼路徑。請使用 [Token 計數端點](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)進行驗證。提示介入、[`task_budget`](https://platform.claude.com/docs/zh-TW/build-with-claude/task-budgets) 與 [`effort`](https://platform.claude.com/docs/zh-TW/build-with-claude/effort) 有助於控制成本；這些控制方式可能會犧牲部分模型智慧。
5. **預填已移除（在 Claude Opus 4.6 上已生效）：** 在 Claude Opus 4.6 及更新的 Opus 模型（包括 Claude Opus 5.5）上，預填助理訊息會傳回 400 錯誤，因此只有當您從 Claude Opus 4.5 或更早版本遷移時，這才是一項變更。請改用[結構化輸出](https://platform.claude.com/docs/zh-TW/build-with-claude/structured-outputs)或系統提示指示。在 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` 下這些區塊為空。若要接收這些更新，請參閱[工具呼叫之間的文字會在思考區塊中傳回](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#text-between-tool-calls)。若要調整其長度與內容，請參閱[面向使用者的進度更新](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates)。
2. **即時網路安全防護措施：** 這是 Claude Opus 4.7 新增的功能，涉及禁止或高風險主題的請求可能會遭到拒絕。對於滲透測試、漏洞研究或紅隊演練等正當的安全工作，請申請 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude-opus-and-sonnet) 以要求放寬限制。申請途徑取決於您存取 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 上的高解析度影像支援](https://platform.claude.com/docs/zh-TW/build-with-claude/vision#high-resolution-image-support-on-claude-opus-4-7)。
關於提示方面的差異，請參閱[為 Claude Opus 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) 與[提示最佳實踐](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices)。
### 從 Claude Opus 4.5 或更早版本遷移
如果您要從 Claude Opus 4.5、Claude Opus 4.1 或更早的模型直接遷移至 Claude Opus 5.5，請從頭閱讀本頁：首先依頁面順序完成所有前面的章節。接著完成本節前面的[從 Claude Opus 4.6 遷移的重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#opus-46-breaking-changes)。然後套用以下累積變更，這些變更是在 Claude Opus 4.5 與 Claude Opus 4.7 之間生效的。如果您使用的是 Claude Opus 4.1 或更早版本，請在本小節之後繼續閱讀[從 Claude 4.1 或更早版本遷移](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier)。
#### 重大變更
1. **移除預填**已涵蓋於[從 Claude Opus 4.6 遷移的重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#opus-46-breaking-changes)中。
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 遷移的重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#opus-46-breaking-changes)的第 1 項。此遷移也會從 `client.beta.messages.create()` (csharp: `client.Beta.Messages.Create()`; go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; php: `$client->beta->messages->create()`; cli: `ant beta:messages create`) 改為 `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant 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 或更早版本遷移](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-45)中的所有內容。該小節以所有前面的章節為起點，因此實際上您是從頭閱讀本頁。然後再套用本小節中的其他變更。
#### 額外的重大變更
1. **移除取樣參數：** 已涵蓋於[取樣參數已移除](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#opus-46-breaking-changes)中。
2. **更新工具版本**
從 Claude 3.x 模型遷移時，這是一項重大變更。
請更新至目前的工具版本。移除任何使用 `undo_edit` 命令的程式碼。
```python Python
# 之前
tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
# 之後
tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]
```
```typescript TypeScript
// 之前
const legacyTools = [{ type: "text_editor_20250124", name: "str_replace_editor" }];
// 之後
const tools = [{ type: "text_editor_20250728", name: "str_replace_based_edit_tool" }];
```
```csharp C#
var parameters = new MessageCreateParams
{
// 之前：{"type": "text_editor_20250124", "name": "str_replace_editor"}
// 之後：
Tools = [new ToolTextEditor20250728()],
// ...
};
```
```go Go
params := anthropic.MessageNewParams{
// 之前：{"type": "text_editor_20250124", "name": "str_replace_editor"}
// 之後：
Tools: []anthropic.ToolUnionParam{
{OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}},
},
// ...
}
```
```java Java
MessageCreateParams params = MessageCreateParams.builder()
// 之前：{"type": "text_editor_20250124", "name": "str_replace_editor"}
// 之後：
.addTool(ToolTextEditor20250728.builder().build())
// ...
.build();
```
```php PHP
$message = $client->messages->create(
// 之前：['type' => 'text_editor_20250124', 'name' => 'str_replace_editor']
// 之後：
tools: [new ToolTextEditor20250728()],
// ...
);
```
```ruby Ruby
# 之前
legacy_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`。詳情請參閱[文字編輯器工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/text-editor-tool)文件。
* **程式碼執行：** 升級至 `code_execution_20260521`。遷移說明請參閱[程式碼執行工具](https://platform.claude.com/docs/zh-TW/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version)文件。
* **電腦使用：** 在 Claude API 與 Google Cloud 上，Claude Opus 5.5 僅接受以 `computer_toolset_20260801` 工具集形式使用電腦使用功能：較早的 `computer_20250124` 與 `computer_20251124` 工具在這些平台上會遭到拒絕。請參閱[電腦使用重大變更](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#computer-use-toolset)。
3. **處理 `refusal` 停止原因**
更新您的應用程式以[處理 `refusal` 停止原因](https://platform.claude.com/docs/zh-TW/test-and-evaluate/strengthen-guardrails/handle-streaming-refusals)：
```python Python
response = client.messages.create(...)
if response.stop_reason == "refusal":
# 適當處理拒絕情況
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "refusal") {
// 適當處理拒絕回應
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Value() == StopReason.Refusal)
{
// 適當處理拒絕情況
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == anthropic.StopReasonRefusal {
// 適當處理拒絕回應
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.REFUSAL)) {
// 適當處理拒絕回應
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'refusal') {
// 適當處理拒絕回應
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :refusal
# 適當處理拒絕回應
end
```
4. **處理 `model_context_window_exceeded` 停止原因**
當生成因達到「context window」（上下文視窗）限制（而非請求的 `max_tokens` 限制）而停止時，Claude 4.5 及更新的模型會傳回 `model_context_window_exceeded` 停止原因。請更新您的應用程式以處理此新的停止原因：
```python Python
response = client.messages.create(...)
if response.stop_reason == "model_context_window_exceeded":
# 適當處理上下文視窗限制
pass
```
```typescript TypeScript
const response = await client.messages.create(/* ... */);
if (response.stop_reason === "model_context_window_exceeded") {
// 適當處理上下文視窗限制
}
```
```csharp C#
var response = await client.Messages.Create(...);
if (response.StopReason?.Raw() == "model_context_window_exceeded")
{
// 適當處理上下文視窗限制
}
```
```go Go
response, _ := client.Messages.New(ctx, params) // your existing request
if response.StopReason == "model_context_window_exceeded" {
// 適當處理上下文視窗限制
}
```
```java Java
Message response = client.messages().create(...);
StopReason reason = response.stopReason().orElse(StopReason.END_TURN);
if (reason.equals(StopReason.of("model_context_window_exceeded"))) {
// 適當處理上下文視窗限制
}
```
```php PHP
$response = $client->messages->create(...);
if ($response->stopReason === 'model_context_window_exceeded') {
// 適當處理上下文視窗限制
}
```
```ruby Ruby
response = client.messages.create(...)
if response.stop_reason == :model_context_window_exceeded
# 適當處理上下文視窗限制
end
```
5. **驗證工具參數處理（結尾換行符）**
Claude 4.5 及更新的模型會保留工具呼叫字串參數中先前會被移除的結尾換行字元。如果您的工具依賴對工具呼叫參數進行精確字串比對，請驗證您的邏輯能正確處理結尾換行字元。
6. **針對行為變更更新您的提示**
Claude 4 及更新的模型具有更簡潔、直接的溝通風格，並需要明確的指示。最佳化指引請參閱[提示最佳實踐](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/claude-prompting-best-practices)。
#### 額外的建議變更
* **移除舊版 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 請求必須滿足的條件](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#request-requirements)、[處理每個回應中的思考](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#thinking-in-every-response)以及[從 Claude Opus 5 遷移至 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/models/opus-5-5/migration-guide#migrating-from-claude-opus-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"` 訊息（須遵守[放置規則](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages#limitations)）。此功能在 Claude Sonnet 5 上無法使用。如果您維護的程式碼路徑會重建完整訊息歷史以更新指示，您可以簡化這些路徑，並保留較早回合的[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)命中。
2. **較低的提示快取最低門檻：** Claude Opus 5.5 上可快取提示的最小長度為 512 個 token，低於 Claude Sonnet 5 上的 1,024 個 token。在 Claude Sonnet 5 上因過短而無法快取的提示現在可以建立快取項目，無需變更任何程式碼。各模型的最低門檻請參閱[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching#cache-limitations)。