LLMゲートウェイのモデルディスカバリはどう動くか

モデルディスカバリは既定で無効になっている

モデルディスカバリは、Claude Codeが起動時にゲートウェイの/v1/modelsエンドポイントへ問い合わせ、返ってきたモデルを/modelピッカーに追加する機能です。共有のAPIキーを使うゲートウェイでは、鍵がアクセスできる全モデルが全ユーザーに見えてしまうため、既定では無効です。

ゲートウェイが送受信するリクエスト全体の仕様はClaude Code LLM gatewayのプロトコルで扱い、本記事はモデルディスカバリ単体の挙動とデバッグに絞ります。

有効にするには、開発者自身の環境変数か、managed settings経由でCLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1を設定します。~/.claude/settings.jsonのenvブロックに書いても有効になります。

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

対象はAnthropic Messages形式を話すゲートウェイだけです。ANTHROPIC_BASE_URLがゲートウェイを指していても、形式が違えば動きません。組織として一律に有効化するか、開発者の判断に任せるかは、managed settingsを配るかどうかで決まります。

ディスカバリが動かない条件

ディスカバリが実行されないのは、次の2つのどちらかに当てはまるときです。

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICは、条件に入りません。このリクエストはゲートウェイにしか飛ばないためです。ただしv2.1.257より前は、この変数が有効だとディスカバリが更新されず、ピッカーは前回キャッシュした一覧のままでした。古いClaude Codeで「一覧が増えない」場合は、この変数を疑う価値があります。

CLAUDE_CODE_USE_BEDROCK=1でANTHROPIC_BEDROCK_BASE_URLを指す構成では、推論は/model/{model}/invokeという別形式のエンドポイントに送られます。CLAUDE_CODE_USE_VERTEX=1でANTHROPIC_VERTEX_BASE_URLを指すGoogle CloudのAgent Platform(旧Vertex AI)形式も、:rawPredictというサフィックス付きです。どちらもAnthropic Messages形式ではないため、ディスカバリの対象外です。

もう1つ、資格情報が解決できないときもスキップされます。ANTHROPIC_AUTH_TOKENもapiKeyHelperもANTHROPIC_API_KEYも解決できず、ANTHROPIC_CUSTOM_HEADERSだけで認証している環境が典型です。この場合もデバッグログに[gatewayDiscovery] skippedが出ます。

ディスカバリの成否をデバッグログで確認する

claude --debugで起動すると、セッションごとのデバッグログ(~/.claude/debug/<セッションID>.txt)に[gatewayDiscovery]という接頭辞の行が残ります。Claude Codeは初回のディスカバリ成功時にキャッシュしたモデル数を記録し、その後はゲートウェイ側の一覧が変わったときだけ再度記録します。

ログの置き場所を自分で決めたいときは、--debug-file <path>が使えます。v2.1.287のclaude --helpでは「特定のパスにデバッグログを書き出す(暗黙にデバッグモードを有効にする)」という説明で、--debugと合わせて指定する必要はありません。

リクエストは既定3秒でタイムアウトし、リダイレクトは失敗として扱う

リクエストはGET /v1/models?limit=1000で、タイムアウトは既定で3秒です。リダイレクトは無条件で失敗扱いになります。認証ヘッダーがリダイレクト先のホストに漏れる経路を作らないための設計です。応答が遅いゲートウェイや、httpからhttpsへのリダイレクトを挟むだけのゲートウェイでも、この失敗はサイレントに起きます。/v1/modelsは設定したベースURLで直接応答させる必要があります。

起動時に3秒で答えられないゲートウェイには、CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MSでミリ秒単位の待ち時間を指定できます。Claude Code v2.1.269以降の変数で、数字だけを受け付けます。0・負の値・数字以外の書き方は既定の3000のままです。

認証ヘッダーは次の2種類を送ります。解決できなかった側は送りません。両方を送るにはv2.1.248以降が必要で、それより前はANTHROPIC_AUTH_TOKENがあればAuthorizationのみ、なければx-api-keyのみでした。

• Authorization: ANTHROPIC_AUTH_TOKENをベアラートークンとして、無ければapiKeyHelperの戻り値をベアラートークンとして使う
• x-api-key: ANTHROPIC_API_KEYなど解決済みのAPIキー。ヘルパーの値しか無い場合はここにも同じ値が入る

ANTHROPIC_CUSTOM_HEADERSのヘッダーも同じリクエストに乗ります。値が空でないカスタムヘッダーは、同名の組み込みヘッダー(大文字小文字は区別しない)の代わりに送られます。つまりAuthorizationをカスタムヘッダーで上書きしている環境では、ディスカバリにも上書き後の値が届きます。

レスポンスのidをどうフィルターするか

ゲートウェイはdata配列でidを返し、display_nameとdescriptionは任意です。

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Codeはidにclaudeまたはanthropicという文字列を含むエントリだけを残し、大文字小文字は区別しません。vertex_ai/claude-sonnet-4-6やbedrock/anthropic.claude-sonnet-4-5のようなプロバイダー接頭辞付きのIDも通ります。

具体的に4つのIDで考えると分かりやすくなります。claude-opus-4-8とbedrock/anthropic.claude-sonnet-4-5は、文字列のどこかにclaudeかanthropicを含むため残ります。一方gpt-4oと、internal-model-7のような社内命名のIDは除外されます。

フィルターは先頭一致ではなく部分一致です。us-west.claude-sonnet-4-6のようなリージョン接頭辞やclaude-sonnet-4-6-previewのような接尾辞が付いても、claudeが残っていれば通ります。

ピッカーでの表示名・重複統合・キャッシュ

/modelのピッカーでは、ゲートウェイがdisplay_nameを返し、それがidと違うときに表示名として使われます。違わないか無いときは、Claude Codeがidを認識できればモデル名、できなければidをそのまま表示します。たとえばmy-gateway-claude-sonnet-4-6でdisplay_nameが無いエントリは、Sonnet 4.6と表示されます。

各行にはdescriptionが1行に畳まれて表示されます。descriptionが無いエントリだけが「From gateway」と表示される仕様で、v2.1.257より前は、すべての発見エントリが「From gateway」でした。

たとえばsonnetがclaude-sonnet-5-5に解決されている間は、発見されたclaude-sonnet-5-5はsonnet行に畳まれます。発見されたclaude-sonnet-5は、解決先が違うので独自の行になります。

管理者がmodelPickerでreplaceBuiltInOptionsを有効にしていると、発見されたモデルはピッカーから隠れます。ただし、そのセッションが現在使っているモデルの行と「Default」の行は残ります。

managed settingsのavailableModelsは、この統合より手前で効きます。availableModelsに無いモデルは、ゲートウェイが返してもピッカーには追加されません。

結果は~/.claude/cache/gateway-models.json(Windowsは%USERPROFILE%\.claude\cache\gateway-models.json)にキャッシュされ、起動のたびに更新されます。CLAUDE_CONFIG_DIRを設定している環境では、キャッシュもそのディレクトリ配下に置かれます。リクエストが失敗した場合や、ゲートウェイが/v1/modelsを実装していない場合は、前回起動時のキャッシュか組み込みのモデル一覧にフォールバックします。

ディスカバリの挙動が変わったバージョン

Claude apps gatewayでは/v1/modelsを誰が作るか

Claude apps gatewayを使っている場合、この/v1/modelsはgateway.yamlのmodelsブロックから作られます。運用者がモデルIDをキュレーションしてupstream_modelごとにAnthropic API・Bedrock・Foundryの実際のIDへ変換する仕組みで、設定リファレンスで詳しく扱っています。modelsブロックは、米国以外のBedrockリージョンやプロビジョンドスループットのARN、Foundryのデプロイ名を使う場合に必須です。

auto_include_builtin_modelsが既定のtrueのままなら、キュレーションしたモデルに加えて組み込みモデルも/v1/modelsの一覧に載ります。falseにすると、modelsブロックに書いた分だけが公開されます。

手動登録との使い分け

モデルをピッカーに追加する方法は、ディスカバリだけではありません。モデル設定の環境変数で個別に手動登録する方法もあります。

ラベルや並び順だけを組織向けに変えたいなら、modelPickerだけで足ります。

まとめ

最初に確認する点は構成で変わります。Claude apps gatewayなら、auto_include_builtin_modelsとmodelsブロックの要否です。自社ゲートウェイなら、/v1/modelsがリダイレクトなしで3秒以内に答えるかとIDの命名です。

ホスト側の管理を優先させる設定はCLAUDE_CODE_PROVIDER_MANAGED_BY_HOST、ゲートウェイ全体の選び方はLLM gatewayとは、ロールアウトの手順は管理者向けロールアウト手順にあります。