2026年10月31日に出た Claude Code 2.1.316 に、CLAUDE_CODE_SUBAGENT_EFFORT という環境変数が加わりました。
サブエージェントがどの effort で動くかを、親のセッションとは別に決めるための変数です。
この effort は、Claude が 1 回の返答にどれだけ手間をかけるかを決める設定で、API でも Claude Code でも使われています。
段階の意味と既定値、thinking との違い、Claude Code での切り替え方が分かると、「なぜ今日は返事が速いのか」「なぜ費用が増えたのか」にも説明がつきます。
effort とは何か
effort は、Claude が返答に使うトークンの量を、1 つのモデルのまま増やしたり減らしたりする設定です。
Anthropic の公式ドキュメントは、丁寧さとトークンの節約のどちらを取るかを 1 つの値で選べるもの、と説明しています。
効くのは考える部分だけではありません。
- 本文の説明
- ツールの呼び出しと、その引数
- thinking(有効なとき)
返答のトークンすべてに効くので、thinking を使わない場合でも effort は意味を持ちます。
もう 1 つ大事なのは、effort が厳密な上限ではないことです。
ドキュメントには、effort は「振る舞いの合図」であってトークンの予算ではない、と書かれています。
低い段階でも、難しい問題なら Claude は考えます。
同じ問題を、高い段階のときより少なく考える、というのが低い effort の意味です。
5 つの段階と既定値
段階は low・medium・high・xhigh・max の 5 つで、API の Messages API では output_config.effort に名前を入れます。
| 段階 | 向いている使い方(公式の説明の要約) |
|---|---|
| low | 速さと費用を優先する単純な作業。サブエージェントも例に挙がっている |
| medium | 速さ・費用・性能のバランスを取るエージェントの作業 |
| high | 複雑な推論・難しいコーディング・エージェントの作業 |
| xhigh | 30 分を超える長いエージェントやコーディングの作業 |
| max | 費用を気にせず、いちばん深く考えさせたい作業 |
指定しないときは、モデルごとの既定値が使われます。
API の既定は多くのモデルで high ですが、Opus 5.5 と Haiku 5.5 は mediumです。
既定値と同じ値を明示しても、指定しないときと動きは変わりません。
Claude Code の既定は少し違い、Opus 5.5・Sonnet 5.5・Haiku 5.5 が medium、Opus 4.7 が xhigh、それ以外は high です。
Sonnet 5.5 は API では high が既定と書かれているので、API と Claude Code で同じモデルを使っても、何も指定しなければ段階がずれます。
また、すべてのモデルが 5 段階を持つわけではありません。
たとえば Opus 4.6 と Sonnet 4.6 には xhigh が無く、Claude Code で xhigh を選ぶと high として動きます。
段階の物差しはモデルごとに調整されていて、同じ「medium」でもモデルが違えば中身は同じではありません。
thinking との違い
effort とよく混ざるのが thinking の設定です。
公式の整理では、thinking は「答える前に thinking ブロックで考えるかどうか」、effort は「返答全体にどれだけ手間をかけるか」を決めます。
adaptive thinking(考えるかどうかとその量をモデルが選ぶ方式)では、どのくらい頻繁に、どれだけ深く考えるかも effort で変わります。
adaptive は thinking のモードの名前で、effort の値ではありません。
Opus 5.5 では adaptive thinking が常に有効で、切ることができません。
thinking: {"type": "disabled"} を送ると、どの段階でも 400 エラーになります。
そのため Opus 5.5 では、考える量と費用を決める主な手段は effortです。
ツールを使う場面でも違いが出ます。
ドキュメントによると、低い段階では呼び出しをまとめて回数を減らし、前置きなしで動き、終わったあとの報告も短くなります。
高い段階では呼び出しが増え、動く前に計画を説明し、変更の要約やコードのコメントも詳しくなる傾向があります。
thinking の仕組みそのものは、推論モデルの記事で扱いました。
API で指定する
API では、リクエストの output_config に段階の名前を入れます。
# 公式ドキュメントの例から抜粋(ヘッダーの一部を省略)
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"messages": [{"role": "user", "content": "..."}],
"output_config": {"effort": "medium"}
}'
ベータのヘッダーは要らず、対応するモデルならそのまま使えます。
気をつけたいのは、会話の途中で段階を変えるときです。
トップレベルの output_config.effort を次のリクエストで変えると、プロンプトキャッシュが最初からになります。
長い会話でキャッシュに頼っているなら、段階は最初に決めて変えないのが基本です。
Opus 5.5・Sonnet 5.5・Haiku 5.5 などでは、ベータのヘッダー mid-conversation-output-config-2026-07-01 を付けると、メッセージ単位で段階を変えられます。
こちらは中身が空の system メッセージに段階だけを載せる方法で、それより前の部分が変わらないためキャッシュが残ります。
Claude Code で切り替える
Claude Code では、effort をいくつかの場所から指定できます。
/effort(引数なしでスライダー、/effort highのように直接指定も可)/modelのスライダー(左右の矢印キー)- 起動時の
--effort - 環境変数
CLAUDE_CODE_EFFORT_LEVEL - 設定ファイルの
modelSettings(モデルごと)やeffortLevel - スキルやサブエージェントの定義(frontmatter)の
effort
いくつも指定したときは、Claude Code のドキュメントに書かれた順で、先に当てはまったものが使われます。
- 環境変数
CLAUDE_CODE_EFFORT_LEVEL - セッションの中で選んだ段階(
/effortや/model) - 起動時の
--effort - 設定ファイルに保存した段階
- モデルの既定値
環境変数がいちばん強いので、/effort で変えたのに変わらないときは、まずこの変数が設定されていないかを見てください。
max は特別扱いで、環境変数で指定しない限りそのセッションだけに効き、保存されません。
いまの段階は /effort status で確かめられます。
Bash ツールの中では、環境変数 CLAUDE_EFFORT にそのときの段階が入ります。
ultrathink は 1 回だけ段階を上げる
プロンプトのどこかに ultrathink と書くと、セッションの設定を変えずに、その 1 回だけ深く考えさせられます。
2.1.311 以降は、ターミナルで入力した ultrathink が、対応するモデルではその回を xhigh に上げます。
上げられるときは、入力した文字が虹色に光ります。
2.1.316 では、VS Code でも同じく xhigh で動くようになりました。
「think」「think hard」などはキーワードとして扱われず、ふつうの文として渡されます。
同じ版で、ultrathink を無効にする CLAUDE_CODE_DISABLE_ULTRATHINK も加わっています。
サブエージェントの effort
サブエージェントの段階は、これまで定義ファイルの effort か、呼び出しごとの effort で決められました。
どちらも無いときは、親のセッションの段階を引き継いでいました。
Claude Code の CHANGELOG によると、2.1.316 の CLAUDE_CODE_SUBAGENT_EFFORT は、ほかに指定が無いときにサブエージェントが使う段階を決めます。
API のドキュメントは low の使い道としてサブエージェントを挙げているので、調べ物を任せる子だけ段階を下げる、という調整がしやすくなりました。
なお CLAUDE_CODE_EFFORT_LEVEL を設定していると、サブエージェントの定義の effort より環境変数が優先されます。
サブエージェントがトークンをどこで使うかは、別の記事で数えています。
選び方と落とし穴
公式ドキュメントのモデルごとの勧めには、共通する考え方があります。
自分の作業で品質を確かめながら段階を上げ下げし、確かめないまま別の段階に固定しない、ということです。
effort を動かしても足りないときに、4 つのモデルをどの順で上げ下げするかは、モデルの選び方の記事にまとめました。
段階の選び方で、はまりやすい点を挙げます。
- 古いモデルの段階を持ち越さない: Opus 5.5 の medium は、Anthropic の試験で Opus 5 の high と同等以上だったとされます。乗り換えたら medium から試すよう勧められています。
- max は様子を見てから: Claude Code のドキュメントは、max は伸びが小さくなりやすく、考えすぎにもなりやすいと書いています。
- 高い段階では max_tokens を大きく:
max_tokensは thinking と本文を合わせた上限なので、xhigh や max では足りなくなりがちです。 - 返答の長さは effort で決まらないことがある: Opus 5 では、effort を下げても見える返答が短くなるとは限らず、長さはプロンプトで指示するよう書かれています。
Claude Code のドキュメントによると、Opus 5.5 と Fable 5.1 の試験では、高い段階ほど境目のケースを多く試し、答える前の確認も増えました。
低い段階では最初のたたき台が早く返るので、1 回ごとに結果を見て指示を足す作業に向いています。
段階を上げるか下げるかは、「自分がどれだけ途中で口を出すか」で考えると決めやすくなります。
最後に
effort は、Claude が返答全体にかける手間を low から max の 5 段階で決める設定で、考える量だけでなくツールの呼び出し方や説明の長さにも効きます。
既定値はモデルと製品で違い、Opus 5.5 は API でも Claude Code でも medium です。
Claude Code では環境変数がいちばん強く、ultrathink は 1 回だけ、CLAUDE_CODE_SUBAGENT_EFFORT はサブエージェントだけを動かします。
まず既定値で使い、自分の作業で確かめながら 1 段ずつ動かすのが、費用と品質の両方を外さない近道です。
以上です。












コメントを残す