Claude Code Router（CCR）は、Claude Codeが送る要求を手元のゲートウェイで受け、OpenRouterやDeepSeek、Kimiなど別のモデルへ振り分けるOSSです。2026年7月公開のv3で、設定の置き場所が config.json からSQLiteと管理画面へ移り、ネットの解説記事の多くがそのままでは動かなくなりました。この記事では、v3.1.3（2026年11月6日時点のnpm最新）を基準に、インストール、Claude Codeの接続、モデルの振り分けとフォールバックの設定を順に扱います。業務で使う場合の規約上の注意と、公式ゲートウェイやLiteLLMとの使い分けも整理しました。
まとめ：Claude Code Routerを入れる前に決めるべき接続方式と利用範囲
個人の検証で他社モデルを試すだけなら、npm版の ccr ui で管理画面を開き、プロバイダー登録、クライアントキー発行、Claude Code用プロファイル作成の3つを済ませれば動きます。古い記事にある config.json の手書きと ccr code は、v3では前提が変わっています。
会社の標準環境にする場合は慎重に判断してください。Anthropicは、ゲートウェイ経由でClaude Codeを非Claudeモデルへ振り分ける使い方をサポート対象外と明記しています。Claudeのサブスクリプションのログイン情報をCCRへ取り込む機能もありますが、業務ではAPIキーかクラウド経由の契約を使うのが安全です。Claudeだけを社内で統制したいなら、公式のClaude apps gatewayか、既に運用しているLLMゲートウェイを優先します。
Claude Code Routerの仕組みとv3で変わったconfig.jsonの扱い
ローカルの3456番ポートで要求を受けて他社モデルへ中継する構成
公式リポジトリのREADMEによると、モデル用ゲートウェイは既定で http://127.0.0.1:3456 で待ち受け、受けた要求をプロバイダーごとの形式（OpenAI Chat、Gemini、Anthropic Messagesなど）に変換して転送します。ライセンスはMITで、2026年11月時点のスター数は約3.8万件です。
v3ではClaude Code専用ではなくなりました。Codex、Grok CLI、Kimi CLI、OpenCodeなど10種類のエージェントを1か所でつなぐ「ローカルの制御盤」という位置づけで、要求ログ、トークン数、推定コストも画面で確認できます。
v2までのconfig.jsonとccr codeの手順がv3でそのまま通らない理由
v2.0.0のREADMEでは、~/.claude-code-router/config.json に Providers と Router（default・background・think・longContextなど）を書き、ccr code で起動する手順でした。検索上位の記事もほぼこの形です。
v3では、設定データベースの説明にあるとおり、実体は config.sqlite に変わりました。config.json はSQLiteの設定が無いときに移行元として1回読まれるだけで、移行後に書き換えても反映されません。CLIリファレンスのコマンド一覧にも ccr code は載っていません。古い記事どおりにJSONを直して「効かない」と悩むのは、ほとんどがこの差です。
npm版CLIのインストールからClaude Codeを接続するまでの作業手順
Node.js 22以上でccr uiを起動し管理画面でプロバイダーを登録する手順
CCRにはデスクトップ版とnpm版があり、同じ設定ディレクトリを読みます。サーバーで常駐させるならNode.js 22以上で動くnpm版が扱いやすい構成です。
node --version
npm install -g @musistudio/claude-code-router
ccr ui # SSH先などブラウザが無い環境は ccr ui --no-open管理画面は http://127.0.0.1:3458 に開きます。ここから次の順に進めます。
- Providersでプリセット（OpenRouter、DeepSeek、Moonshotなど）か独自エンドポイントを選び、APIキーとモデルを登録する
- API Keysでクライアントキーを発行する（表示は作成時の1回だけ）
- Routingで既定モデルと失敗時の動作を決める
- Serverでゲートウェイが動いていることを確かめる
起動時に出る管理URLには ccr_web_token が含まれます。公式はこのURL全体をパスワードとして扱い、ログやチケットに貼らないよう求めています。
Agent ConfigでClaude Code用プロファイルを作りccrで起動する方法
一番手間が少ないのは、CCR側でClaude Code用のプロファイルを作り、CCRから起動する方法です。Claude Code用の設定ページの手順で、Agent ConfigからClaude Codeを選び、名前と既定モデル（例：Moonshot/kimi-k3）を指定して保存します。
# プロファイル名で起動（npm版）
ccr "Claude Code - Work"
# Claude Code側の引数は -- の後ろに渡す
ccr "Claude Code - Work" cli -- --model sonnet適用範囲は「CCRから開いたときだけ」と「システム既定」から選べます。前者なら、普段の claude は今までどおりAnthropicへ直接つながるため、検証用に向いています。デスクトップ版では起動名が ccr-app になる点に注意してください。Claude Code自体の初期設定はClaude Codeのインストールと権限・CLAUDE.md設定の手順で解説しています。
ANTHROPIC_BASE_URLとクライアントキーでclaudeコマンドを向ける設定
プロファイルを使わず、いつもの claude をCCRへ向けることもできます。Claude Codeのゲートウェイ接続ガイドに沿い、ベースURLと認証情報を環境変数で渡します。
# 1. ゲートウェイへ直接1トークンだけ送って疎通を確かめる
export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
export ANTHROPIC_AUTH_TOKEN=CCRで発行したクライアントキー
curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
# 2. 通ったら ~/.claude/settings.json の env に移す
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
"ANTHROPIC_AUTH_TOKEN": "CCRで発行したクライアントキー",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
}
}401が返るときは、変数を ANTHROPIC_API_KEY（x-api-key ヘッダー）に替えて試します。最後の変数を入れると、ゲートウェイが返すモデル名が /model の一覧に並びます。キーはコミットされるプロジェクトの .claude/settings.json には書かないでください。接続後は /status に「Anthropic base URL」の行が出ていれば成功です。
OpenRouter・DeepSeekなど他社モデルへの振り分けとフォールバックの設定
Fable・Opus・Sonnet・Haikuの段ごとに別モデルを割り当てるモデル別名
Claude Codeは処理の重さに応じて内部で段（Fable、Opus、Sonnet、Haiku）を使い分けます。CCRのプロファイルには段ごとにモデルを差し替える欄があり、v2の Router.think や background に近い役割を担います。
| CCRの設定欄 | Claude Code側で使われる場面 | 割り当ての例 |
|---|---|---|
| Model（既定） | 段の指定が無い通常の対話 | Moonshot/kimi-k3 |
| Opus model | 計画や難しい推論 | 推論の強いモデル |
| Sonnet model | 通常の実装作業 | コーディング向けモデル |
| Haiku model | 軽い補助処理 | 安価で速いモデル |
空欄の段はClaude Codeの判断に任されます。別名に入れる値は、CCRが実際に提供できる プロバイダー/モデル でなければ効きません。計画段と実行段を分ける考え方はopusplanでOpusとSonnetを自動で切り替える設定と同じです。
サブエージェントだけ安価なモデルへ回すCCR-SUBAGENT-MODELタグの仕組み
CCRのルーティング説明によると、Claude CodeがAgentやTaskでサブエージェントを起こすとき、CCRはツール説明に使えるモデルの一覧を差し込みます。Claude Code側はプロンプト先頭に CCR-SUBAGENT-MODEL タグでモデル名を書き、CCRがそのタグを外して指定モデルへ送る流れです。
この仕組みはModelsページの「Description」が1件も無いと動きません。説明欄に「コード検索や要約向け、安価」「設計レビュー向け、遅いが強い」のように用途を書いておくと、それを手がかりに振り分け先が選ばれます。ログに builtin:claude-code-subagent と出れば成功です。サブエージェント側の定義方法はClaude Codeのサブエージェントの作り方と設定項目を参照してください。
Node.jsスクリプトで入力トークン数に応じてモデルを切り替えるルール例
v2の longContextThreshold（既定60,000トークン）に相当する振り分けは、v3ではRoutingのルールにNode.jsスクリプトを指定して書きます。ファイルは非同期関数の本体として扱われ、input を読んで振り分け先を返します。
// long-context.js（Routing → Add → Rule type: Node.js script）
if (input.tokenCount === 0 || input.tokenCount < 60000) {
return null; // 一致しない。次のルールへ
}
return {
model: "OpenRouter/LONG_CONTEXT_MODEL", // CCRに登録済みの名前に置き換える
fallback: { mode: "model-chain", models: ["DeepSeek/BACKUP_MODEL"], retryCount: 0 }
};モデル名は、CCRに登録済みの名前と一致させます。登録の無い名前を返すと、そのルールは診断ログを残して不一致扱いになります。スクリプトが例外やタイムアウト（10〜30,000ミリ秒で指定）を起こした場合も、止まらずに次のルールへ進む作りです。
429や5xxで止めないためのRetryとFallback targetsの使い分け
失敗時の動作は、Routing画面上部の「Default on failure」で全体を、各ルールの「On failure」で個別に決めます。
| モード | 切り替わる応答 | 向いている障害 |
|---|---|---|
| Retry | 408・409・429・5xx | 一時的なレート制限やタイムアウト |
| Fallback targets | すべての4xxと5xx | モデル廃止、認証切れ、提供元の停止 |
待ち時間は、上流が Retry-After を返せばそれに従い、無ければ1秒から始まる指数的な待ちで、1回あたり最大30秒です。他社APIはモデル名の改廃が速いため、実務では既定をFallback targetsにして、別の提供元のモデルを2番手に置く構成を勧めます。どのモデルで応答したかは応答ヘッダーの x-ccr-fallback-model で確認できます。
業務でClaude Code Routerを使うときの規約とセキュリティの注意点
Anthropicが非Claudeモデルへの振り分けをサポート対象外とする範囲
Claude Codeのゲートウェイ解説には、Anthropicは第三者のゲートウェイ製品を保証・監査せず、ゲートウェイ経由で非Claudeモデルへ振り分ける使い方もサポートしないと書かれています。禁止とまでは書かれていませんが、不具合が起きても公式の支援は受けられません。
実際に起きやすいのは、Claude Codeの新機能が送る項目を相手側が受け付けない問題です。同じガイドは、Extra inputs are not permitted などの400エラーには CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 で試験的な項目を抑える対処を挙げています。Claude Codeを更新したら、CCR経由の動作を確かめてから全員へ配る運用にしてください。
サブスクリプションのOAuthをCCRへ取り込む使い方を業務で避ける理由
CCRのプロバイダー追加画面は、手元のClaude CodeのOAuthログイン情報を読み取り「Claude Code API」として登録する機能を持っています。一方、Claude Codeの法務・コンプライアンスのページは、OAuth認証を「Claude Codeや純正アプリの通常利用」のためのものとし、開発者がClaude.aiの認証情報やセッショントークンを収集・保存・中継することを認めていません。
個人の判断で試す範囲を超えて、会社のアカウントでこの取り込みを使うのは見送るべきです。ゲートウェイ用の認証情報を使う場合、要求はサブスクリプションの上限ではなく、その認証情報の持ち主にトークン単位で課金されます。プランとAPI課金の損益分岐はClaude Codeの料金プラン比較と支出上限の設定で整理しています。
0.0.0.0で待ち受ける前に揃える管理トークン・クライアントキー・TLS
CCRには性格の違う認証情報が3つあります。管理画面を守る管理トークン、モデル要求を通すクライアントキー、上流プロバイダーのAPIキーです。Server設定の説明は、利用者に配るのはクライアントキーだけで、上流のキーを渡してはならないとしています。
チームで共有するためにHostを 0.0.0.0 にする場合は、固定の強い CCR_WEB_AUTH_TOKEN、ファイアウォールか閉域網、信頼できるリバースプロキシでのTLSをそろえてからにします。クライアントキーには有効期限と、分・時・日単位の要求数やトークン数の上限を付けられます。上流のキーは設定ディレクトリ（Windowsは %APPDATA%\claude-code-router）に保存されるため、そのバックアップも機密として扱ってください。Claude Code側の権限ルールや管理設定はClaude Codeのセキュリティ設定の実装手順にまとめています。
Claude Code Routerと公式ゲートウェイ・LiteLLMの違いと選び方
Claude apps gateway・LiteLLM・CCRの対応範囲と運用負荷の比較
CCR以外の選択肢として、Claude apps gatewayはAnthropicが提供する自社運用型で、Amazon Bedrock、Google Cloud、Microsoft Foundryなどを上流にし、SSOでのサインインとグループ単位のモデル許可、OTLPでの利用計測を備えます。
| 観点 | Claude Code Router | LiteLLM Proxy | Claude apps gateway |
|---|---|---|---|
| 主な用途 | 個人端末で他社モデルを試す | 社内共通のLLM API窓口 | Claudeを自社クラウド経由で統制 |
| 非Claudeモデル | 主目的 | 対応 | 対象外 |
| 利用者管理 | クライアントキー単位 | キー・チーム・予算 | SSOとグループ |
| Anthropicの支援 | 対象外 | 対象外 | 対象 |
LiteLLMの構築とフォールバック・予算の設定はLiteLLM Proxyの構築手順で、ゲートウェイ全般の役割はAIゲートウェイの役割と導入判断で解説しています。
個人の検証はCCR、社内標準はClaudeのまま統制する判断基準
CCRを選んでよいのは、開発者が自分の端末で他社モデルの実力を比べたい場面です。設定はGUIで済み、要求ログでモデルごとの応答とコストを並べて見られます。
反対に、数十人規模の開発組織で「Claude Codeを全員に配り、費用と監査ログを一元管理したい」ならCCRは選びません。端末ごとにSQLiteの設定を持つ作りのため、配布と更新の統制が効きにくいからです。Claudeを使い続けるなら公式ゲートウェイかクラウド経由、複数社のモデルを社内APIとしてまとめるならLiteLLMなどのサーバー型が合います。社内ゲートウェイを含めたAI開発基盤の設計・構築は、生成AI開発・AI受託開発でご相談いただけます。
Claude Code Routerの導入・設定でよくある質問
導入前によく確認される点を、v3.1.3と公式ドキュメントの記載に沿って回答します。
Claude Code Routerを使えばClaude Codeを無料で使えますか？
CCR自体はMITライセンスで無料ですが、振り分け先のモデル料金は別にかかります。OpenRouterの無料枠付きモデルや、手元のOllamaで動かすローカルモデルを選べば支払いを抑えられます。その場合、応答の質とツール呼び出しの安定性はClaudeと同じにはなりません。Claude Code本体の利用にAnthropicのアカウントやプランが要るかは、どのモデルへ振り分けるかと認証方法で変わります。
Ollamaなどのローカルモデルにも接続できますか？
ローカルモデルへの接続は可能です。Providersで独自エンドポイントを選び、Ollamaの http://localhost:11434/v1 のようなOpenAI互換のURLとモデル名を登録します。ただしClaude Codeはツール定義の多い長いプロンプトを送るため、小さなモデルではファイル編集の指示を正しく返せないことがあります。まずSonnet段だけを置き換え、ログで失敗率を見てから範囲を広げる進め方が無難です。
ccr codeを実行してもコマンドが見つからないのはなぜですか？
v3のCLIでは、起動方法がプロファイル単位に変わったためです。Agent ConfigでClaude Code用のプロファイルを作って有効にし、ccr "プロファイル名" で起動します。ccr 自体が見つからない場合は、npm prefix -g でnpmのグローバル領域を確かめ、そのbinがPATHに入っているかを確認してから新しい端末を開き直してください。
Windowsでも使えますか？設定ファイルはどこにありますか？
使えます。デスクトップ版のインストーラーと、npm版の両方が用意されています。設定は %APPDATA%\claude-code-router\config.sqlite に保存され、macOSとLinuxでは ~/.claude-code-router/config.sqlite です。動作中にSQLiteファイルを直接編集・コピーすると壊れるおそれがあるため、バックアップは設定画面のExport dataを使います。
CCR経由でもRemote Controlや音声入力は使えますか？
使えません。Claude Codeの公式ガイドによると、Remote Controlは ANTHROPIC_BASE_URL がAnthropic以外を指している間は無効になり、音声入力もゲートウェイの認証情報が有効な間は止まります。これらを使うときは、CCRから開いたときだけ設定が効くプロファイル方式にして、通常の claude はclaude.aiのログインで使い分けると切り替えが楽です。
関連記事
- Sakana FuguをClaude Codeで使う設定手順：ゲートウェイを挟まず、特定の他社モデルをClaude Codeへつなぐ例
- Kimi K2.7 Codeとは？料金・HighSpeed版・ローカル実行とClaude Code接続：CCRの振り分け先として候補になるモデルの仕様
- DeepSeek-V3.2とは？仕組みと性能、2026年の使い方と料金：DeepSeekを振り分け先にする前に確認したい提供状況
- CodexとClaude Codeの違い：エージェント自体を替える選択肢との比較
- Claude CodeのOpenTelemetry設定：ゲートウェイとは別経路で利用状況とコストを可視化する方法
