Claude Code effort 設定誰說了算：CLAUDE_CODE_EFFORT_LEVEL、--effort、modelSettings、effortLevel 與 maxEffortLevel 的優先順序

Claude Code 的 effort 設定散在好幾個地方：effortLevel、modelSettings、maxEffortLevel、--effort、環境變數 CLAUDE_CODE_EFFORT_LEVEL，還有 /effort 指令與 ultrathink 關鍵字。多個同時出現時誰說了算？本文整理官方設定參考頁裡的優先順序。我讀到的頁面有幾處被截斷，所以只寫我讀得到的部分，沒讀到的標明；我沒有實測任何組合。

優先順序，由高到低

1. CLAUDE_CODE_EFFORT_LEVEL：文件說它優先於 --effort 與 effortLevel 兩者。可接受的值我沒讀到。
2. --effort：只對那一個 session，優先於 effortLevel 這個設定。
3. 同一個設定檔裡，modelSettings 底下某個模型的 effortLevel，優先於頂層的 effortLevel。
4. 頂層 effortLevel：類型是字串，我讀到的值為 low、medium、high、xhigh，預設未設定；用來設定「你還沒替它存過等級的模型」的預設值。

最上面還有一道天花板：maxEffortLevel（v2.1.267 以上）。文件說它限制 session 可用的 effort；任何更高的等級，包括來自 /effort、/model 選單、--effort、CLAUDE_CODE_EFFORT_LEVEL 的，都以上限執行。值可以是 low 到 max，其中 max 代表不設上限。也可以在 modelSettings 裡替個別模型設不同的上限。

/effort 到底寫到哪裡

• 在你自己機器上的互動式 session 執行 /effort low、medium、high 或 xhigh，Claude Code 會把等級存在「目前這個模型」的 modelSettings 底下，不是寫頂層的 effortLevel。v2.1.251 之前，/effort 寫的是頂層那個 key。
• 連到遠端 worker 的 session、-p 執行與 Agent SDK 裡，/effort 只對該 session 生效。
• /effort auto 清除你替目前模型存的等級。

三個最容易踩的坑

• 使用者設定裡的 effortLevel 對新模型沒用：文件說，在 ~/.claude/settings.json 裡，這個 key 是 /effort 還沒改成每個模型各自儲存之前的舊形式，仍然套用在 Opus 5、Fable 5.1 與更早的模型；Opus 5.5 與之後發布的模型會忽略它，用自己的預設，直到你替它們存過等級。在專案、本機、managed 設定與 --settings 裡，這個 key 則對每個模型都適用。所以「我在使用者設定寫了 xhigh，為什麼 Opus 5.5 沒用到」有明確的答案。
• 天花板會蓋過你的明確指定：設了 maxEffortLevel: "medium" 之後，--effort xhigh 也只會以 medium 執行。
• 關掉 thinking 的組合：文件說，在 Anthropic API 上關掉 thinking 時，Claude Code 會對它已知不接受該組合的模型（例如 Opus 5）送 effort high，而不是更高的等級。而在永遠會思考的模型（Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 系列）上，把 thinking 設成 false 沒有效果。

ultracode 與 ultrathink

兩個容易混淆的東西。ultracode（設定頁有這個 key）是讓 Claude 對每個實質任務自動規劃工作流程；文件說它只在動態工作流程對你啟用、且你的模型支援 xhigh 時才規劃；它不改變 session 的 effort，用的是 session 目前的等級；/effort ultracode 只對目前 session 開啟，--effort ultracode 也只對一個 session、並以 xhigh 執行。v2.1.284 之前，ultracode: true 會讓 session 以 xhigh 執行，而低於 xhigh 的上限會讓 ultracode 關閉。ultrathink 則是 prompt 裡的關鍵字：v2.1.311 的更新說明寫，在互動式終端機、透過 Anthropic API 使用 Opus 5.5、Sonnet 5.5、Haiku 5.5 與 Fable 5.1 時，那一回合以 xhigh effort 執行；在 Claude 工作中輸入，則提高該回合剩下的部分。我讀到的設定頁沒有出現 ultrathink 這個詞，所以它的行為只依據更新說明。另外，maxEffortLevel 的上限是否也限制 ultrathink，我在讀到的內容裡找不到，不要假設。

我的判斷：怎麼設才不亂

以下是我的整理，不是官方建議：個人偏好用 /effort（它存進各模型自己的位置）；團隊要統一的上限用 maxEffortLevel 放 managed 或專案設定，因為它連明確指定都能蓋過；CI 或排程任務用 CLAUDE_CODE_EFFORT_LEVEL 或 --effort，因為它們最高優先。避免在使用者設定檔手寫頂層 effortLevel 然後期待它管到新模型。成本方面，文件只說較低等級在簡單任務上更快更便宜、較高等級在複雜問題上推理更深；官方頁面沒有給各等級的實際花費比，我也沒有數字。