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

modelPickerでできること

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

Claude Code v2.1.242以降が必要です。設定できる場所はユーザー設定・managed設定・--settingsに限られ、プロジェクト設定やローカル設定には反映されません(詳しくは後述)。

設定の書き方

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つです。

replaceBuiltInOptionsをtrueにすると、組み込みのモデル一覧・availableModelsが追加する行・LLMゲートウェイが検出した行・ANTHROPIC_CUSTOM_MODEL_OPTIONの行がすべて隠れ、optionsの行とDefault、現在使用中のモデルの行だけが残ります。false(既定)のままなら、組み込みの一覧に追加する形で末尾に並びますが、組み込みの一覧が既にカバーしているモデルをoptionsに重複して書いた場合、その行はスキップされます。追加モードは「組み込みに無い行だけを足す」設計なので、既存のOpus/Sonnetの行をラベルだけ変えたいならreplaceBuiltInOptions: trueに切り替える必要があります。

行の並び順にも規則があります。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ゲートウェイのモデルディスカバリにあります。replaceBuiltInOptionsをtrueにすると、この自動検出行も隠れる対象に含まれる点は覚えておく必要があります。

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のいずれでも使えます。複数リージョン・複数チームでモデルルーティングを分けたい組織は、サブエージェントのモデル配分設計も合わせて検討する必要があります。

availableModelsとの関係(制限はmodelPickerでは外れない)

modelPickerは一覧の見せ方を変える設定であって、選択できるモデルの範囲を制限する設定ではありません。availableModelsの許可リストはmodelPickerのあとにもう一段チェックされ、次の3通りのいずれかになります。

• Dropped: 組織がアクセス権を持たないモデルなど、Claude Codeが提供できない行は消える
• Grayed out: まだ選べない行は理由付きでグレー表示になる
• No row survives: optionsの行が1つも残らなければ、組み込みの一覧が許可リストで絞られた形で表示される

availableModelsに書いた完全なモデルIDのうち組み込みの行を持たないもの(許可リストで固定した旧バージョンなど)は、ピッカーに単独の行として現れます。ただしmodelPickerが組み込みの一覧を置き換えている場合は出ないので、必要ならoptionsに載せます。

availableModelsに行を足すときは、許可リストのマージ規則にも注意が必要です。ファミリー内の特定モデルID(バージョンプレフィックスや完全なID)を1つでも書くと、そのファミリーのワイルドカード行は無効になります。["sonnet", "claude-sonnet-4-5"]のように書くと、許可されるのはSonnet 4.5系だけになり、他のSonnetモデルは通りません。

modelOverridesとavailableModelsを同時に使うときは、許可リストの判定対象がどちらのIDかを混同しないことが重要です。availableModelsはmodelOverridesで変換した後のプロバイダ固有ID(Bedrockの推論プロファイルARN等)ではなく、変換前のAnthropicモデルIDに対して評価されます。そのためavailableModelsに"opus"とだけ書いておけば、Opusの各バージョンがARNへマッピングされていても許可判定は変わらず機能します。enforceAvailableModelsでDefaultを許可リストに強制したときも、Defaultが解決するIDへのmodelOverridesはmanaged設定からのマッピングだけが適用され、ユーザー設定やプロジェクト設定側のmodelOverridesはDefaultには反映されません。

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

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

この3か所のうち最も優先度の高いものが全体を丸ごと供給します。ユーザー設定とmanaged設定の両方にmodelPickerを書いても、2つのリストが合成されることはなく、優先度の高い側のリストだけが有効になります。配列を連結・重複排除するavailableModelsなどとは挙動が異なるので、両方に書いて「片方が足りない分を補ってくれる」と期待すると、意図しない一覧になります。

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

組織展開でよくあるのは、Claude Code本体のアップグレードより先にBedrock側へ新しいモデルバージョンをデプロイしたい場合です。全員のClaude Codeを一斉に上げなくても、behavesAsで「未知のモデルIDだが挙動は既知のOpusと同じ」と伝えておけば、旧バージョンのユーザーもピッカーからそのモデルを選べます。

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

組織全体に配るときの置き場所

個人の設定として試すだけならユーザー設定(~/.claude/settings.json)に書けます。組織全体へ配るときは、managed設定としてmanaged-settings.jsonファイル・MDMポリシー・claude.aiのアドミンコンソール(server-managed設定)のいずれかで配布します。managed設定は最も優先度が高く、ユーザー側のmodelPickerより常に優先されるので、組織で一元管理したいなら管理者側だけがこのキーを持てば足ります。個々の開発者に~/.claude/settings.jsonを触らせたくない場合は、この置き場所の使い分けを徹底しておく必要があります。

本番へ配る前に手元で確認したいときは、claude --settingsフラグで一時的なJSONファイルを渡して挙動を試せます。managed設定と同じ内容を--settings経由で試してからmanaged-settings.jsonへ昇格させれば、配布前にピッカーの見た目を実機で確認できます。

使い分け早見表

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

1件だけ試験的なモデルIDを追加したいならANTHROPIC_CUSTOM_MODEL_OPTIONで足ります。ラベル付きで複数行を意図した順序に並べたいならmodelPicker、実際に呼び出すIDをバージョンごとに変えたいならmodelOverrides、そもそも選べるモデルを絞りたいならavailableModelsという切り分けです。advisorModelやswitchModelsOnFlagのようにモデル選択に関わる設定は他にもありますが、いずれもmodelPickerとは独立に効き、組み合わせて使えます。

よくあるつまずき

• プロジェクト設定に書いて反映されない: modelPickerはプロジェクト・ローカル設定を読まない。クローンした側で勝手にピッカーを変えられないようにする設計であって、書式ミスではない
• ユーザー設定とmanaged設定の両方に書いて片方が消える: 2つのリストは合成されず、優先度の高い側が丸ごと勝つ。組織のmanaged設定を配布したら、ユーザー設定側のmodelPickerは書かないほうが事故が起きにくい
• replaceBuiltInOptions: trueにして必要な行が消えた: ゲートウェイ検出やAPI経由の追加オプションもまとめて隠れるため、置き換え後に必要な行はoptionsへ明示的に足す
• 新しいモデルなのに行がグレーアウトされる: modelPickerはあくまで表示順の設定で、availableModelsの許可リストによる制限は別途かかる

まとめ

modelPickerはv2.1.242以降、ユーザー設定かmanaged設定にだけ書ける設定です。ラベル付けと並び替えはmodelPicker、実際に呼び出すIDの差し替えはmodelOverrides、選択できる範囲の制限はavailableModelsと役割が分かれています。組織展開では、managed設定にまとめて配置し、ユーザー設定側では触らないようにするとリストの丸ごと上書きに驚かずに済みます。