--- title: Effort（投入程度） url: https://platform.claude.com/docs/zh-TW/build-with-claude/effort description: 使用 effort 參數控制 Claude 回應時使用的 token 數量，在回應的完整程度與 token 效率之間取得平衡。 featureMetadata: status: ga zdr: eligibility: eligible note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). supportedModels: - claude-fable-5-1 - claude-mythos-5-1 - claude-fable-5 - claude-mythos-5 - claude-mythos-preview - claude-opus-5-5 - claude-opus-5 - claude-opus-4-8 - claude-opus-4-7 - claude-opus-4-6 - claude-opus-4-5-20251101 - claude-sonnet-5-5 - claude-sonnet-5 - claude-sonnet-4-6 - claude-haiku-5-5 supportedPlatforms: Claude API: ga Claude Platform on AWS: ga Amazon Bedrock: ga Google Cloud: ga Microsoft Foundry: ga --- 「effort」（投入程度）參數讓您控制 Claude 在回應請求時花費多少 token。您可以使用單一模型，在回應的完整性與 token 效率之間進行取捨。頂層 effort 參數在所有支援的模型上皆可使用，無需 beta 標頭。[逐訊息 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta) 目前為 beta 版。若要了解 effort 如何與思考互動，以及該使用哪一種控制方式，請參閱[思考與 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-effort)。在可使用「adaptive thinking」（自適應思考）的情況下，effort 是控制思考深度的建議方式。 ## 設定 effort 等級在請求上設定 `output_config.effort`。以下範例以 `medium` effort 執行一個請求，並印出回應文字。 ```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"}' \ --transform 'content.#(type=="text").text' \ --raw-output ``` ```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 ``` ## effort 的運作方式大多數 Claude 模型預設為 high effort，會花費所需的 token 數量以獲得出色的結果；Claude Opus 5.5 和 Claude Haiku 5.5 則預設為 medium。您可以將 effort 等級提高到 `max` 以獲得絕對最高的能力，或將其降低以更節省 token 用量，在接受部分能力降低的同時針對速度和成本進行最佳化。將 `effort` 設定為模型的預設值（Claude Opus 5.5 和 Claude Haiku 5.5 上為 `"medium"`，其他模型上為 `"high"`），所產生的行為與完全省略 `effort` 參數完全相同。 effort 參數會影響回應中的**所有 token**，包括： * 文字回應和說明 * 工具呼叫和函式引數 * 思考（啟用時）由於 effort 適用於每個輸出 token，因此無論是否啟用思考，它都能運作。較低的 effort 也意味著更少且更簡潔的工具呼叫。 ### effort 等級 | 等級 | 說明 | 典型使用情境 | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | `max` | 絕對最高的能力，對 token 花費沒有任何限制。適用於 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5.5、Claude Sonnet 5、Claude Sonnet 4.6 和 Claude Haiku 5.5。 | 需要最深入推理和最徹底分析的任務 | | `xhigh` | 適用於長時程工作的擴展能力。適用於 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Sonnet 5.5、Claude Sonnet 5 和 Claude Haiku 5.5。 | 長時間執行（超過 30 分鐘）且 token 預算達數百萬的代理式和程式設計任務 | | `high` | 花費任務所需的 token 數量以獲得出色的結果。除 Claude Opus 5.5 和 Claude Haiku 5.5 外，所有支援 effort 的模型皆以此為預設值。 | 複雜推理、困難的程式設計問題、代理式任務 | | `medium` | 平衡的方法，可適度節省 token。Claude Opus 5.5 和 Claude Haiku 5.5 的預設值。 | 需要在速度、成本和效能之間取得平衡的代理式任務 | | `low` | 最有效率。大幅節省 token，但能力會有所降低。 | 需要最佳速度和最低成本的較簡單任務，例如子代理 | 並非每個支援 `max` 的模型都支援 `xhigh`。 effort 是一種行為訊號，而非嚴格的 token 預算。在較低的 effort 等級下，Claude 在面對足夠困難的問題時仍會思考，但對於相同問題，其思考量會少於較高 effort 等級時的思考量。以下各模型的建議若與此表格不同，以各模型的建議為準。 ### Claude Fable 5.1 的建議 effort 等級 Claude Fable 5.1 支援全部五個 effort 等級。**請從預設值 `high` 開始。**對於對能力最敏感的代理式與程式設計工作，可提升至 `xhigh` 或 `max`；對於例行性或對延遲敏感的工作，一旦您的評估顯示品質得以維持，即可降至 `medium` 或 `low`。在 `high` 及以上等級時，請設定較大的 `max_tokens`。它是總輸出（思考加上回應文字）的硬性上限。相同的建議也適用於 Claude Mythos 5.1。請參閱[提示 Claude Fable 5.1](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#consider-all-effort-levels)。 Claude Fable 5.1 也支援透過逐訊息的 `output_config` [在對話中途變更 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留提示快取。 ### Claude Fable 5 的建議 effort 等級在 Claude Fable 5 上，effort 是在智慧、延遲與成本之間進行取捨的主要控制方式。**對於大多數任務，請從預設值 `high` 開始**，對於對能力最敏感的工作負載使用 `xhigh`，對於例行性工作則降至 `medium` 或 `low`。Claude Fable 5 上較低的 effort 設定仍然表現良好，且通常超越先前模型在 `xhigh` 下的表現。在 `high` 與 `xhigh` 時，請設定較大的 `max_tokens`。它是總輸出（思考加上回應文字）的硬性上限。請參閱[成本控制](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-steering-and-cost#cost-control)。如果任務能夠完成但花費的時間超過必要，或者您想要更快速、更具互動性的工作風格，請降低 effort。相同的建議也適用於 Claude Mythos 5。如需更完整的指引，請參閱[提示 Claude Fable 5](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-fable-5)。 ### Claude Opus 5.5 的建議 effort 等級 Claude Opus 5.5 支援全部五個 effort 等級，且預設值為 `medium`（Claude Opus 5 及更早的 Opus 模型預設為 `high`，因此省略 `effort` 的請求會比在 Claude Opus 5 上低一個等級執行）。自適應思考始終開啟且無法關閉，因此 effort 是控制模型推理量以及請求成本的主要方式。請在您自己的評估上執行 effort 掃描，而不是沿用先前模型的設定，並在較高等級時設定較大的 `max_tokens`：它是總輸出（思考加上回應文字）的硬性上限。設定 `thinking: {"type": "disabled"}` 的請求在任何 effort 等級下都會傳回 400 錯誤。Claude Opus 5.5 也支援透過逐訊息的 `output_config` [在對話中途變更 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留提示快取。請參閱[提示 Claude Opus 5.5](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)。 ### Claude Opus 5 的建議 effort 等級 Claude Opus 5 支援全部五個 effort 等級。**從預設值 `high` 開始**，並根據您的評估進行調整：對於要求嚴苛的程式設計和代理式工作，提高到 `xhigh`；當任務值得不受限制地花費 token 時，提高到 `max`；並在評估顯示品質維持不變的情況下，大量使用 `low` 和 `medium` 作為控制 token 成本和回應時間的主要方式。如果您沿用了先前模型的 effort 設定，請在您的評估上重新執行 effort 掃描，而不是重複使用這些設定。 effort 控制的是思考量，而非可見的回應長度：在 Claude Opus 5 上，變更 effort 並不能可靠地縮短回應，因此請改為[透過提示控制長度](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-opus-5#response-length-and-verbosity)。 API 預設值為 `high`。若要使用不同的等級，請明確設定 `effort`。您傳入的值會覆寫預設值。在 Claude Opus 5 上，於 `xhigh` 或 `max` effort 時無法停用思考：在這些等級設定 `thinking: {"type": "disabled"}` 的請求會傳回 400 錯誤。請參閱[effort 與思考](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#effort-with-thinking)。以 `xhigh` 或 `max` effort 執行 Claude Opus 5 時，請設定較大的 `max_tokens`，讓模型有空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並以此為基礎進行調整，是合理的預設做法。 Claude Opus 5 也支援透過每則訊息的 `output_config` [在對話中途變更 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留提示快取。在 Amazon Bedrock 上，Claude Opus 5 無法使用每則訊息的 effort。 ### 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 4.7 的建議 effort 等級 **程式設計和代理式使用情境請從 `xhigh` 開始**，並將 `high` 作為大多數講求智慧的工作負載的最低等級。對於成本敏感的工作負載，降低到 `medium`；只有在您的評估顯示 `xhigh` 仍有可測量的提升空間時，才提高到 `max`。 API 預設值為 `high`。若要使用 `xhigh`，請明確設定 `effort`。您傳入的值會覆寫預設值。 | effort | Claude Opus 4.7 的指引 | | -------- | -------------------------------------------------------------------------- | | `low` | 有效率，但最適合簡短、範圍明確的任務。如果您的任務有多個部分，請將 `low` 搭配明確的檢查清單使用。 | | `medium` | 適用於一般工作流程的直接替代選項，可在降低成本的同時獲得良好結果。 | | `high` | 仍需要在智慧與 token 消耗之間取得平衡的進階使用情境。這通常是品質與 token 效率之間的最佳平衡。 | | `xhigh` | 程式設計和代理式工作的建議起點，也適用於探索性任務，例如重複的工具呼叫、詳細的網頁搜尋和知識庫搜尋。預期 token 用量會明顯高於 `high`。 | | `max` | 保留給最前沿的問題。在大多數工作負載上，`max` 會增加大量成本，但品質提升相對較小；在某些結構化輸出或較不講求智慧的任務上，它可能導致過度思考。 | Claude Opus 4.7 也比 Claude Opus 4.6 更嚴格地遵守 effort 等級，尤其是在 `low` 和 `medium` 時。在較低的 effort 等級下，模型會將工作範圍限定在所要求的內容，而不會做超出要求的事。如果您在使用 Claude Opus 4.7 處理複雜問題時觀察到推理過於淺薄，請提高 effort，而不是透過提示來繞過問題。如果您必須為了延遲而保持較低的 effort，請加入有針對性的指引，例如「This task involves multistep reasoning. Think carefully before responding.」以 `xhigh` 或 `max` effort 執行 Claude Opus 4.7 時，請設定較大的 `max_tokens`，讓模型有空間在子代理和工具呼叫之間進行思考和行動。從 64k token 開始並以此為基礎進行調整，是合理的預設做法。 ### Claude Sonnet 5.5 的建議 effort 等級 Claude Sonnet 5.5 支援全部五個 effort 等級，且在 Claude API 上的預設值為 `high`。其等級經過重新校準，因此某個等級所產生的思考量與 Claude Sonnet 5 上相同等級的思考量並不相同。請在您的評估上重新執行 effort 掃描，而不是沿用您在 Claude Sonnet 5 上使用的設定。除非您的工作負載是代理式或對延遲敏感的，否則請從 `high` 開始。對於代理式程式設計和多步驟工具使用，規格明確的任務請從 `medium` 開始，較困難或較長的任務則改用 `high`。對於聊天和其他對延遲敏感的工作，請從 `medium` 或 `low` 開始。只有在您的評估顯示品質有所提升時，才使用 `xhigh` 或 `max`。設定 `max_tokens` 時請為思考和回覆預留空間。即使未傳回思考內容，思考仍會計入 `max_tokens`。對於代理式程式設計，請將 `max_tokens` 設定為模型的最大值 128,000，並以[串流](https://platform.claude.com/docs/zh-TW/build-with-claude/streaming)方式接收回應。若要關閉預先思考，請傳送 `thinking: {"type": "between_tools"}` 而非 `"disabled"`。這是 Claude Sonnet 5.5 上最低的思考設定，可在 `low`、`medium` 和 `high` effort 下運作。在 `xhigh` 或 `max` 時，使用此設定的請求會傳回 400 錯誤，因此在這些等級請使用自適應思考：省略 `thinking` 欄位或傳送 `thinking: {"type": "adaptive"}`。請參閱[在沒有預先思考的情況下執行](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking)。 Claude Sonnet 5.5 也支援透過每則訊息的 `output_config` [在對話中途變更 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留提示快取。使用 `between_tools` 時，effort 無法在對話中途變更：與目前生效等級不同的每則訊息 `output_config.effort` 會傳回 400 錯誤。若要在每個回合變更 effort，請使用自適應思考。請參閱[為 Claude Sonnet 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort)。 ### Claude Sonnet 5 的建議 effort 等級 Claude Sonnet 5 在 Claude API 與 Claude Code 上預設為 `high` effort。 * **High effort（預設）：**適用於品質比速度或成本更重要的複雜推理、程式設計與代理式任務。 * **Xhigh effort：**適用於最困難的程式設計與代理式任務。請參閱[提示 Claude Sonnet 5](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-sonnet-5#calibrating-effort-and-thinking-depth)。 * **Medium effort：**從預設值降級以節省成本。與 Claude Sonnet 4.6 在 high effort 下的表現相當。 * **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 Haiku 5.5 的建議 effort 等級 Claude Haiku 5.5 支援全部五個 effort 等級，且 `medium` 為預設值。Effort 是控制模型思考量的主要方式，並連帶影響品質、延遲和成本。大多數工作（包括代理式程式設計）**請從 `medium` 開始**。對於聊天、簡短的工具任務以及簡單的大量請求，請使用最便宜且最快速的等級 `low`。在冗長的代理提示中，模型在 `low` 時較可能略過搜尋、提早停止或略過檢查。對於知識工作、較長的代理任務和嚴格遵循指示，請使用 `high`。只有在您的評估顯示品質有所提升時，才使用 `xhigh` 或 `max`，並在效能、成本和速度方面將其與 Claude Sonnet 5.5 進行比較。思考預設為開啟且會計入 `max_tokens`，因此請為其預留空間。請參閱[為 Claude Haiku 5.5 撰寫提示](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking)。若要減少思考，請降低 effort 等級。您也可以在 `high` effort 或以下傳送 `thinking: {"type": "disabled"}`。在 `xhigh` 或 `max` 時，這會傳回 400 錯誤，因此在這些等級請使用自適應思考：省略 `thinking` 欄位或傳送 `thinking: {"type": "adaptive"}`。在 Claude API 和 Google Cloud 上，Claude Haiku 5.5 也支援透過每則訊息的 `output_config` [在對話中途變更 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留提示快取。使用 `thinking: {"type": "disabled"}` 時，effort 無法在對話中途變更：與目前生效等級不同的每則訊息 `output_config.effort` 會傳回 400 錯誤。若要在每個回合變更 effort，請使用自適應思考。 ## effort 與工具使用使用工具時，effort 參數會同時影響工具呼叫周圍的說明以及工具呼叫本身。較低的 effort 等級傾向於： * 將多個操作合併為較少的工具呼叫 * 進行較少的工具呼叫 * 不加開場白，直接採取行動 * 完成後使用簡潔的確認訊息較高的 effort 等級可能會： * 進行更多的工具呼叫 * 在採取行動前說明計畫 * 提供詳細的變更摘要 * 包含更完整的程式碼註解 ## effort 與思考 `thinking` 參數控制 Claude 是否在回答之前於[思考區塊](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking)中進行思考；`effort` 參數則控制 Claude 在整個回應中投入多少工作量，在自適應模式下，這包括它思考的頻率與深度。請勿將 `adaptive` 作為 `effort` 的值傳入：`adaptive` 是一種思考模式，而非努力程度等級。在較高的 effort 等級下，Claude 會更積極地思考，且思考時間更長。在工具使用迴圈中，僅處理工具結果的後續請求在任何等級下仍可能略過思考。在較低的等級下，Claude 對於較簡單的問題可能會完全略過思考。如需這兩種控制方式如何協同運作的完整指引，請參閱[思考與 effort](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-effort)。在 Claude Opus 4.5（唯一支援 effort 且僅支援「extended thinking」（擴展思考）的模型）上，它與 [`budget_tokens`](https://platform.claude.com/docs/zh-TW/build-with-claude/extended-thinking) 搭配運作：先為您的任務設定 effort 等級，然後根據任務所需的推理深度設定思考 token 預算。關於各模型的思考可用性，請參閱[各模型設定表](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking-troubleshooting#supported-models)。無論是否啟用思考，effort 都能運作。請參閱[effort 的運作方式](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#how-effort-works)。 ## 在對話中途變更 effort 您可以透過兩種方式，以不同的 effort 等級執行對話的後續回合。在 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，請使用每則訊息的 effort 變更，這樣可以保留提示快取。在其他模型上，請在下一個請求中設定新的頂層值，這會讓快取重新開始。 ### 逐訊息 effort（beta）每則訊息的 effort 目前為 beta 版。在 Claude API 和 [Google Cloud](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-vertex-ai) 上，它適用於 Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Sonnet 5.5 和 Claude Haiku 5.5。在 [Amazon Bedrock](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock) 上，它適用於 Claude Fable 5.1、Claude Mythos 5.1 和 Claude Opus 5.5。它需要 [beta 標頭](https://platform.claude.com/docs/zh-TW/api/beta-headers) `mid-conversation-output-config-2026-07-01`。使用 Amazon Bedrock [InvokeModel API](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy) 時，它適用於 Claude Fable 5.1 和 Claude Opus 5.5，且您需改為在請求主體的 `anthropic_beta` 陣列中傳送該值。若沒有 beta 值，每則訊息的 `output_config` 會傳回 400 錯誤：`messages.N.output_config: Extra inputs are not permitted`，其中 `N` 是 `system` 訊息在 `messages` 中的索引。若有 beta 值，不支援每則訊息 effort 的模型（包括 Claude Fable 5）會傳回 400 錯誤：`output_config.effort requires a model that supports per-turn effort; this model does not`。在 Amazon Bedrock 上，這些模型和 Claude Opus 5 則會改為傳回 `Extra inputs are not permitted` 錯誤。在使用 `thinking: {"type": "between_tools"}` 的 Claude Sonnet 5.5 上，以及使用 `thinking: {"type": "disabled"}` 的 Claude Haiku 5.5 上，effort 無法在對話中途變更：與目前生效等級不同的每則訊息 `output_config.effort` 會傳回 400 錯誤。若要在每個回合變更 effort，請使用自適應思考。新增一則 `role: "system"` 訊息，其 `content` 為空，並在 `output_config.effort` 中設定新的等級。若將其直接放在含有新輸入的 `user` 回合之後，它會設定 Claude 對該回合回覆的等級。若放在其他任何位置，例如像以下範例那樣放在 `assistant` 回合與下一個 `user` 回合之間，它會從下一個含有新輸入的 `user` 回合開始生效。僅包含 `tool_result` 區塊的 `user` 回合不算作新輸入，因此在工具使用迴圈中放在此類回合之後的變更，會等到下一個含有新輸入的 `user` 回合才生效。新的等級隨後會持續有效，直到後續訊息再次變更它為止。該訊息之前的所有內容都保持不變，因此快取的前綴仍然相符。以下範例從 `high` 開始，然後在例行性的後續問題中降低到 `low`： ```bash cURL # 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。 curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: mid-conversation-output-config-2026-07-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-fable-5-1", "max_tokens": 4096, "output_config": {"effort": "high"}, "messages": [ {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."}, {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."}, {"role": "system", "content": [], "output_config": {"effort": "low"}}, {"role": "user", "content": "Summarize the plan in one sentence."} ] }' ``` ```bash CLI ant beta:messages create --beta mid-conversation-output-config-2026-07-01 \ --transform 'content.#(type=="text").text' --raw-output <<'YAML' model: claude-fable-5-1 max_tokens: 4096 output_config: effort: high messages: - role: user content: Plan a migration from SQLite to PostgreSQL in three short steps. - role: assistant content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." # 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。 - role: system content: [] output_config: effort: low - role: user content: Summarize the plan in one sentence. YAML ``` ```python Python client = anthropic.Anthropic() response = client.beta.messages.create( model="claude-fable-5-1", max_tokens=4096, output_config={"effort": "high"}, messages=[ { "role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps.", }, { "role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.", }, # 僅含 effort 的系統訊息：新等級將自下一個使用者回合起生效。 {"role": "system", "content": [], "output_config": {"effort": "low"}}, {"role": "user", "content": "Summarize the plan in one sentence."}, ], betas=["mid-conversation-output-config-2026-07-01"], ) for block in response.content: if block.type == "text": print(block.text) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.beta.messages.create({ model: "claude-fable-5-1", max_tokens: 4096, output_config: { effort: "high" }, messages: [ { role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps." }, { role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." }, // 僅含 effort 的系統訊息：新等級將自下一個使用者回合起生效。 { role: "system", content: [], output_config: { effort: "low" } }, { role: "user", content: "Summarize the plan in one sentence." } ], betas: ["mid-conversation-output-config-2026-07-01"] }); for (const block of response.content) { if (block.type === "text") { console.log(block.text); } } ``` ```csharp C# using Anthropic.Models.Beta; using Anthropic.Models.Beta.Messages; using Model = Anthropic.Models.Messages.Model; AnthropicClient client = new(); var response = await client.Beta.Messages.Create(new MessageCreateParams { Model = Model.ClaudeFable5_1, MaxTokens = 4096, OutputConfig = new() { Effort = Effort.High }, Messages = [ new() { Role = Role.User, Content = "Plan a migration from SQLite to PostgreSQL in three short steps." }, new() { Role = Role.Assistant, Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." }, // 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。 new() { Role = Role.System, Content = new([]), OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low }, }, new() { Role = Role.User, Content = "Summarize the plan in one sentence." }, ], Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01], }); foreach (var block in response.Content) { if (block.TryPickText(out var textBlock)) { Console.WriteLine(textBlock.Text); } } ``` ```go Go client := anthropic.NewClient() response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{ Model: anthropic.ModelClaudeFable5_1, MaxTokens: 4096, OutputConfig: anthropic.BetaOutputConfigParam{ Effort: anthropic.BetaOutputConfigEffortHigh, }, Messages: []anthropic.BetaMessageParam{ anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")), { Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")}, }, // 僅含 effort 的系統訊息：新等級將自下一個使用者回合起生效。 anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{ Effort: anthropic.BetaSystemMessageOutputConfigEffortLow, }), anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")), }, Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01}, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok { fmt.Println(textBlock.Text) } } ``` ```java Java import com.anthropic.models.beta.AnthropicBeta; import com.anthropic.models.beta.messages.BetaMessage; import com.anthropic.models.beta.messages.BetaMessageParam; import com.anthropic.models.beta.messages.BetaOutputConfig; import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig; import com.anthropic.models.beta.messages.MessageCreateParams; import com.anthropic.models.messages.Model; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_FABLE_5_1) .maxTokens(4096L) .addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01) .outputConfig(BetaOutputConfig.builder() .effort(BetaOutputConfig.Effort.HIGH) .build()) .addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.") .addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.") // 僅含 effort 的系統訊息：新等級將自下一個使用者回合起生效。 .addMessage(BetaMessageParam.builder() .role(BetaMessageParam.Role.SYSTEM) .contentOfBetaContentBlockParams(List.of()) .outputConfig(BetaSystemMessageOutputConfig.builder() .effort(BetaSystemMessageOutputConfig.Effort.LOW) .build()) .build()) .addUserMessage("Summarize the plan in one sentence.") .build(); BetaMessage response = client.beta().messages().create(params); response.content().stream() .flatMap(block -> block.text().stream()) .forEach(textBlock -> IO.println(textBlock.text())); } ``` ```php PHP use Anthropic\Beta\AnthropicBeta; use Anthropic\Beta\Messages\BetaMessageParam; use Anthropic\Beta\Messages\BetaOutputConfig; use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig; use Anthropic\Client; $client = new Client(); $response = $client->beta->messages->create( model: 'claude-fable-5-1', maxTokens: 4096, outputConfig: BetaOutputConfig::with(effort: 'high'), messages: [ BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'), BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'), // 僅含 effort 的系統訊息：新等級自下一個使用者回合起生效。 BetaMessageParam::with( role: 'system', content: [], outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'), ), BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'), ], betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01], ); foreach ($response->content as $block) { if ($block->type === 'text') { echo $block->text, PHP_EOL; } } ``` ```ruby Ruby client = Anthropic::Client.new response = client.beta.messages.create( model: "claude-fable-5-1", max_tokens: 4096, output_config: {effort: :high}, messages: [ {role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps."}, {role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."}, # 僅含 effort 的系統訊息：新等級將自下一個使用者回合起生效。 {role: "system", content: [], output_config: {effort: :low}}, {role: "user", content: "Summarize the plan in one sentence."} ], betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01] ) response.content.each do |block| puts block.text if block.type == :text end ``` 僅包含 effort 的系統訊息不帶任何文字，因此[對話中途系統訊息的放置規則](https://platform.claude.com/docs/zh-TW/build-with-claude/mid-conversation-system-messages#limitations)不適用。它可以出現在 `messages` 中的任何位置，包括作為第一個項目，或位於 `assistant` 回合與下一個 `user` 回合之間。值為等級名稱（`low`、`medium`、`high`、`xhigh` 和 `max`）。請優先使用此形式，而不是在請求之間變更頂層值。頂層變更會重新開始快取，而且在 Claude Fable 5.1 上，對模型的引導效果也較不可靠：它先前的回覆是以先前的等級撰寫的，而它傾向於與這些回覆保持一致。 ### 在下一個請求上設定頂層 effort 頂層 `output_config.effort` 適用於整個請求。若要以不同的等級執行對話的後續部分，請在下一個請求上設定新的值。由於頂層 effort 會影響所呈現的提示，因此在請求之間變更它不會保留先前輪次的已快取前綴。如果您在長時間的工作階段中依賴[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)，而您的模型不支援逐訊息 effort，請在一開始就選定一個 effort 等級並保持不變。 ## 最佳實務 1. **明確設定 effort：** API 預設為 `high`（Claude Opus 5.5 和 Claude Haiku 5.5 上為 `medium`），但合適的起點取決於您的模型和工作負載。 2. **對速度敏感或簡單的任務使用 low：** 當延遲很重要或任務很直接時，low effort 可以大幅縮短回應時間並降低成本。 3. **測試您的使用情境：** effort 等級的影響因任務類型而異。部署前請針對您的特定使用情境評估效能。 4. **考慮動態 effort：** 根據任務複雜度調整 effort。簡單的查詢可能適合 low effort，而代理式程式設計和複雜推理則能從 high effort 中受益。在同一個對話中變更 effort 之前，請參閱下一項。 5. **在快取的對話中保持頂層 effort 不變：** 在請求之間變更頂層 effort 值會使[提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)失效，因此請在不同工作負載之間變更它，而不是在依賴快取命中的對話中變更。在支援的模型上，請改用[逐訊息 effort 變更](https://platform.claude.com/docs/zh-TW/build-with-claude/effort#change-effort-mid-conversation-beta)，這樣可以保留快取。請參閱[思考與提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/thinking#thinking-and-prompt-caching)。 ## 後續步驟為 Claude 提供整個代理式迴圈的建議性 token 預算，協助模型在長時間的代理式任務中自我調節。了解自適應思考（由 Claude 決定何時思考以及思考多少），並透過 effort 和提示來引導它。了解思考的運作方式、Claude 何時預設會思考，以及思考如何與 effort 互動。