Claude Code Router 3.1.1のインストール・ルーティング・トラブル解決
Claude Code Router 3.1.1の現行仕様に沿った実践ガイドです。Node.js 22+での導入、ProviderとRouting、Agent Profiles、サービスコマンド、代表的なエラー、ANTHROPIC_BASE_URLで直結すべき条件まで説明します。
目次
Claude CodeからDeepSeek、OpenRouter、Gemini、Kimi、Z.AI/GLM、または別の互換Endpointを使いたいのに、見つけた手順がまだconfig.jsonとccr codeを前提にしている。あるいはUIは開くのに、127.0.0.1:3456のgatewayが起動しない。この記事では、現行の3.1.1に合わせて、インストールからClaude Code用Profileの検証までを順番に進め、よくある失敗を層ごとに切り分けます。
最初にバージョンを確認する：3.1.1は手書きのconfig.jsonが中心ではない
現在はProvider、Routing、Agent ProfilesをWeb UIで設定し、古いJSON設定をそのままコピーしません。 2026年9月26日時点でnpmのlatestは3.1.1です。現行パッケージは主な設定をconfig.sqliteに保存し、稼働中のgateway向けにgateway.config.jsonを生成します。これはnpmレジストリのメタデータと現在のプロジェクトREADMEで確認できます。
この違いを知ると、二つの典型的な行き詰まりを避けられます。現在のCLIリファレンスはccr <profile-name-or-id>でAgentを起動し、ccr codeを掲載していません。また、gateway.config.jsonは生成物であり、手作業で維持する設定元ではありません。config.jsonやccr codeを要求する記事を見たら、PATHを疑う前に対象CCRバージョンを確認してください。
Node.js、upstream Provider、Claude Codeを準備する
Node.js 22以降、利用可能なモデルProvider、ローカルに導入済みのClaude Codeが必要です。 CCRはリクエストをルーティングするもので、Claude Code自体をインストールしません。また、APIアクセスはClaude.aiやClaude Maxのサブスクリプションとは別物です。
まずNode.jsを確認します。
node --versionメジャーバージョンが22未満なら先に更新します。UpstreamにはOpenRouter、DeepSeek、Gemini、Moonshot/Kimi、Z.AIなどの組み込みpreset、または対応するOpenAI-compatible／Anthropic-compatible protocolを実装したcustom endpointを利用できます。
npm CLIをインストールし、設定前にccrコマンドを確認する
グローバルインストール直後にhelpを実行します。 これにより、npmやPATHの問題とProvider／Routingの問題を分離できます。
npm install -g @musistudio/claude-code-router
ccr --help更新と削除は次のコマンドです。
npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-routernpmパッケージを削除しても、ローカル設定やデータベースは自動削除されません。データディレクトリはmacOS/Linuxで~/.claude-code-router、Windowsで%APPDATA%\claude-code-routerです。
Provider → Check Connection → Client Key → Routing → Server → Profile → end-to-end testの順で設定する
条件やfallbackを追加する前に、まず一つのdefault routeを通します。 複数Provider、rewrites、retries、fallbacksを同時に設定すると、401、誤ったModel ID、protocol mismatchを区別しにくくなります。
管理UIを開きます。
ccr ui管理UIの既定値はhttp://127.0.0.1:3458、モデルgatewayの既定値はhttp://127.0.0.1:3456です。CCRが表示または自動で開いた認証付きURLを使ってください。3458が使用中なら、CCRが次の空き管理ポートを選び、実際のURLを表示する場合があります。
1. Providersにupstreamを追加する
presetがある場合はそれを優先し、必要な場合だけcustom endpointを使います。 Providers → Add Providerでサービスを選び、そのProvider自身のAPI Key、正しいprotocol、アカウントで実際に利用できるModel IDを登録します。
モデルの製品名からprotocolを推測しないでください。Anthropic Messages、OpenAI Chat/Responses、Geminiはリクエスト形式が異なります。Base URL、protocol、Model IDはupstreamの現行ドキュメントと一致させます。
Providerを保存したらCheck Connectionを実行します。これはupstream設定だけの接続確認であり、Claude Code → CCR gateway → Routing → Providerという全経路の検証ではありません。
2. API KeysでCCR client keyを作成する
CCR client keyとmanagement tokenは別の認証情報です。 Management tokenはWeb UIとRPC APIを保護し、client keyはClaude Codeからgatewayへ送るモデルリクエストを認証します。ccr_web_tokenを含む管理URLはパスワードとして扱い、ログ、チケット、チャットに貼らないでください。
3. 条件やfallbackより先にdefault routeを作る
Check Connectionを通過したProvider一つと、そのProviderのmodel一つだけをdefault routeに指定します。 Routeを保存しますが、まだClaude Codeからrequestは送りません。先にgatewayを起動し、Agent Profileを作成します。
手順6のend-to-end requestが成功してから、Routingでconditions、retries、request rewrites、ordered fallbackを追加します。一度に一つだけ変更し、その都度再検証してください。Fallback modelも、タスクに必要なtools、context、protocolを扱えなければなりません。どちらも会話できるというだけでは互換になりません。
4. Serverでgatewayを起動して確認する
UIが開いていても、3456のgatewayが使えるとは限りません。 Serverでgatewayを起動し、表示されるclient向けURLを記録します。既定値はhttp://127.0.0.1:3456ですが、CCRが表示する実際のURLを使ってください。起動に失敗したらforegroundでエラーを確認します。
ccr serveForeground出力を見ると、ポート競合、未完成のProvider、モデル未登録、ローカルファイル権限の問題を切り分けやすくなります。
5. Claude Code用Agent Profileを作成して有効化する
現行CLIは有効なAgent Profileを経由してClaude Codeを起動します。 Agent ProfilesでClaude Code用Profileを作成し、Check Connectionを通過したProviderのdefault routeで使うmodelを選び、保存して有効化します。CCRを使う場合、Claude Codeの接続先はServerに表示されるCCR gateway（既定値http://127.0.0.1:3456）であり、upstream ProviderのURLではありません。Profile名は任意で、例としてClaude - Reviewを使えます。
名前またはIDで起動します。
ccr "Claude - Review"Claude Code固有の引数は--の後ろに置き、CCR自身のoptionとして解釈されないようにします。
ccr "Claude - Review" cli -- --model sonnetClaude - Reviewは実際に作成したProfile名またはIDへ置き換えてください。
6. Claude Codeからrequestを送り、Logsを確認する
ここで初めて本当のend-to-end testを行います。 起動したProfileからClaude Codeで簡単なrequestを送り、Logsで意図したProviderとmodelが選ばれ、成功statusになったことを確認します。
ProviderのCheck Connectionが確認するのはupstream接続だけです。実requestではCCR client key、gateway、Routing、Agent Profile、model callもまとめて検証できます。
ccr start、ui、serve、stopの役割を使い分ける
通常運用ではccr uiまたはccr start、調査ではccr serveを使います。
| コマンド | 向いている場面 | 動作 |
|---|---|---|
ccr start | バックグラウンド常駐 | Detached管理サービスとgatewayを起動し、認証付き管理URLを表示する |
ccr ui | ローカルでの対話設定 | 既存バックグラウンドサービスを再利用または起動し、UIを開く |
ccr serve | トラブル調査、process supervisor | Foregroundで動作し、起動・リクエストエラーを表示する。ccr webはalias |
ccr stop | バックグラウンド設定の作り直し | startまたはuiが起動したdetached serviceを停止する |
start、ui、serveは--host、--port、--open/--no-open、--gateway/--no-gatewayを受け付けます。ここでの--portは優先する管理ポートであり、モデルgatewayの3456を自動的に指定するものではありません。
「ccr: command not found」はNodeとnpmのglobal binを確認する
再インストールを繰り返す前にruntimeとglobal prefixを確認します。
node --version
npm prefix -gNode.jsが22以上であり、npmのglobal executable directoryが現在のshellのPATHに含まれることを確認します。Shellによってはコマンド位置をcacheするため、インストール後に新しいterminalを開いてください。
Desktop appも導入している場合、関連コマンドccr-appが追加されます。一方、このnpmパッケージが導入するのはccrです。ccr-appが存在しても、npm CLIがPATHにある証明にはなりません。
127.0.0.1:3456で待ち受けないgatewayを直す
Gatewayが起動できていないのか、別processがポートを占有しているのかを先に確認します。 3458のUIが正常でも、3456の状態は分かりません。
macOS/Linuxでは次を実行します。
lsof -nP -iTCP:3456 -sTCP:LISTENWindowsでは次を使います。
netstat -ano | findstr :3456古いCCR processや別プログラムがポートを使っている場合、停止する前にPIDを特定します。その後ccr serveを実行し、Serverへ戻ってProvider、model、client keyが揃っていることを確認してからgatewayを再起動します。
401、model not found、protocol errorは三つの対応関係を確認する
Credentials、protocol、Model IDの順で確認します。 Management tokenをclient keyとして使う、CCR client keyをupstream Providerへ入力する、Anthropic-compatible endpointをOpenAI-compatible routeで呼ぶ、といった混同が典型です。
次の順序で確認してください。
- Claude Codeは
ccr_web_tokenではなくCCR client keyでCCRへ認証する。 - Providerにはupstreamサービス自身のAPI Keyを保存する。
- 選択したprotocolがendpointと一致する。
- Routing先のModel IDがそのProviderとアカウントで利用できる。
- Logsが意図したProviderとmodelへ解決されている。
Claude Codeの最終エラーだけを見ないでください。CCR Logsなら、client authentication、route resolution、upstream authentication、model requestのどこで失敗したかを判断できます。
Profileが見つからない場合と、古いoptionが残る場合を直す
起動できるのは有効化されたAgent Profilesだけです。 名前照合は大文字小文字を区別せず、正規化された名前も受け付けますが、曖昧な名前ではProfile IDが必要です。生成launcherがない場合はProfileを再保存します。
再利用中のbackground processは、新しいhost、port、gateway optionを自動適用しません。停止して作り直します。
ccr stop
ccr start --host 127.0.0.1 --port 3458コマンドが成功したように見えても、サービスが以前の設定を使い続けるのはこのためです。
Endpointが一つならANTHROPIC_BASE_URL直結のほうが簡単
Anthropic-compatible Endpointが一つ、主なモデルが一つで、conditional routing、fallback、共通Logs、複数Profileが不要なら、直結のほうが短く済みます。 ProviderのClaude Code向けドキュメントに従い、ANTHROPIC_BASE_URL、認証変数、model mappingを設定すれば、ローカルgatewayは不要です。
次のいずれかに当てはまるならCCRが向いています。
- DeepSeek、OpenRouter、Gemini、Kimi、Z.AI、custom endpointsを切り替える。
- タスクやProfileごとに別モデルを使う。
- retries、条件Routing、rewrites、ordered fallbackが必要。
- 実際のroute、status、tokens、latency、errorsを一か所で確認したい。
- 複数clientで一つのlocal gatewayを共有したい。
| 状況 | 優先する方法 |
|---|---|
| 安定したAnthropic-compatible Endpointが一つ | ANTHROPIC_BASE_URLで直結 |
| Provider、model、Profileが複数 | CCR |
| 各requestのrouteを確認したい | CCR |
| 一つのserviceへ最短で接続したい | まず直結し、workflowが増えたらCCRへ移行 |
互換Endpointの例：BetterTokenをCCRへ追加する
BetterTokenはcustom Anthropic-compatible Providerの一例であり、唯一の選択肢ではありません。 CCRのProvidersでは、https://bettertoken.aiをupstreamのAPI endpoint/Base URL欄に入力します。これはClaude CodeのBase URLではなく、/v1も付けません。Protocolは明示的にAnthropic Messagesを選び、自分のBetterToken API Keyと利用可能なModel IDを登録して保存し、Check Connectionを実行します。
CCRを使う場合、Claude CodeはServerに表示されるCCR gateway（通常http://127.0.0.1:3456）へ接続します。Agent Profileを起動してrequestを送り、Logsで意図したBetterToken modelへrouteされたことを確認してください。このモードでClaude Codeをhttps://bettertoken.aiへ直接向けるとCCRを迂回します。
CCRを意図的に使わず、この単一Endpointへ直接接続するときだけ、BetterTokenのClaude Codeドキュメントに従ってmacOS/LinuxでBase URLを設定します。
export ANTHROPIC_BASE_URL="https://bettertoken.ai"PowerShellでは次の通りです。
$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"このdirect modeでも、認証変数とmodel mappingは現行ドキュメントに従います。Claude CodeへOpenAI-compatible用のhttps://www.bettertoken.ai/v1を流用しないでください。
ローカル認証情報を保護し、安全にバックアップする
Remote accessを意図していない限り、管理listenerは127.0.0.1に保ちます。 Remote accessが必要ならfirewallまたはprivate networkを使い、信頼できるreverse proxyでTLSを設定します。CCR client keysなしでgatewayを外部公開しないでください。
Upstream credentials、logs、runtime databasesはCCRのローカルdata directoryにあります。CCRが書き込み中のconfig.sqliteを編集・コピーしないでください。UI exportを使うか、CCRを停止してからfilesystem backupを取得します。
UIだけでなくrequest全体を検証する
成功とは、Claude Codeのrequestが意図したrouteを通り、正常に応答した状態です。 次を確認します。
node --versionが22以上を示す。ccr --helpが実行できる。- ProvidersにCheck Connectionを通過したupstreamが一つ以上ある。
- API KeysにCCR client keyがある。
- Serverが稼働中gatewayとclient向けURL（既定値
http://127.0.0.1:3456）を表示する。 - Agent Profileが保存・有効化されている。
ccr <profile-name-or-id>でClaude Codeが起動する。- Claude Codeから実requestを送り、Logsが意図したProvider、model、成功statusを示す。
- 新しいrouteやfallbackを追加するたびに再検証した。
この順序なら、installation、authentication、Routing、Agent起動を別々の層として扱えます。問題が起きても、CCRを再インストールしたり古いconfig.jsonを当てずっぽうで編集したりせず、原因のある層だけを修正できます。
