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 的僅限擴展思考模型）上，它與 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。在單一對話中變更 effort 之前，請先參閱下一項。
5. 在有快取的對話中保持 effort 不變： 在請求之間變更 effort 值會使提示快取失效，因此請在不同工作負載之間變更 effort，而不是在依賴快取命中的對話中變更。請參閱思考與提示快取。



後續步驟