Claude Opus 4.7 遷移指南：升級前必查的 7 個 workflow 風險

升級 Claude Opus 4.7 時，最容易踩雷的不是原本 prompt 完全失效，而是舊 workflow 把關鍵控制藏在舊 API 參數、舊 token 估算、或不夠明確的 tool policy 裡。Anthropic 的遷移文件指出，Opus 4.7 延續 Opus 4.6 的主要平台能力，但遷移時仍要處理 thinking configuration、sampling-parameter removal、task budgets 與 tokenization 等變更。

本文以 Anthropic 文件明確描述的 Opus 4.6 → Opus 4.7 遷移為基準。如果你是從更舊的 Claude 模型升級，仍可把這份清單當成回歸測試起點，但應另外比對原模型版本的差異。

先判斷你的 Claude workflow 類型

升級工作量取決於你怎麼用 Claude。手動聊天和文件草稿多半是 prompt 回歸測試；API、RAG、agent、coding 或 vision workflow 則要更仔細地檢查參數、工具策略與成本模型。

使用方式	升級前最該檢查
手動聊天、文件草稿、知識工作	常用 prompt、語氣、輸出格式、引用與工具使用規則
Messages API / SDK	model ID、thinking 設定、sampling 參數、token counting、錯誤處理
Tool use / RAG / web search	何時必須用工具、何時不得猜測、工具失敗時如何 fallback
長任務 agent / coding agent	effort、task budget、token budget、延遲與 regression eval
圖片、截圖、PDF、computer-use workflow	影像解析度、downsample policy、token 成本與視覺辨識品質

1. 先修 breaking change：extended thinking 改 adaptive thinking

第一件事不是改 prompt，而是掃 API 設定。Anthropic 表示，開發者可透過 Claude API 使用 claude-opus-4-7；如果你的應用程式直接指定 model ID，先把這一步納入小流量或 shadow eval。

更關鍵的是 thinking 設定。Anthropic 的 migration guide 明確寫到，Claude Opus 4.7 或之後不再支援舊式 extended thinking 的 budget_tokens 設定，且會回傳 400 error；遷移方向是改用 adaptive thinking。

實務上，先做三件事：

• 搜尋程式碼、SDK wrapper、prompt runner、內部平台設定中的 budget_tokens。
• 移除舊式 extended thinking 設定，改用你所使用 API 或 provider 支援的 adaptive thinking 設定。
• 不要再把固定 thinking token budget 當成主要控制器；改用文件支援的 effort、task budget、prompt 約束與 eval 來校準任務深度。

Anthropic 的 prompting best practices 也把 effort levels、task budgets、thinking configuration、sampling-parameter removal 與 tokenization 列為從 Opus 4.6 遷移到 Opus 4.7 時要看的 API 變更。

2. 把 sampling 參數的控制搬回 prompt 與 eval

如果舊 workflow 依賴 temperature、top_p 或 top_k 來控制創意度、穩定度或輸出差異，升級時要重新設計。Anthropic 的 prompting 文件把 sampling-parameter removal 列入 Opus 4.7 遷移注意事項；OpenRouter 的 Claude 4.7 migration guide 也列出 sampling parameters removed、adaptive-only thinking 與 provider-specific effort 行為。

這會影響三種常見任務：

• 創意寫作或行銷文案：過去可能靠較高 sampling 取得更發散的版本。
• 客服、合規、資料抽取：過去可能靠較低 sampling 追求穩定。
• 批次生成：過去可能用 sampling 參數控制多樣性。

升級後，較穩的控制方式是把規則移到 prompt 與 eval：明確定義語氣、格式、禁止事項與成功標準；用 few-shot 範例固定輸出風格；對抽取、分類與報告產生使用結構化輸出要求；把舊版 Claude 的 golden examples 變成 regression eval，逐題比較 Opus 4.7 的格式遵循、正確率、成本與延遲。

3. Tool use：把「何時查工具」寫成明確 policy

如果舊 workflow 是給 Claude 一個寬鬆目標，讓模型自己判斷何時查工具，升級時最值得補強的是 tool policy。Anthropic 的 prompting best practices 指出，Claude 最新模型受訓於精準遵循指令，且會受益於明確要求使用特定工具；同一份文件也建議將 adaptive thinking 用於 multi-step tool use、complex coding tasks 與 long-horizon agent loops 等 agentic workload。

可把這類規則直接寫進 system prompt 或工作流 policy：

• 涉及即時資訊、價格、政策、版本差異或外部文件時，必須先使用指定查詢工具。
• 內部 knowledge base 沒有答案時，必須說明無法確認，不得猜測。
• 工具結果彼此矛盾時，先列出衝突，再給出保守結論。
• 最終答案要區分哪些資訊來自工具結果，哪些是模型推論。

這通常比單純替換 model ID 更重要，因為 tool policy 會直接影響 agent 是否漏查資料、是否在資料不足時亂猜，以及工具結果衝突時是否過度自信。

4. 長任務 agent：用 effort 和 task budget 思考成本

Opus 4.7 的一個遷移重點是長任務與 agentic workflow 的預算控制。Anthropic 的 What’s new 文件指出，Opus 4.7 introduces task budgets；官方文件也說，effort 參數可在能力、速度與 token spend 之間取捨，task budget 則讓 Claude 對整體任務可用 token 有概略估計。

如果你的 workflow 是 coding agent、research agent、browser agent、長時間資料處理或多工具 loop，建議把 budget 分成三層：

• 單次回覆 budget：最終輸出可以用多少 token。
• 推理與工具 budget：多步驟任務中，模型可以投入多少 reasoning、tool calls 與 tool results。
• 任務級 budget：整段 agent loop 的成本與延遲上限。

不要只用最終輸出上限來估整段 agent loop 成本。長任務的成本可能來自多次工具查詢、工具結果回灌、圖片或 PDF 解析、重試與最終輸出；Opus 4.7 的 task budgets 與新 tokenizer 都讓這件事更需要重新 benchmark。

5. Token、RAG、快取與 batch：重跑 benchmark

這是最容易被低估的遷移項。Anthropic 文件指出，Opus 4.7 的新 tokenizer 在處理文字時，可能會比前代模型使用約 1x 到 1.35x 的 token；/v1/messages/count_tokens 對 Opus 4.7 回傳的 token count 也會不同於 Opus 4.6，Anthropic 建議用該 endpoint 重新估算。

升級前應重測：

• RAG chunk size 與 overlap。
• 長文件截斷門檻。
• conversation memory 長度。
• prompt caching 命中率與成本預估。
• batch job 的成本上限。
• agent 每輪工具結果可回灌的大小。
• 圖片與 PDF 的預處理策略。

如果舊 workflow 已接近成本上限或 context limit，不要直接沿用舊版 token 估算。先用核心 prompt、長文件樣本與高流量任務跑 token benchmark，再決定是否調整 chunking、截斷或 cache key 設計。

6. 圖片、截圖與 PDF：重設前處理規則

Opus 4.7 文件提到 high-resolution image support；官方文件也提醒，如果不需要額外影像保真度，應在送進 Claude 前先 downsample，以避免 token 使用增加。

這會影響三類工作流：

• 截圖理解：例如 UI QA、表格截圖、dashboard 分析。
• 文件影像處理：例如掃描 PDF、合約截圖、簡報頁面。
• computer-use / browser automation：例如模型需要理解畫面位置、按鈕、表單與錯誤訊息。

從 Opus 4.6 升級時，PDF 與 vision 能力本身仍在 Anthropic 列出的同一組主要平台能力中；真正要重測的是送多大圖片、是否需要高解析度、以及 downsample 後關鍵文字與 UI 元件是否仍可辨識。

7. Provider 或內部 gateway：不要假設參數映射相同

如果你不是直接打 Anthropic API，而是透過 OpenRouter、雲端平台或內部 gateway 呼叫 Claude，不能假設欄位名稱、忽略規則與 effort 行為完全相同。OpenRouter 的 Claude 4.7 migration guide 就單獨列出 sampling parameters removed、adaptive-only thinking 與 provider-specific effort 行為。

因此，除了 Anthropic 文件，也要查你實際 provider 的 migration note。特別是多模型 router、fallback gateway、內部 prompt 平台，常會把上游 API 參數包成自己的欄位；升級時應確認哪些欄位仍有效、哪些會被忽略、哪些會導致錯誤。

哪些通常不用大改？

如果你是從 Opus 4.6 升到 Opus 4.7，平台能力不是全部翻新。Anthropic migration guide 表示，Opus 4.7 支援與 Opus 4.6 相同的主要功能集合，包括 1M token context window、128k max output tokens、adaptive thinking、prompt caching、batch processing、Files API、PDF support、vision，以及完整的 server-side / client-side tools。

也就是說，第一優先通常不是重寫這些基礎架構：

• Files API 與文件上傳流程。
• PDF / vision 能力是否存在。
• prompt caching 或 batch processing 是否可用。
• 工具呼叫能力本身。
• 長 context 能力本身。

真正要重校的是你如何控制這些能力：何時用工具、花多少 token、用多高 effort、圖片送多大，以及失敗時如何 fallback。

實際遷移 checklist

把這份清單交給工程、AI platform owner 或負責 Claude workflow 的團隊，可以快速找出高風險點。

API 與參數

• 將模型名稱切換到 claude-opus-4-7，並先做小流量或 shadow eval；Anthropic 表示開發者可透過 Claude API 使用這個 model ID。
• 搜尋 thinking、budget_tokens 與舊式 extended thinking wrapper，改成 adaptive thinking；Opus 4.7 或之後不支援舊式設定，會回傳 400。
• 搜尋 temperature、top_p、top_k 等 sampling 控制，改用 prompt、few-shot、schema 與 eval 管理穩定性。
• 若透過 OpenRouter 或其他代理層使用 Claude，另查該 provider 的 Claude 4.7 migration guide 與參數映射。

Prompt 與 tool use

• 把何時必須用工具寫進 system prompt；Anthropic 文件指出最新 Claude 模型受益於明確的 tool-use 指示。
• 把何時不能猜答案、資料不足時如何回答寫清楚。
• 把工具結果衝突、工具失敗、外部資料不足時的 fallback 行為寫清楚。
• 對資料抽取、分類、報告產生等 workflow 加上結構化輸出格式。

Agent 與 coding workflow

• 對 coding agent、research agent、browser agent 重新校準 effort 與任務預算；Anthropic 文件將 adaptive thinking 與 multi-step tool use、complex coding tasks、long-horizon agent loops 連在一起討論。
• 評估是否使用 task budgets；Opus 4.7 文件列出 task budgets，並提醒 token counting 與前代不同。
• 不要只用最終輸出上限估整段 agent loop 成本；把工具呼叫、工具結果、重試與最終輸出都納入成本模型。
• 用舊版 Claude 的成功案例建立 regression eval，比較 Opus 4.7 的成功率、格式遵循、延遲與成本。

Token、文件與影像

• 用 /v1/messages/count_tokens 重新估算核心 prompt、RAG chunks、長文件與批次任務成本。
• 重測 chunk size、截斷門檻、conversation memory 與 prompt caching 策略。
• 對圖片、截圖與 PDF 頁面建立 downsample policy；不需要高保真時先降低解析度，以控制 token 使用。

建議升級順序

最穩的升級方式不是一次全面替換，而是分四步：

1. 靜態掃描：找出 model ID、thinking、sampling、token counting、image preprocessing 與 provider-specific 參數。
2. 小流量 eval：用既有 golden set 比較舊版 Claude 與 Opus 4.7 的輸出品質、格式遵循、tool use、成本與延遲。
3. 重寫高風險 prompt：優先處理 tool use、RAG、coding agent、資料抽取與合規任務。
4. 逐步放量：監控 token 使用、工具呼叫次數、錯誤率、延遲與人工回報。

一句話總結：從舊版 Claude 搬到 Opus 4.7，核心不是把 prompt 全部重寫，而是把舊 workflow 裡隱含的控制邏輯顯性化。thinking 改 adaptive，sampling 改 prompt/eval，長任務改預算驅動，圖片與 token 成本重新 benchmark；這樣升級風險最低，也最能保留舊 workflow 的可控性。