Claude Code Routerでモデルを別プロバイダーへ振り分ける設定と注意点

Claude Code Router(以下CCR)は、Claude Codeの前に置くローカルのモデルゲートウェイです。Claude Codeが送るリクエストを一度受け取り、設定した規則に従ってOpenRouterやDeepSeekなど別のプロバイダーへ転送します。Claude Codeの設定ファイルを何度も書き換えずに、使うモデルを切り替えられるのが売りです。

注意点が1つあります。Anthropicは、ゲートウェイ経由でClaude Codeを非Claudeモデルに向ける使い方をサポートしていません。CCRの中心機能はまさにプロバイダーの振り分けなので、導入前にこの線引きを知っておく必要があります。ここではCCRの入れ方と規則の書き方を追い、Claude Code標準のゲートウェイ方式とどこが違うかを見ていきます。

CCRとは何か — Claude Code標準のゲートウェイとの違い

CCRは、コーディングエージェント向けのローカルなモデルゲートウェイ兼コントロールプレーンです。リポジトリの説明によれば、Claude Code、Codex、Grok CLI、Kimi CLI、OpenCodeなど複数のエージェントに、1つの安定したローカルエンドポイントを提供します。プロバイダー、モデル、アカウント、ルーティング規則は、その裏側で1か所にまとめて管理します。

対応するAPI形式は、OpenAI Chat / Responses、Anthropic Messages、Gemini Generate Content / Interactionsです。接続先としては、OpenRouter、DeepSeek、SiliconFlow、Moonshot、Mistral、Z.AIなどのプリセットがあり、互換APIなら自前のエンドポイントも追加できます。

Claude Codeには、組織向けのゲートウェイの仕組みが別にあります。両者は同じ「Claude Codeとプロバイダーの間に置くプロキシ」ですが、目的が違います。

非Claudeモデルがサポート対象外なのは、ゲートウェイの種類を問いません。表の最終行は他社ゲートウェイ全般の話です。Claude Codeはリリースごとに機能を足していくため、それを転送しないゲートウェイでは、対応する機能が壊れます。CCRを使うときも、同じ前提で見ておく必要があります。

標準側の全体像はClaude Code LLM gatewayとは — 選び方と全体設計に、互換性の条件はClaude CodeのLLMゲートウェイ互換性にまとめています。

CCRを導入して最初の1リクエストを通す

配布形態は3つあります。リポジトリはデスクトップアプリを推奨しており、npm CLIとDockerも用意されています。

CLI版はNode.js 22以上が必要です。インストールから管理画面の起動までは次の2行です。

npm install -g @musistudio/claude-code-router
ccr ui

起動後は、管理画面で次の順に設定します。手順はデスクトップ版もCLI版も共通です。

1. 「Providers」で「Add Provider」を押し、プリセットか独自エンドポイントを選んでAPIキーを入れる
2. キーとエンドポイントを入れると、CCRが対応プロトコルとモデルを自動検出する。誤検出なら詳細設定で手動指定する
3. 「Check Connection」で実際にリクエストを送り、エンドポイント・キー・プロトコル・モデルが通ることを確かめる
4. 「Server」で「Start」を押す。ローカルゲートウェイは既定で127.0.0.1:3456で待ち受ける
5. 「Agent Config」で「Claude Code」を選び、モデル・小型高速モデル(small fast model)・設定ファイルを指定して「Apply」を押す
6. CCRの「Open Agent」からClaude Codeを起動し、1回だけ送信して「Logs」に記録されるか見る

「Check Connection」は実リクエストを送ります。確認対象のモデルを必要な分だけ選ぶと、無駄な課金を避けられます。

試用中は、適用範囲を「Only opened from CCR」にする案内がCCRのドキュメントにあります。CCRから起動したエージェントだけが影響を受けるので、普段のClaude Codeの設定が汚れません。安定してから「System default」に広げます。

環境変数で自分でつなぐ場合に確認すること

Agent Configの「Apply」が何を書き込むかは、CCRのドキュメントに環境変数名までは載っていません。そこでここでは、Claude Code側のゲートウェイ接続手順を使って接続を確かめる方法を示します。CCR側のゲートウェイ(http://127.0.0.1:3456)に向ける場合の形は、Claude Codeのドキュメントの例に当てはめた次のようになります。

export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
export ANTHROPIC_AUTH_TOKEN=<CCRで発行したキー、または任意の文字列>
claude

これは例示であり、CCRがこの変数の組み合わせをそのまま受け付けるかは、導入したバージョンの設定画面で確かめる前提の書き方です。CCRには、有効期限とローカルの回数・トークン上限を持てる「CCRクライアントキー」があります。認証を有効にしている場合は、そのキーを渡す必要があります。

つながったかどうかは、Claude Codeの/statusで見ます。見る場所は2か所です。

• StatusタブのAnthropic base URL行: ゲートウェイのアドレスが出ていれば、リクエストはそこへ向かっている。行が無ければ変数がセッションに届いていない
• Auth tokenかAPI keyの行: 設定した変数名が出ていれば、ゲートウェイ用の認証情報が有効。保存済みのclaude.aiログインのままではない

設定ファイルのenvブロックと、シェルのexportの両方に同じ変数があるときは、設定ファイルの値が優先されます。Agent Configが設定ファイルを書き換える仕組みだと、シェルでexportした値が効かず、戸惑いやすい点です。

また、ANTHROPIC_BASE_URLだけを設定し、ゲートウェイ用の認証情報を設定しない場合、保存済みのclaude.aiログインが有効な認証情報のままです。リクエストの宛先はゲートウェイに変わりますが、課金と利用上限はサブスクリプション側のものが適用されます。CCR経由で別プロバイダーを使うつもりなら、この状態では意図とずれます。変数の優先順位と認証の細部は、ANTHROPIC_BASE_URLでAPIエンドポイントを切り替えるにあります。

ルーティング規則 — 1リクエストごとにモデルを振り分ける

CCRの中核は「Routing」ページです。振り分けは3層に分かれます。

Claude Code向けの組み込みルート

組み込みルートは、Claude Codeからのリクエストを検知します。クライアントがCCRの認識できるモデルを選んでいない場合に限り、メインのリクエストをAgent Configで選んだモデルへ送ります。

ここで見落としやすいのが優先順位です。CCRが認識できるモデルをClaude Code側で明示すると、そちらが優先されます。Agent Configのモデルは、クライアントのモデルが未指定か未認識のときの既定値にすぎません。Agent Configのモデルを設定していなければ、組み込みルートは働きません。

CCRはさらに、Claude Codeが注入するx-anthropic-billing-headerの先頭のシステムメッセージを自動で取り除きます。課金補助のメッセージが後続のルーティング判断に影響しないようにするためです。

条件つきのカスタム規則

カスタム規則は、リスト順に評価されます。最初に有効かつ条件に合致した規則が、リクエストを書き換えます。順序は上下ボタンで入れ替えられ、「Status」を切れば規則を消さずに無効化できます。

規則は次の要素で組み立てます。

条件で使える演算子は、==・!=、大小比較、starts with、contains、contains deep、not containsです。messagesやtoolsのような入れ子の配列を調べるなら、位置を固定しないcontains deepのほうが頑健だと説明されています。

書き換えの基本形は、request.body.modelに対する「Set」です。値にはprovider/modelの形のモデルセレクタを入れます。たとえば、ユーザーメッセージに特定の語が入ったときだけ別モデルへ回す、といった規則が1行で書けます。

条件を1つでは表せない場合は、ルールの種類を「Node.js script」にします。複数フィールドをまたぐ判断や段階的なロールアウト、外部のポリシー参照が向く場面です。ドキュメントの最小例は次のとおりです。

if (input.body.model !== "Provider/original-model") {
  return null;
}
return {
  model: "Provider/target-model"
};

スクリプトは非同期関数の本体として書き、input・api・returnを直接使います。CommonJSやESモジュールの形式で書いてはいけません。例外・タイムアウト・不正な結果は、すべて「フェイルオープン」で扱われます。診断が記録されたうえで、次の規則の評価に進みます。

スクリプトの実行にはいくつかの上限があります。1つのスクリプトファイルは最大5MiB、タイムアウトは10〜30000ミリ秒(既定は2000ミリ秒)です。同じ規則が60秒以内に3回失敗すると、30秒間そのサーキットブレーカーが開きます。スクリプトは実行環境から隔離されますが、CCRプロセスが持つネットワーク・ファイル・環境変数へのアクセスは引き継ぎます。信頼できるスクリプトだけを動かす前提です。

サブエージェントごとのモデル自動選択

Claude CodeのAgent・Task・Workflowが追加で投げるリクエストは、タグの注入で別モデルに振り分けられます。仕組みは次のとおりです。

1. メインのリクエストが組み込みルートに合致すると、CCRがツール一覧を確認する
2. 「Models」ページで説明(Description)を書いたモデルが1つでもあれば、モデル一覧と説明をAgent/Taskツールの説明文に注入する
3. Claude Codeがサブエージェントを呼ぶとき、プロンプトの先頭に<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>というタグが付く
4. そのリクエストがCCRに届くと、タグを取り除き、指定されたモデルへ送る

モデルの選択を担うのはタグだけです。x-claude-code-agent-idのようなヘッダーは、観測の助けにはなっても、モデルの選択には使われません。

説明を1つも書かなければ、この機構は有効になりません。説明は、そのモデルが得意な仕事を軸に書きます。ドキュメントの例では、低コストの高速モデルに「コード検索・ファイルの仕分け・要約・小さな編集向き」と書いています。推論の強いモデルには「大規模な設計分析やリスクの高いレビュー向き」、長いコンテキストのモデルには「大きなログやリポジトリ規模の情報収集向き」と書く形です。

ここは、Claude Code本体の機能ではなくCCRのプロンプト注入で動く点を押さえてください。サブエージェントへの指示がCCRの文面に影響されるため、Claude Codeの更新でツールの説明文が変わると、挙動が変わる余地があります。

フォールバックとリトライで止まらない構成にする

失敗時の挙動は、規則ごとの「On failure」と、Routingページ上部の「Default on failure」の2段で決まります。規則が一致したときは、規則側の設定が全体の既定値を上書きします。

retryCountは0から9999の整数で、既定は0です。model-chainに並べるモデルは、すべてCCRに設定済みのモデルセレクタでなければなりません。次のような形になります。

{
  "mode": "model-chain",
  "models": ["Provider/backup-one", "Provider/backup-two"],
  "retryCount": 0
}

画面上では、フォールバック先がタグとして並び、上下の矢印で順序を入れ替えます。無料枠のあるプロバイダーを先頭に置き、失敗したら有料のプロバイダーへ落とす、といった階段状の構成が組めます。

複数のAPIキーを持つなら、プロバイダーの「Credential pool」タブで優先度・重み・上限を設定できます。保存後にリクエストログを認証情報で絞ると、ローテーションが効いているかを確かめられます。

つまずいたときの切り分け

CCRのQ&Aは、症状から原因を探す形で並んでいます。Claude Codeとの組み合わせで出やすいものを選びます。

CCRのQ&Aには、費用が急に増えたときの調べ方もあります。推測せずにリクエストログをモデル・プロバイダー・認証情報で絞り、トークンの構成とリクエストボディの大きさ、最終的に使われたモデルを見て、増加分の出どころを突き止めます。

どちらを選ぶか

標準のゲートウェイとCCRは、そもそも解く問題が違います。やりたいことごとに、向く構成を並べます。

個人で複数のモデルを試す用途では、CCRの手軽さは明らかな利点です。一方、チームや組織で使うなら、サポート対象外の経路に開発体制を載せることになります。Claude Codeのリリースごとに、CCR側が新機能を転送し続けられるかも継続的な確認事項です。

非Claudeモデルをローカルで動かしたいだけなら、ゲートウェイ製品を挟まない方法もあります。Ollamaへの接続手順はClaude CodeをOllamaのローカルLLMに接続する手順と制約にあります。Claude Code自体の接続先を組織で固定したい場合は、Claude CodeをLLMゲートウェイに接続する方法が出発点です。

CCRは更新が速く、画面の項目名や既定のポートが変わる可能性があります。導入するときは、手順の細部をCCRのクイックスタートで確かめてから進めてください。