Claude CodeのmodelPickerで/modelのモデル一覧を組織向けに構成する

modelPickerでできること

modelPickerは、/modelコマンドが開くピッカーの行を、組織が選んだ順序とラベルで差し替える設定キーです。Amazon Bedrockの推論プロファイルARNやMicrosoft Foundryのデプロイ名のような長い文字列がそのままピッカーに出るのを避け、「Opus(本番)」のような名前を並べられます。

Claude Code v2.1.242以降が必要です。1行ごとの表示名や能力宣言は、ピン留めモデルの表示名と対応能力の上書きが扱います。

設定の書き方

modelPickerはoptions配列と、任意のreplaceBuiltInOptionsの2つのフィールドを持つオブジェクトです。

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus(本番)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet(本番)",
        "description": "日常業務向け"
      }
    ]
  }
}

optionsの各行が持てるフィールドは次の4つです。

行はoptionsに書いた順で並びます。ただし、まだ選べないグレーアウトの行だけは一覧の末尾へ移ります。

組み込みの一覧を残すか、置き換えるか

replaceBuiltInOptionsの値で、optionsの行が組み込みの一覧にどう関わるかが決まります。

追加モードは重複行を落とすので、既存のOpusやSonnetの行のラベルだけを変えたい場合は置き換えモードを選びます。置き換えると必要な行まで消えるため、残したいモデルはoptionsへ自分で書き足します。

モデルIDに指定できる値

modelの値は逐語のまま渡されるので、--modelフラグが受け付ける値なら何でも書けます。

• opusのようなエイリアス
• claude-opus-4-8のようなAnthropicモデルID
• Amazon Bedrockの推論プロファイルARN、Google CloudのAgent Platformのバージョン名、Microsoft Foundryのデプロイ名
• LLMゲートウェイが返すモデルID

ゲートウェイ経由なら、CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1でゲートウェイの/v1/modelsから行を自動検出させる手もあります。自動検出とmodelPickerの手動指定は併用でき、検出の解決順はLLMゲートウェイのモデルディスカバリにあります。置き換えモードでは、この自動検出の行も隠れます。

Bedrock/Vertex/Foundryのラベルとルーティングを両立させる

modelPickerが決めるのはピッカーの表示だけです。Claude Codeがプロバイダへ送るIDは変わりません。送るIDを差し替えるのはmodelOverridesの役目です。

{
  "modelPicker": {
    "options": [
      { "model": "claude-opus-4-7", "label": "Opus(本番)" }
    ]
  },
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod"
  }
}

ユーザーには「Opus(本番)」の行が見え、Claude Codeは裏でBedrockの推論プロファイルARNを呼びます。modelOverridesはガバナンス・コスト配分・リージョン別ルーティングのためにバージョンごとのIDを差し替える設定で、Bedrock・Google CloudのAgent Platform・Foundryのいずれでも使えます。リージョンやチームでルーティングを分ける組織は、サブエージェントのモデル配分設計も合わせて検討する余地があります。

ARNや、Foundryのように利用者が名前を決められるデプロイ名は、Claude Codeが知っているモデルとして認識されません。ARNは、modelOverridesがそのARNに対応づけているときだけ認識されます。Foundryのデプロイ名は、対応づけていても認識されません。認識されない行は、labelを付けない限りモデルIDがそのまま出ます。

新しいモデルを旧バージョンのClaude Codeで選べるようにする

behavesAsは、v2.1.257以降で使えるフィールドです。自分のClaude Codeがまだ知らない新しいモデルをmodelに書くとき、claude-opus-4-8のような既知のモデルIDをbehavesAsに指定すると、その既知モデルの機能とエフォート既定値がこの行に適用されます。ラベルと、リクエストで送るモデルIDは変わりません。

Claude Code本体の更新より先に、Bedrock側へ新しいモデルバージョンを展開したい組織では、この指定が役立ちます。全員のClaude Codeを一斉に上げなくても、「未知のIDだが挙動は既知のOpusと同じ」と伝えておけば、旧バージョンのユーザーもピッカーから選べます。

availableModelsとの関係

modelPickerは一覧の見せ方を変える設定で、選べるモデルの範囲を制限する設定ではありません。availableModelsの許可リストはmodelPickerの後にもう一段かかります。ピッカーを出す前に、Claude Codeが行ごとにセッションとの適合も調べます。結果は次の3通りです。

許可リストに完全なモデルIDを書いたとき、そのモデルに専用の行ができるかは、プロバイダで分かれます。

• Anthropic API・Claude Platform on AWS・Claude apps gateway・ANTHROPIC_BASE_URL経由のLLMゲートウェイ: 組み込みの行がないOpus・Sonnet・Haikuの旧バージョンは、専用の行として出る。置き換えモードでは出ない
• Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundry: IDがanthropic.で始まるものを除き、行は作られない。出したいバージョンはmodelPickerのoptionsにも書く

許可リストのマージ規則にも癖があります。ファミリー内の特定モデルIDを1つ書くと、そのファミリーのワイルドカード行は無効になります。バージョンプレフィックスでも完全なIDでも同じです。["sonnet", "claude-sonnet-4-5"]と書いて許可されるのはSonnet 4.5系だけで、ほかのSonnetは通りません。

modelOverridesと併用するときは、許可リストの判定対象がどちらのIDかが肝心です。availableModelsは、modelOverridesで変換した後のARNではなく、変換前のAnthropicモデルIDに対して評価されます。availableModelsに"opus"と書いておけば、Opusの各バージョンがARNへ対応づけられていても、許可判定はそのまま働きます。

enforceAvailableModelsでDefaultまで許可リストに縛った場合、Defaultが解決するIDに効くmodelOverridesはmanaged設定のものだけです。ユーザー設定やプロジェクト設定のmodelOverridesは、Defaultに反映されません。

許可リストの外のモデルを/model <name>で選ぶと、次のメッセージで拒否されます。

Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.

このとき、セッションのモデルは変わりません。

反映されるスコープと注意点

modelPickerが読み込まれるのは、managed設定・--settings・ユーザー設定の3か所だけです。プロジェクト設定とローカル設定では無視されるので、クローンしたリポジトリの設定ファイルでピッカーを書き換えることはできません。

この3か所のうち最も優先度の高いものが、全体を丸ごと供給します。ユーザー設定とmanaged設定の両方に書いても、2つのリストは合成されません。配列設定はmanagedが無ければユーザー・プロジェクト・ローカルの間で連結されますが、modelPickerはmanagedが定義した時点でそのリストだけが効きます。「足りない分をユーザー設定が補ってくれる」という期待は外れます。

書式を誤った行があっても、Claude Codeはその行だけを落として、残りをそのまま反映します。

組織全体に配るまでの手順

個人で試すだけなら、ユーザー設定(~/.claude/settings.json)に書けば足ります。組織へ配るときは、managed設定としてmanaged-settings.jsonファイル・MDMポリシー・claude.aiのアドミンコンソール(server-managed設定)のいずれかで配布します。

Claude Codeを自社アプリに組み込んで動かす場合は例外があります。環境変数CLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定したアプリでは、そのアプリのモデル設定が優先されます。対象はmanaged設定のmodel・fallbackModel・modelPicker・modelOverridesです。managed側のavailableModelsは、アプリが自前の許可リストを渡さない限り有効なままです。

availableModelsとmodelOverridesを組で配るときは、同じmanagedの供給元に両方を入れます。既定では最優先の供給元しか読まれないため、管理コンソールが何かを配っていると、managed設定ファイルに置いた組は無視されます。

使い分け早見表

モデルの見せ方・呼び出し方・許可範囲を扱う設定は複数あり、名前だけでは役割の境目が分かりにくいので、次の表で切り分けます。

試験的なモデルIDを1件足したいだけなら、ANTHROPIC_CUSTOM_MODEL_OPTIONで足ります。advisorModelやswitchModelsOnFlagなど、モデル選択に関わる設定は他にもありますが、modelPickerとは独立に効きます。

よくあるつまずき

• プロジェクト設定に書いたのに反映されない: プロジェクト・ローカル設定は読まれない仕様で、書式ミスではない
• ユーザー設定とmanaged設定の両方に書いて片方が消えた: 優先度の高い側が丸ごと勝つ。managed設定を配ったら、ユーザー設定側は書かない
• 置き換えモードにしたら必要な行が消えた: ゲートウェイ検出やAPI経由の追加オプションも隠れる。必要な行はoptionsへ書き足す
• 行がグレーアウトして選べない: まだ選べない行は理由つきで表示されるので、その理由を読む。availableModelsの許可リスト外のモデルはグレーアウトでなく、ピッカーから消える
• Foundryの行がデプロイ名のまま出る: 認識されない行はlabelを付けない限りモデルIDが出る。labelを書く
• 一部の行だけ消えた: 書式を誤った行は、その行だけが落とされて残りは反映される。落とされた行の書式を見直す
• Bedrockで許可リストに書いたIDの行が出ない: anthropic.始まりでないIDは行が作られないので、modelPickerのoptionsにも書く
• ピッカーで選んだモデルが次回も残る: Enterはユーザー設定のmodelに保存する。今のセッションだけに効かせるならsを使う

sのキー割り当ては、keybindings.jsonのmodelPicker:thisSessionOnlyで変えられます。以前のmodelPicker:setAsDefaultをカスタムしていた場合は、この名前への書き換えが必要です。

まとめ

組織展開で最初に決めるのは、modelPickerをどの供給元に置くかです。最優先の供給元のリストだけが丸ごと効くので、managed設定の1か所にまとめると、意図しない一覧になりにくくなります。