Claude Code effortレベルの使い方と設定
effortレベルの既定値はモデルで異なり、保存先と優先順位も決まっています。Enterとsの違い、フォールバック時の扱い、ultracodeとの区別を解説します。
effortレベルは、Claude Codeがタスクごとにどれだけ深く推論するかを決める設定です。low / medium / high / xhigh / maxの5段階があり、使えるレベルと既定値はモデルによって異なります。既定はhighが基本ですが、Opus 5.5とSonnet 5.5はmedium、Opus 4.7はxhighです。ultracodeはeffortレベルではなく、動的ワークフローを有効にする別の設定です。
effortレベルは何を制御するか
effortレベルが制御するのは、adaptive reasoning(各ステップでモデルが考えるかどうかと、どれだけ考えるかをタスクの複雑さに応じて判断させる仕組み)の深さです。低いeffortは単純なタスクを高速・低コストにこなし、高いeffortは複雑な問題に深い推論を割り当てます。これが効くのはadaptive reasoning対応モデルの場合で、extended thinking専用モデルではeffortを上げても深さが変わりません。
使えるレベルはモデルごとに決まっています。
| モデル | 使えるレベル |
|---|---|
| Fable 5.1、Fable 5 | 使えるレベルlow / medium / high / xhigh / max |
| Opus 5.5、Sonnet 5.5、Opus 5、Sonnet 5、Opus 4.8、Opus 4.7 | 使えるレベルlow / medium / high / xhigh / max |
| Opus 4.6、Sonnet 4.6 | 使えるレベルlow / medium / high / max(xhighなし) |
対応していないレベルを指定すると、Claude Codeは指定値以下でモデルが対応する最も高いレベルで動きます。Opus 4.6にxhighを指定するとhighになります。表にないモデルはeffort自体に対応しません。
既定値はモデルごとに違う
既定のeffortは、対応するモデルの多くでhighです。例外は2つあります。
- Opus 5.5とSonnet 5.5は
medium - Opus 4.7は
xhigh(Opus 4.7 xhighの挙動とコスト試算で詳しく扱っています)
Claude Codeを使わずAPIを直接呼ぶ場合は、effortを省略したときの既定がモデルによって変わります。Opus 5.5はmedium、Sonnet 5.5を含む他のモデルはhighです。Sonnet 5.5のmediumはClaude Code側の既定です。
Opus 5.5は、Opus 5の既定highより一段低いmediumから始まります。Anthropicのテストでは、Opus 5.5のmediumはコーディングと知識労働の評価でOpus 5のhighと同等以上でした。同じレベル名でもOpus 5.5のほうが1ターンで多く考える傾向があるため、Opus 5から移るときは前のレベルを持ち越さずmediumから試す、と案内されています。effortの尺度はモデルごとに較正されており、high同士を比べても内部の推論量は同じではありません。
自分のセッションで今何が効いているかは、セッションヘッダーのモデル名の横に「with low effort」のように出ます。/effort statusでも確認できます。
どの設定が勝つか
effortの決まり方は、上から順に最初に当てはまるものが採用されます。
effortレベルが決まる順番
- 1
明示的な選択
CLAUDE_CODE_EFFORT_LEVEL環境変数、--effortでの起動、セッション中の/effort。環境変数は--effortと/effortにも勝ちます。 - 2
保存済みの設定
/effortや/modelで保存したモデル別のレベル(modelSettings)と、effortLevelキー。 - 3
モデルの既定値
モデルの既定値(前節のとおり)。組織が組織既定モデルに既定effortを設定していれば、そのモデルではそれが既定になります。
SkillやSubagentのfrontmatterのeffortは、そのSkillやSubagentが動いている間だけセッションのレベルを上書きします。環境変数は上書きできず、maxEffortLevelや組織の上限も超えられません。Skillの本文では${CLAUDE_EFFORT}で現在のレベルを読めるので、レベルに応じて指示を切り替えられます。frontmatterの値はlow / medium / high / xhigh / maxで、使える範囲はモデルに依存します。実行中のSubagentのモデルは/tasksで確認でき、frontmatterにeffortがあればその行に併記されます(v2.1.242以降)。frontmatterで設定できる項目全体はClaude Code Sub-agents完全ガイドにあります。
Enterとsで保存の範囲が変わる
インタラクティブなセッションでlow / medium / high / xhighを選ぶとき、確定の仕方で効く期間が変わります。
effortを確定するキーの違い
Enter(または/effortにレベル名を続ける)
そのモデルの既定として保存され、以後のセッションでも使われます。保存先はユーザー設定のmodelSettingsで、モデルごとに別々のレベルを持てます。
s
/effortのスライダーまたは/modelピッカーでsを押すと、今のセッションにだけ適用されます。v2.1.257以降です。
maxは例外で、CLAUDE_CODE_EFFORT_LEVELで設定しない限り常に現在のセッション限りです。-pの非対話実行、リモートワーカーに接続したセッション、Agent SDKでは、/effortもそのセッション限りになります。CIやバッチでレベルを確実に決めたいときは、起動コマンドに--effortを入れます。/effortが表示するメッセージで、保存されたのかセッション限りだったのかが分かります。
古いeffortLevelキーの扱い
v2.1.251より前は、/effortが設定ファイルの最上位のeffortLevelを書いていました。今はモデル別にmodelSettingsへ保存します。ユーザー設定ファイルに残っている最上位のeffortLevelは、Opus 5、Fable 5.1、それ以前のモデルでは従来どおり効きます。一方Opus 5.5とそれ以降のモデルでは無視され、/effortか/modelピッカーで保存するまでモデル自身の既定値から始まります。プロジェクト・ローカル・管理設定と--settingsに書いた最上位のeffortLevelは、全モデルに効きます。
同じ設定ファイルの中ではモデル別の保存値が優先され、ファイルをまたぐ場合は優先度の高い設定ファイルが勝ちます。管理設定のeffortLevelはユーザーが保存した値より強い、ということです。書き方はmodelSettingsのeffortをモデル別に直接編集するにあります。
レベルごとの向き不向き
各レベルはトークン消費と能力のトレードオフで、既定値はほとんどのコーディングタスクに合うよう選ばれています。
| レベル | 向いている場面 |
|---|---|
| low | 向いている場面結果を1つずつ確認しながら進める、ブレインストーミング・最初のたたき台・名前の変更のような小さな変更 |
| medium | 向いている場面範囲が明確な日常の開発(新機能の実装など)。Opus 5.5とSonnet 5.5の既定値。他のモデルではコストを抑えたい作業向け |
| high | 向いている場面検証が重要、またはエッジケースが出やすい作業(既存コードベースのバグ修正など) |
| xhigh | 向いている場面より深い推論をトークン消費増と引き換えに得る。Opus 4.7の既定値 |
| max | 向いている場面セキュリティ脆弱性の探索など、手を離して任せたい難題。過剰思考になりやすく、広く採用する前に検証が必要 |
Opus 5.5とFable 5.1のテストでは、高いレベルほどエッジケースを多く試し、答える前に自分の作業を多く検証しました。同時に、自分で下す判断も増えました。低いレベルは出発点を早く返すので、結果を見て次の指示を出す進め方に合います。ベンチマークの失敗内訳やタスク別の実例は、Terminal-Bench 3.0とeffortの関係で読み解いています。
ultracodeはeffortレベルではない
/effortのスライダーにはultracodeのトグルもありますが、これはClaude Code独自の設定で、effortレベルではありません。有効にすると、Claude Codeがまとまった規模のタスクごとに動的ワークフローを組み立てます。effortはそのセッションの段のままです。v2.1.284より前は、オンにするとxhighに固定され、別のレベルを選ぶとオフになっていました。有効化の入口と使い分けはClaude Codeのultracode設定にあります。
ultracodeを有効にする3つの入口
/effort
/effort ultracodeでオン、/effort ultracode offでオフ。スライダーではTabでトグルを切り替えてEnterで適用します。現在のセッションのみに効きます。--effortフラグ
claude --effort ultracodeで起動すると、xhighのeffortとultracode有効の状態で始まります。xhighのeffortも設定されるのは、このフラグとAgent SDKのeffortLevel: "ultracode"のときだけです。ultracode設定
設定ファイルや
--settings、Agent SDKの制御リクエストで"ultracode": trueを渡します。
--effort ultracodeにはv2.1.203以降が必要で、それより前はUnknown --effort value 'ultracode'と表示されて既定のeffortで始まっていました。永続化されるeffortLevelとCLAUDE_CODE_EFFORT_LEVELはultracodeを受け付けません。環境変数や組織の上限がレベルを決めている場合、ultracodeはそのレベルのままオンになります。ワークフローが無効化されている環境やxhighに対応しないモデルでは、--effort ultracodeはultracodeをオフのまま、モデルと上限が許す最も高いレベル(xhighまで)で始まります。
実機のv2.1.287でclaude --helpを見ると、--effortの説明は次のように出ます。
claude --help | grep -A1 -- "--effort" --effort <level> Effort level for the current session
(low, medium, high, xhigh, max)ヘルプの選択肢にultracodeは並びません。公式のCLIリファレンスではultracodeも指定できる値として載っており、ヘルプの一覧と受け付ける値が一致しない点には注意が必要です。
組織による上限
組織はeffortの上限を2つの方法で設けられます。Claude Enterpriseでは、管理者がカスタムロールごとに、モデル別の上限を設定できます(v2.1.195以降)。プランやプロバイダー(Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryを含む)を問わず使えるのは、管理設定のmaxEffortLevelです(v2.1.267以降)。両方が当たるモデルでは低いほうが採用されます。
上限を超えるレベルは/effortのピッカーに出ません。--effortや/effortで上限より高いレベルを指定すると、上限のレベルで動きます。インタラクティブなセッションと平文の--printでは警告が出ますが、jsonやstream-json出力、バックグラウンドエージェントでは黙って切り詰められます。ロールが複数あってモデルが重なる場合は、最も緩い上限が採用されます。
モデルの自動フォールバックとeffort
Claude Codeが自動でフォールバックモデルに切り替えたときは、そのモデルの既定ではなく、問題のあったリクエストが動いていたeffortが引き継がれます。例として、既定のmediumで動いていたOpus 5.5がOpus 4.8にフォールバックしてもmediumのままです(Opus 4.8の既定はhigh)。
引き継ぎが止まるのは次の場合です。
- 設定ファイルや組織の既定に、フォールバック先モデルで効くレベルがある
- 自分でeffortを選び直した、
/modelでモデルを選んだ、セッションを再開した - Skillの
effortが問題のリクエストに設定されていた(そのターンにだけ効き、以降のターンは優先順位どおりのレベルに戻ります)
effortを変えるとキャッシュはどうなるか
多くのモデルでは、effortレベルごとにプロンプトキャッシュが別になります。会話の途中で変えると、次のリクエストは履歴全体をキャッシュなしで読み直すため、キャッシュが温まっている間はClaude Codeが確認を求めます。
Opus 5.5・Sonnet 5.5・Fable 5.1をAPIキーまたはClaudeサブスクリプションで使う場合は、effortを変えてもキャッシュが保たれ、確認なしで新しいレベルが適用されます。Bedrock、Google CloudのAgent Platform、Claude apps gateway、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定した環境、HIPAA構成の組織には当てはまりません。Fable 5.1でキャッシュが保たれるのはv2.1.260以降です。
APIを直接使う場合は、会話の途中のメッセージにoutput_configでeffortを書きます(ベータ、ヘッダーmid-conversation-output-config-2026-07-01)。Fable 5.1・Opus 5.5・Opus 5・Sonnet 5.5なら、キャッシュを保ったままレベルを変えられます。リクエスト最上位のeffortを変えるとキャッシュは作り直しです。
固定思考量モードと思考のオン・オフ
Fable 5・Sonnet 5・Opus 4.7以降のモデルは常にadaptive reasoningで動き、effortレベルが推論量を決める主な手段になります。Opus 4.6とSonnet 4.6だけは、CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1で固定の思考予算に戻せます。その場合の思考量はMAX_THINKING_TOKENSで決まり、effortによる調整とは別の運用です。
思考そのものを切る操作とeffortの組み合わせにも制約があります。Opus 5.5、Sonnet 5.5、Fableモデルでは思考をオフにできません。/configの行とセッションのトグルはThinking can't be turned offと表示し、MAX_THINKING_TOKENS=0を保存していても効きません。それ以外のモデルで思考をオフにしたままxhigh以上で動かすと、次のエラーになることがあります。
API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)Anthropic APIでは、この組み合わせを受け付けないと分かっているモデル(Opus 5など)に対して、Claude Codeがxhigh以上の代わりにhighを送ります。
Anthropic APIを直接使う場合の制約も、モデルごとに違います。
- Opus 5.5は、
thinking: {"type": "disabled"}を送るとどのeffortでも400エラーになります - Opus 5は、
xhighかmaxで思考を無効にすると400エラーになります - Sonnet 5.5は、思考を切る代わりに
thinking: {"type": "between_tools"}を送ります。xhighかmaxでこれを送ると400エラーになります
思考の頻度が想定と違うときは、プロンプトやCLAUDE.mdで「もっと考えて」「即答して」と直接書くと、そのeffort設定の範囲内でモデルが応答を調整します。
よくあるつまずき
xhighを指定したのに反映されない: Opus 4.6・Sonnet 4.6はxhighに対応せず、highで動きます。上限がxhigh未満に設定されている場合も同じです- Opus 5.5に
effortLevelを書いたのにmediumで始まる: ユーザー設定の最上位effortLevelはOpus 5.5以降で無視されます。/effortで保存するか、プロジェクト設定側に書きます ultracodeを設定ファイルのeffortLevelに書いてエラーになる:effortLevelはultracodeを受け付けません。有効化は"ultracode": trueか/effort ultracodeですmaxが次のセッションで消えている:maxはCLAUDE_CODE_EFFORT_LEVELで設定しない限りセッション限りです--effortで指定したのに環境変数の値で動く:CLAUDE_CODE_EFFORT_LEVELが--effortより優先されます。値をautoにすればモデルの既定に戻ります
よくある質問
ultrathinkとeffortレベルは同じものですか
別物です。プロンプトのどこかにultrathinkと書くと、そのターンだけ深い推論を要求できます。Claude Codeがキーワードとして認識し、コンテキスト内に指示を足す仕組みで、APIに送られるeffortレベル自体は変わりません。thinkやthink hardのような言い回しはキーワードとして扱われず、通常のプロンプトの一部です。
まとめ
キャッシュが保たれる環境(APIキーやサブスクリプションのOpus 5.5・Sonnet 5.5・Fable 5.1)では、途中でレベルを変えても履歴の読み直しは起きません。Bedrockなどでは変更のたびに読み直すので、レベルは最初に決めておくほうが安くつきます。