Effort

「effort」參數讓您能夠控制 Claude 在回應請求時所花費的 token 數量。您可以透過單一模型在回應完整性與 token 效率之間取得平衡。effort 參數在所有支援的模型上皆可使用，無需 beta 標頭。



Effort 的運作方式

預設情況下，Claude 使用 high effort，會盡可能使用所需的 token 以獲得優異的結果。您可以將 effort 等級提高至 max 以獲得絕對最高的能力，或降低等級以更保守地使用 token，在接受部分能力降低的同時，針對速度和成本進行最佳化。

effort 參數會影響回應中的所有 token，包括：

• 文字回應與說明
• 工具呼叫與函式引數
• 思考（啟用時）

這種方法有兩個主要優點：

1. 不需要啟用思考功能。
2. 可以影響所有 token 花費，包括工具呼叫。例如，較低的 effort 意味著 Claude 會進行較少的工具呼叫。這讓您對效率有更大程度的控制。



Effort 等級

xhigh 是較新的等級；部分支援 max 的模型不支援 xhigh。



Claude Sonnet 5 的建議 effort 等級

Claude Sonnet 5 在 Claude API 和 Claude Code 上預設為 high effort。

• High effort（預設）： 適用於品質比速度或成本更重要的複雜推理、程式編寫和代理任務。
• Xhigh effort： 適用於最困難的程式編寫和代理任務。請參閱為 Claude Sonnet 5 撰寫提示。
• Medium effort： 從預設值降低一級以節省成本。與 high effort 下的 Claude Sonnet 4.6 相當。
• Low effort： 適用於高流量或對延遲敏感的工作負載。適合優先考慮快速回應的聊天和非程式編寫使用情境。
• Max effort： 適用於需要絕對最高能力且對 token 花費沒有任何限制的任務。



Claude Sonnet 4.6 的建議 effort 等級

Sonnet 4.6 預設為 high effort。使用 Sonnet 4.6 時請明確設定 effort，以避免非預期的延遲：

• Medium effort（建議預設值）：對大多數應用程式而言，在速度、成本和效能之間取得最佳平衡。適用於代理程式編寫、大量使用工具的工作流程和程式碼生成。
• Low effort： 適用於高流量或對延遲敏感的工作負載。適合優先考慮快速回應的聊天和非程式編寫使用情境。
• High effort： 適用於品質比速度或成本更重要的複雜推理和任務。
• Max effort： 適用於需要絕對最高能力且對 token 花費沒有任何限制的任務。



Claude Opus 4.7 的建議 effort 等級

針對程式編寫和代理使用情境，請從 xhigh 開始，並將 high 作為大多數對智慧敏感工作負載的最低設定。對於成本敏感的工作負載，可降至 medium；僅當您的評估顯示在 xhigh 下仍有可測量的提升空間時，才升至 max。

API 預設值為 high。若要使用 xhigh，請明確設定 effort；您傳入的值會覆寫預設值。

Claude Opus 4.7 也比 Claude Opus 4.6 更嚴格地遵守 effort 等級，尤其是在 low 和 medium 等級。在較低的 effort 等級下，模型會將工作範圍限定在所要求的內容，而不會做超出要求的事。如果您在使用 Claude Opus 4.7 處理複雜問題時觀察到推理過於淺顯，請提高 effort，而非透過提示來繞過此問題。如果您必須為了延遲而保持低 effort，請加入針對性的指引，例如「此任務涉及多步驟推理。請在回應前仔細思考。」

在以 xhigh 或 max effort 執行 Claude Opus 4.7 時，請設定較大的 max_tokens，讓模型有足夠空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並據此調整是合理的預設值。



Claude Opus 4.8 的建議 effort 等級

Claude Opus 4.7 的指引同樣適用於 Claude Opus 4.8。針對程式編寫和代理使用情境，請從 xhigh 開始，對於大多數其他對智慧敏感的工作負載使用 high，僅當您已透過評估確認較低等級能維持品質時，才降至 medium 或 low。

API 預設值為 high。若要使用不同的等級，請明確設定 effort；您傳入的值會覆寫預設值。

在以 xhigh 或 max effort 執行 Claude Opus 4.8 時，請設定較大的 max_tokens，讓模型有足夠空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並據此調整是合理的預設值。



Claude Opus 5 的建議 effort 等級

Claude Opus 5 支援全部五個 effort 等級。從預設值 high 開始，並根據您的評估進行調整：對於要求較高的程式編寫和代理工作，升至 xhigh；當任務值得不受限制的 token 花費時，升至 max；在您的評估顯示品質能夠維持的情況下，可大方地使用 low 和 medium 作為控制 token 成本和回應時間的主要手段。如果您沿用了先前模型的 effort 設定，請在您的評估上重新進行 effort 掃描，而非直接重複使用。

Effort 控制的是思考量，而非可見的回應長度：在 Claude Opus 5 上，變更 effort 並不能可靠地縮短回應，因此請改為透過提示控制長度。

API 預設值為 high。若要使用不同的等級，請明確設定 effort；您傳入的值會覆寫預設值。

在 Claude Opus 5 上，xhigh 或 max effort 下無法停用思考：在這些等級下設定 thinking: {"type": "disabled"} 的請求會回傳 400 錯誤。請參閱 Effort 與思考。

在以 xhigh 或 max effort 執行 Claude Opus 5 時，請設定較大的 max_tokens，讓模型有足夠空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並據此調整是合理的預設值。



Claude Fable 5 的建議 effort 等級

Effort 是在 Claude Fable 5 上權衡智慧、延遲和成本的主要控制手段。對於大多數任務，請從預設值 high 開始，對於最需要能力的工作負載使用 xhigh，對於例行工作則降至 medium 或 low。Claude Fable 5 上較低的 effort 設定仍然表現良好，且通常超越先前模型在 xhigh 下的表現。在 high 和 xhigh 下，請設定較大的 max_tokens：這是總輸出（思考加上回應文字）的硬性限制。請參閱成本控制。

如果任務能夠完成但花費的時間超過必要，或者您想要更快速、更具互動性的工作方式，請降低 effort。相同的建議也適用於 Claude Mythos 5。如需更完整的指引，請參閱為 Claude Fable 5 撰寫提示。



基本用法

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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)



何時調整 effort 參數

• 當您需要絕對最高能力且沒有任何限制時，請使用 max effort：最徹底的推理和最深入的分析。適用於 Claude 4.6 及更新的模型以及 Claude Mythos Preview。
• 針對需要延伸探索的進階程式編寫和複雜代理工作（例如重複的工具呼叫和詳細搜尋），請使用 xhigh effort。適用於 Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7 和 Claude Sonnet 5。
• 針對複雜推理、細緻分析、困難的程式編寫問題，或任何品質比速度或成本更重要的任務，請使用 high effort（預設值）。
• 當您想要穩健的效能，但不想花費 high effort 的全部 token 時，請使用 medium effort 作為平衡選項。
• 當您針對速度（因為 Claude 以較少的 token 回答）或成本進行最佳化時，請使用 low effort。例如，簡單的分類任務、快速查詢，或邊際品質提升不足以證明額外延遲或花費合理的高流量使用情境。



Effort 與工具使用

使用工具時，effort 參數會同時影響工具呼叫周圍的說明以及工具呼叫本身。較低的 effort 等級傾向於：

• 將多個操作合併為較少的工具呼叫
• 進行較少的工具呼叫
• 直接採取行動而不加前言
• 完成後使用簡潔的確認訊息

較高的 effort 等級可能會：

• 進行更多的工具呼叫
• 在採取行動前說明計畫
• 提供變更的詳細摘要
• 包含更完整的程式碼註解



Effort 與思考

thinking 參數控制 Claude 是否在回答前於思考區塊中進行思考；effort 參數控制 Claude 在整個回應中投入多少工作量，在 adaptive 模式下，這包括思考的頻率和深度。請勿將 adaptive 作為 effort 的值傳入：adaptive 是一種思考模式，而不是一個工作量等級。

在較高的 effort 等級下，Claude 會對大多數請求進行思考，且思考篇幅更長；在較低的等級下，對於較簡單的問題可能完全跳過思考。請參閱思考與 effort 以取得關於這兩種控制方式如何協同運作的完整指引。

在 Claude Opus 4.5（唯一支援 effort 的僅限擴展思考模型）上，effort 與 budget_tokens 搭配運作：為您的任務設定 effort 等級，然後根據任務所需的推理深度設定思考 token 預算。

關於各模型的思考可用性，請參閱各模型設定表。Effort 無論是否啟用思考皆可運作；請參閱 Effort 的運作方式。



在對話中途變更 effort

output_config.effort 是請求層級的設定：每個請求都帶有自己的值，因此若要在對話的後續部分以不同的 effort 等級執行，請在下一個請求中設定新值。effort 等級會套用至整個請求。由於 effort 會影響渲染的提示，在請求之間變更它不會保留先前回合的快取前綴；如果您在長時間的工作階段中依賴提示快取，請在開始時選定一個 effort 等級並保持不變。



最佳實務

1. 明確設定 effort： API 預設為 high，但正確的起點取決於您的模型和工作負載。
2. 對速度敏感或簡單的任務使用 low： 當延遲很重要或任務較為簡單時，low effort 可以大幅減少回應時間和成本。
3. 測試您的使用情境： effort 等級的影響因任務類型而異。在部署前，請針對您的特定使用情境評估效能。
4. 考慮動態 effort： 根據任務複雜度調整 effort。簡單的查詢可能適合 low effort，而代理程式編寫和複雜推理則受益於 high effort。在單一對話中變更之前，請參閱下一項。
5. 在快取的對話中保持 effort 不變： 在請求之間變更 effort 值會使提示快取失效，因此請在不同工作負載之間變更 effort，而非在依賴快取命中的對話中變更。請參閱思考與提示快取。



後續步驟