modelSettingsのeffortをモデル別に直接編集する

modelSettingsとは何か

modelSettingsは、settings.jsonの中でモデルごとのeffortレベルを保存するキーです。モデル名をキーに、effortLevelとmaxEffortLevelを値に持つオブジェクトとして書きます。

/effort low・medium・high・xhighをインタラクティブセッションで実行すると、Claude Codeは選んだレベルを使用中のモデルの下にこのキーで自動保存します。VS Code拡張のモデルピッカーにあるeffortスライダーで選んだ場合も同じ場所に書き込まれます。手で直接編集して、保存済みのレベルを変更・削除することもできます。

modelSettingsによるモデル別保存はClaude Code v2.1.251以降で有効です。それより前のバージョンでは、/effortはトップレベルのeffortLevelキーを書き換えていました。手元のバージョンが対応しているかはclaude --versionで確認できます。

effortLevel・modelSettings・maxEffortLevelの違い

3つのキーは似た名前ですが役割が異なります。混同すると、settings.jsonを直接編集したときに意図と違うモデルに設定が効いてしまいます。

表中のUser・Project・Local・Managedは、公式の呼び方でそれぞれ~/.claude/settings.json・.claude/settings.json・.claude/settings.local.json・組織が配布する設定ファイルを指します。

modelSettings配下のeffortLevelは「既定値を決める」キーで、maxEffortLevelは「上限を決める」キーです。前者は/effortや--effortで上書きできますが、後者は/effortで選べる上限そのものを狭めます。

モデル別にeffortの既定値を設定する

設定ファイルを手で編集する場合は、モデルの正式名をキーにしてeffortLevelを書きます。

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

Claude Codeはこのキーをモデルの正式名(claude-opus-5-5など)の下に書き込み、そのモデルのエイリアス・日付サフィックス付き名・[1m]付き名・プロバイダー固有IDも同じエントリーに一致させます。したがってclaude-opus-5-5に設定すれば、Bedrock経由でも同じモデルを指している限り同じeffortLevelが適用されます。

保存したレベルを外側から解除したいときは/effort autoを実行します。使用中のモデルの保存済みレベルだけがクリアされ、他のモデルのエントリーやトップレベルのeffortLevelはそのまま残ります。

モデル別に既定値を分けたくなる典型例は、日常のコーディングにはSonnet系をmediumで使い、難しい設計判断だけOpus系をhighやxhighに上げておくような使い分けです。トップレベルのeffortLevel1つだけでは全モデル共通の値しか持てないため、モデルを切り替えるたびに/effortを打ち直す代わりに、あらかじめmodelSettingsへ両方の値を書いておけば、/modelで切り替えた瞬間にそのモデル用のeffortが自動で適用されます。

優先順位はファイル内とファイル間で別々に決まる

同じsettings.jsonファイル内では、あるモデルに対するmodelSettingsエントリーが、そのファイルのトップレベルeffortLevelより優先されます。

ファイルをまたぐ場合はモデルごとに個別に解決されます。そのモデルにeffortLevelを設定している(トップレベルでもmodelSettingsでも構いません)設定ファイルのうち、後述の優先順位表で最も上にあるものが決定権を持ちます。つまりManaged設定で特定モデルのレベルを固定すると、ユーザー設定で保存した値より優先されます。

--effortはセッション単位でさらにこれらを上書きします。環境変数による上書きと、上限(maxEffortLevel)がどの段階で効くかは後述します。

優先順位表が示す階層は、modelSettingsを含むすべてのキーに共通です。上から順に、この階層のどこで同じモデルへのeffortLevelが設定されているかを見れば、どのファイルが勝つかが分かります。

modelSettingsもこの階層に従うため、チームの共有設定(.claude/settings.json)で特定モデルにeffortLevelを書けば、各メンバーのユーザー設定にある値より優先されます。個人が自分のマシンだけで値を変えたい場合は、.claude/settings.local.jsonに同じモデルのエントリーを追加すれば、共有設定より優先して上書きできます。このsettings.local.jsonはClaude Codeが自動生成した場合はGitの管理対象から外れますが、手で新規作成したときは.gitignoreへの追加を忘れると、個人用のmodelSettingsエントリーをそのままチームの共有設定にコミットしてしまうので注意してください。

組織で上限を配布するときはモデル別maxEffortLevelを使う

maxEffortLevelをManaged設定に置くと組織全体に上限を強制できます。ただし全モデル一律の上限では、特定モデルだけ緩めたい場合に不便です。そこでmodelSettings配下にmaxEffortLevelを書けば、そのモデルだけ別の上限(または上限なしの"max")を設定できます。

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

この例は全モデルをmediumに制限しつつ、Claude Sonnet 4.6だけ上限を解除します。ただしmodelSettingsのモデル別上限は、それを設定した設定ソース内でのみトップレベルの上限を置き換えます。別の設定ソース(たとえばManaged設定)が同じモデルに別の上限をかけていれば、その上限は引き続き適用されます。組織のエフォート上限と衝突した場合は、低い方の値が採用されます。

モデル別maxEffortLevelはClaude Code v2.1.267以降が必要です。このバージョンでmaxEffortLevel自体もトップレベル・modelSettings配下の両方の書式で追加されました。この上限はBedrock・Vertex AI・Foundry経由でモデルを呼び出す場合にも共通で適用されるため、複数のクラウド経由でモデルを使い分けていても組織のポリシーから外れることはありません。上限がxhigh未満のモデルでは、そのモデルでultracodeが使えなくなる点にも注意してください。

/effortコマンドとの使い分け

日常の切り替えは/effortや/modelのeffortスライダーで十分です。セッション内で選んだ値は自動的にmodelSettingsへ保存されるため、通常はファイルを直接編集する必要はありません。

/effort high

modelSettingsを手で編集する場面は主に3つです。1つ目は、複数モデルの既定値をまとめて1回のコミットで整えたいとき。2つ目は、対話セッションを使わないヘッドレス実行や-p実行の前に、恒久的な既定値をリポジトリのプロジェクト設定へ用意しておきたいとき(-p実行での/effort相当の指定はそのセッション限りで、ファイルには保存されません)。3つ目は、Managed設定でモデルごとの上限を組織に配布するときです。

/effortによるモデル別保存の詳しい操作手順はClaude Code effortレベルの使い方と設定、/modelピッカーからの切り替えはClaude Codeの/modelにまとめています。

環境変数はmodelSettingsより後から効く

modelSettingsやeffortLevelを設定ファイルに書いても、環境変数がそれを上書きすることがあります。CLAUDE_CODE_EFFORT_LEVELは--effort・/effort・modelSettings・トップレベルのeffortLevelのすべてより優先されますが、maxEffortLevelの上限はこの環境変数にも適用されます。

CLAUDE_CODE_ALWAYS_ENABLE_EFFORTを1に設定すると、effortパラメーターに対応しているとClaude Codeがまだ認識していないモデルIDにも、常にeffortを送るようになります。LLMゲートウェイやサードパーティプロバイダー経由でカスタムIDのモデルを使う場合に使う設定で、modelSettingsでモデル名を指定してもClaude Codeがそのモデルをeffort対応と認識していなければ値が送られない、というケースを避けられます。ただしeffortパラメーターをAPI側が拒否するモデル(Claude 3系・Sonnet 4.0/4.5・Opus 4.0/4.1・Haiku 4.5)は、この変数を立てても除外されたままです。

Bashツールやフックのサブプロセスからは、実行中のeffortレベルがCLAUDE_EFFORT環境変数(low・medium・high・xhigh・maxのいずれか)として自動的に渡されます。ultracodeは独立したレベルではなくxhighとして報告されます。フックのスクリプト側で、今どのeffortレベルで動いているかをmodelSettingsを読み返さずに判定したいときはこの変数を使います。対話セッション側で同じ情報を見たいときは、/effortを引数なしで実行すると選択メニューが開き、現在保存されているレベルがハイライトされた状態で確認できます。

新しいモデルでは古いeffortLevelが引き継がれない

~/.claude/settings.json(User設定)のトップレベルeffortLevelは、/effortがモデル別保存(modelSettings)に対応する前の古い書式です。この古いキーは、Claude Opus 5・Claude Fable 5.1以前のモデルには今も適用され続けます。

一方でClaude Opus 5.5以降にリリースされたモデルは、このトップレベルの古いeffortLevelを無視します。何もしなければ、そのモデル自身の既定effortから始まり、modelSettingsにそのモデル用のレベルを保存するまでその状態が続きます。Project・Local・Managed設定のトップレベルeffortLevelはこの制限を受けず、すべてのモデルに適用されます。

つまり、以前/effort xhighを一度だけ実行して~/.claude/settings.jsonに古い書式のキーが残っている場合、Opus 5.5へ切り替えたタイミングで既定effortに戻ります。意図した挙動でなければ、Opus 5.5用のmodelSettingsエントリーを明示的に追加してください。

まとめ

modelSettingsはモデルごとのeffort既定値を保存するキーで、v2.1.251以降/effortや/modelのスライダーが自動的に書き込みます。手で編集すれば、複数モデルの既定値を一括管理したり、Managed設定でモデル別の上限(maxEffortLevel、v2.1.267以降)を組織に配布したりできます。トップレベルのeffortLevel・maxEffortLevelと、modelSettings配下の同名キーは役割が違うため、設定ファイルを直接触る前に優先順位の違いを確認してください。

Opus 5.5以降のモデルでeffortが期待通りに効かないときは、まず対象モデルのmodelSettingsエントリーと、Managed設定側の上限の両方を確認するのが近道です。古い書式のトップレベルeffortLevelが新しいモデルに引き継がれない仕様も、原因の切り分けで見落としやすいポイントです。設定ファイルを直接編集したあとは、そのモデルで/effortを実行して現在のレベルを確認すると、設定がどの値で反映されたかを取り違えずに済みます。複数の設定ファイルにまたがって書き換える場合は、どのファイルが優先されるかを先に確認してから編集する順番にすると、意図しない値で上書きされる事故を防げます。