Claude CodeのadvisorModelでAdvisorの既定モデルを指定する

advisorModelとは何か

advisorModel は、Claude Codeがサーバー側のadvisorツールを呼ぶときに、どのモデルへ相談するかを保存する設定キーです。キーが無い(unset)状態が既定で、その場合advisorはオフです。

値は文字列で、"fable" "opus" "sonnet" のエイリアスか、"claude-opus-5-5" のようなフルのモデルIDを受け付けます。エイリアスはClaude Codeのリリースごとに更新される、そのモデルファミリーの既定バージョンに解決されます。

{
  "advisorModel": "opus"
}

advisorにはメインモデル以上の能力が要ります。メインモデルが対応しないadvisorは、ピッカーでも手書きでも保存されます。保存は通るので、ファイルは正常に見えたまま、advisorだけが付きません。/model で対応するメインモデルに切り替えると有効になります。

このキーは、advisorが提供されない環境でも書き込めます。Amazon BedrockやClaude Platform on AWSではadvisorという仕組みが使えず、値を入れても効果がありません。"fable" にはFableアクセス権も要ります。Advisor unavailable と出る条件はAdvisor unavailableになる条件に、Fable 5のadvisor固有の経緯はFable 5のadvisorがunavailableになる原因と対処法にあります。

3つの設定手段はどう使い分けるか

advisorを有効にする入口は3つあり、保存先と効く期間が違います。

ピッカーで選んだのに効かないとき

引数なしで /advisor を実行すると、現在の選択・使えるadvisorの一覧・「No advisor」を並べたピッカーが開きます。モデルを直接渡すこともできます。

/advisor opus

選ぶと Advisor set to に続けてモデル名が表示され、その値が advisorModel としてユーザー設定へ書き込まれます。

例外が1つあります。Remote Controlのクライアントから選んだとき、またはリモートワーカーに接続したセッションで選んだときは、選択がそのセッションだけに適用され、advisorModel は変わりません。設定ファイルに反映されていないのは仕様どおりです。

ターミナルの対話ピッカーが無い面(-p の非対話モード、Agent SDK、デスクトップアプリ、Remote Control)でも /advisor は動きます。Claude Code v2.1.260以降が必要です。それらの面では、引数なしの実行は現在値と使えるエイリアスを表示するだけです。/advisor <model> で設定、/advisor off で解除します。

Fableをadvisorに選ぶときは、プランによってusage creditsへの課金同意が別途必要です。同意前に /advisor fable を実行しても何も保存されず、/model fable の実行を促す案内が出ます。

上位の設定ファイルの値が使われ続ける

書き込み先にも罠があります。advisorModel は管理者設定・プロジェクト設定(共有・ローカル)・ユーザー設定のどれにも書けます。優先順位は managed-settings.json が最も強く、次に .claude/settings.local.json、.claude/settings.json、最後に ~/.claude/settings.json です。

/advisor ピッカーが書くのは一番弱いユーザー設定だけなので、共有やローカルの設定に別の値が手書きされていると、ピッカーで選び直しても上位ファイルの値が使われ続けます。

どの階層が読み込まれているかは、Claude Code内で /status を実行すると確認できます。Statusタブの Setting sources の行に、そのセッションで読み込んだ設定ファイルが並びます。ただし分かるのは読み込んだファイルまでで、advisorModel をどのファイルの値が決めたかは表示されません。

保存できても付かないadvisorの組み合わせ

advisorはメインモデル以上の能力が条件で、組み合わせごとに扱いが2通りに分かれます。

後者は静かに無効化される型です。受け入れられるadvisorを /advisor で選び直したうえで、/clear か /compact を実行するか新しいセッションを始めるまで戻りません。拒否済みの会話では、/model でモデルを切り替えても戻りません。メインモデル別に受け入れられるadvisorは次のとおりです。

settings.jsonに書いたのに効かないとき

設定リファレンスには「通常このキーは手で編集しない」とあります。ピッカーは使えるモデルの一覧から選ぶので誤字が入りませんが、手書きでは何でも保存されます。

• 綴りの違うモデルIDも保存できます。Claude Codeが認識しないモデルは、advisorとして付けられません
• 組織の許可リスト(availableModels)が除外するモデルを書いても保存はされますが、Claude Codeはそのadvisorを呼びません
• ピッカーでは保存されないFableも、手書きなら "advisorModel": "fable" で保存されます。ただしリクエストは同意を済ませるまでadvisorなしで送られ、対話セッションでは /model fable を案内する通知が出ます

起動時にエラーで止まるとき

--advisor は、条件が合わないと起動が止まります。次のいずれかで、Claude Codeはエラーで終了します。

• セッションのメインモデルがadvisorに対応していない
• 指定したモデル(Haikuなど)がadvisorになれない
• 組織の availableModels が指定モデルを除外している
• Fableを指定したのに、usage creditsの同意が済んでいない

バックグラウンドセッションだけは例外で、終了せずadvisorなしで始まります。スクリプトに --advisor を組み込むときは、この起動時エラーを織り込んでおく必要があります。

Claude Codeのバージョンは手元ではv2.1.285で確認しました。claude --help の一覧に --advisor は出ません。公式ドキュメントも「一覧に載せていない」と書いており、--help でフラグを探しても見つからないのは想定どおりです。設定の読み込み元を絞る --setting-sources と、追加の設定を渡す --settings は、一覧に出ます。

そもそもadvisorが動かない環境

設定手段と打ち消し手段を強い順に並べると、次のようになります。

CLAUDE_CODE_DISABLE_ADVISOR_TOOL を設定すると /advisor が使えなくなり、advisorModel は無視されます。--advisor フラグは受け付けられるものの効果はありません。フラグを渡している既存のスクリプトがエラーにならないための挙動です。

値を書いた(あるいはピッカーで選んだ)のにadvisorが呼ばれないときは、次の順で確認します。

advisorが呼ばれたかの見分け方

呼ばれた場合は、トランスクリプトに Advising の行が出ます。結果は3通りで、Reviewed は助言を得られた状態、Declined は Advisor declined to advise on this request という行、Advisor unavailable (<error_code>) はadvisorの呼び出し自体が失敗した状態です。助言の本文は Ctrl+O で読めます。

Sub-agentsは親セッションの advisorModel を引き継ぎ、自分のモデルに対して同じ組み合わせ判定を受けます。親では成立していても、Sub-agentのモデルが弱ければ、そのSub-agentだけadvisorが外れます。逆に、親のメインでrejectedになった組み合わせでも、Sub-agent自身のモデルが条件を満たせば使える場合があります。

似た設定との違い

モデルの使い分けを設定で決める仕組みは、advisor以外にもあります。opusplanはplan modeだけOpusにする設定です。fallbackModelは強さではなく可用性、つまり過負荷などで使えないときの切り替え先を決める点が違います。

効くタイミングが違います。opusplanはplan modeの間、Sub-agentに model を指定した場合は委譲した作業の全体、/model は次のリクエストからです。advisorだけは、Claude自身が判断の節目で呼びます。呼ぶ回数の上限や強制の設定はなく、増やしたいときは「進める前にadvisorに相談して」のように依頼文で頼みます。

まとめ

ピッカーで選び直しても変わらないときは、ユーザー設定ではなく、上位のプロジェクト設定や管理者設定に別の値が入っていないかを先に疑います。ファイルに書いたのに動かないときは、誤字と、受け入れ表の組み合わせを確認します。