Claude Code Router — Claude Codeを任意のモデルへルーティングする、またはルーターを完全に省略する

Claude Code Routerを検索する人の多くは、異なる2つの目的のどちらかを求めています。Claude Codeを複数のモデルプロバイダー間でルーティングすること、またはAnthropicの定価より安い場所でClaude Codeを実行することです。ルーターが必要なのは前者だけです。Claude Codeは ANTHROPIC_BASE_URL をネイティブに読み取るため、後者なら環境変数を3つ設定するだけで、追加ソフトウェアは一切不要です。

このガイドでは両方の経路を扱い、正確な変数名、サイレントな 401 を発生させる資格情報の落とし穴、そして任意のゲートウェイ経由で動作しなくなる機能を正直に一覧します。最近別のCCR解説を読んだ場合は、まずOption Bに進んでください。そこで編集するよう案内されている config.json は、現在ルーターが読み取る設定ではありません。

実際に必要なのはどちらですか？

ルーターはローカルサービスです。もう1つプロセスを実行、設定、最新状態に維持する必要があり、2026年時点では編集するファイルではなく、独自のUIを備えたデスクトップアプリでもあります。複数プロバイダー間のルーティング、リクエストごとの会計、またはサブエージェント単位のモデル選択が本当に必要な場合、そのコストに見合います。ベースURLだけで済む場合には見合いません。

Option A — ベースURLの切り替え（インストール不要）

KunavoはネイティブのAnthropic Messages APIを /v1/messages で提供しており、これがClaude Codeの呼び出すエンドポイントです。そこを指定します。

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URLはOriginのみです。Claude Codeが/v1/messagesを自動的に付加するため、パスを含めないでください。モデル行も維持してください。Claude Codeに組み込まれたデフォルトとそのopusエイリアスは、どちらも最新のOpusに解決されます。Kunavoがそのモデルをまだ提供していない場合、最初のリクエストは404を返します。sonnetエイリアスはKunavoが提供していないSonnet 5.5を要求するため、ANTHROPIC_DEFAULT_SONNET_MODELの行がないと、/model sonnet、opusplanの実行フェーズ、model: sonnetに設定されたすべてのサブエージェントが404になります。opusエイリアスはOpus 5.5（claude-opus-5-5）に固定されており、Claude Code v2.1.280以降が必要です。古い場合はclaude updateを実行してください。登録して$10をチャージした後、ダッシュボードからキーを取得します。キーは一度だけ表示されます。

どの資格情報変数を使うべきか — そして重要な理由

Claude Codeは2つの資格情報変数を異なるHTTPヘッダーで送信します。サーバーが読み取らないヘッダーにキーを入れると、401で失敗します。

具体的な理由から ANTHROPIC_AUTH_TOKEN を優先してください。ANTHROPIC_API_KEY には対話型セッションで一度だけ承認が必要で、一度拒否したキーはその後プロンプトなしで無視されます。変数は明確に設定されているのに明確に使われないという、分かりにくい失敗です。Kunavoでは、モデル検出によってこの選択は決まりません。Claude Codeのゲートウェイモデル検出は、ANTHROPIC_AUTH_TOKEN が設定されている場合はベアラートークンのみを送信し、それ以外では x-api-key にフォールバックします。Kunavoの /v1/models エンドポイントは、どちらのヘッダーからもキーを読み取ります。

設定を定着させる

シェルのexportは、そのターミナルとそこから起動したものにしか適用されません。Dockから開いたエディターには反映されず、バックグラウンドエージェントにも反映されません。すべてを対象にするには、設定ファイルに値を記述してください。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

すべてのプロジェクトには ~/.claude/settings.json を使用してください。プロジェクトの .claude/settings.json にキーを記述してはいけません。このファイルはコミットされます。

信頼する前に確認する

まずエンドポイントを直接テストし、失敗の原因がClaude Codeではなく設定にあることを確認します。

curl -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-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

次に、同じシェルから claude を起動して /status を実行します。Anthropic base URL の行に api.kunavo.com が表示され、Auth token の行に変数名が表示されれば、両方が有効です。

カスタムモデルを設定する — スラッグを明示的に選択

Kunavoはモデルスラッグを完全一致で解決し、日付サフィックス付きの名前を別名扱いしません。そのため、claude-sonnet-4-5-20250929 は404を返し、claude-sonnet-5 は成功します。組み込みデフォルトに依存せず、必ず ANTHROPIC_MODEL を設定してください。

エイリアス用の変数を設定すれば、ルーターなしでタスクごとに振り分けられます。ANTHROPIC_DEFAULT_OPUS_MODELはopusエイリアスとプランモードに使われます。ANTHROPIC_DEFAULT_SONNET_MODELはsonnetとopusplanの実行フェーズに使われます。ANTHROPIC_DEFAULT_HAIKU_MODELはhaikuと、要約やタイトル生成などClaude Codeのバックグラウンド作業に使われます。Kunavo経由では後者の2つが必須です。固定しないと、Kunavoが提供していないモデルID（Sonnet 5.5と、v2.1.293以降のHaiku 5.5）を要求します。Haikuの設定先はclaude-haiku-4-5にしてください。これにより、バックグラウンド作業もメインモデルから切り替わります。（ANTHROPIC_SMALL_FAST_MODELは同じ設定の非推奨表記です。）

任意：ピッカーにすべてのモデルを表示する

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1（Claude Code v2.1.129以降）を設定すると、Claude Codeは起動時に GET /v1/models をクエリし、見つかったモデルを /model ピッカーにFrom gatewayというラベルで追加します。Kunavoはこのエンドポイントを提供するため、有効なClaudeモデルがすべて表示され、/model は手動で管理するリストではなくライブメニューになります。どちらの資格情報変数でも使用できます。上記を参照してください。

Option B — 現在実際に動作するclaude-code-router

ここから始めてください。CCRについて書かれたもののほとんどは、もはや存在しないバージョンについて説明しているからです。以前のルーターはJSONファイルと ccr code コマンドでした。現在はデスクトップアプリ、管理UI、リクエストログ、モデルゲートウェイを備えたローカルコントロールプレーンです。そして、チュートリアルが示す config.json は、もう設定には使われません。

CCRはランタイム設定を ~/.claude-code-router/config.sqlite（Windowsでは %APPDATA%\claude-code-router\config.sqlite）に保持します。従来の config.json は、SQLite設定がまだ存在しない場合に、移行元として一度だけ読み取られます。その初回実行後は、編集しても実行中の設定には影響しません。エラーも警告も表示されません。慎重に貼り付けた Providers ブロックは、単に設定ではありません。

これには、2026-09-06以前のこのページも含まれます。以前ここに掲載していたJSONスニペットは誤っており、無視されたことを何も知らせないため、午後の時間を費やす種類の誤りでした。現在はUIで設定します（バックアップの場合はSettings → Export dataを使用します。CCRの実行中にライブSQLiteファイルをコピーしないでください）。

インストールと起動

CCRには2つの提供方法があります。GitHub Releasesから入手するデスクトップアプリ（トレイ、自動更新、デスクトップ統合）と、ヘッドレスまたは監視付きデプロイ向けのnpm CLIです。両者は同じ設定ディレクトリを共有します。

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Kunavoの追加は、1つのプロバイダーエントリ（Providers → Add provider、プリセット Other / custom API endpoint、エンドポイント https://api.kunavo.com、自分の sk-kn- キー）と、1つの Agent Config → Add profile → Claude Code プロファイルで完了します。Check Connectionとモデル検出を含むフィールドごとの手順は、Claude Code Router統合ページにあります。このセクションの残りでは、そのページで扱っていない資格情報、費用、失敗モードを説明します。

3つの資格情報と、401がどれを指すか

これは、動作するセットアップが壊れているように見える最も一般的な原因です。CCRには3つの別々のシークレットがあり、それぞれ異なる3つのホップを認証します。

ポートの対応関係も混乱しやすい点です。管理サービスのデフォルトは127.0.0.1:3458、モデルゲートウェイは127.0.0.1:3456です。3458を指すベースURLでは、ゲートウェイではなくUIに到達します。（Dockerでは、意図的に両方を1つのNginxエンドポイントの背後にまとめているため、Dockerの手順は異なって見えます。）UIに到達できても、ゲートウェイが動作しているとは限りません。ゲートウェイアドレスで/healthを確認し、ServerがRunningと表示されることを確認してください。

ティアごとのマッピングが要点です

Claude Codeはモデルを要求するのではなく、ティアを要求します。メインループではSonnetまたはOpusが必要で、バックグラウンド処理（サブエージェント、検索、要約、会話タイトル）では小型で高速なモデルが必要です。Agent ConfigのClaude Codeプロファイルでは、これらを個別のフィールドとして設定できます。デフォルトのModelに加え、オプションでFable、Opus、Sonnet、Haikuを上書きでき、それぞれProvider/model値を受け取ります。ティアを空欄にすると、Claude Codeが選択します。

誰かのティア構成をコピーする前に、この表を確認してください。明らかな分割が最初のレバーです。claude-sonnet-5はKunavoでclaude-opus-5-5より50%安い（$1.40 / $7.00 対 $2.80 / ）。2つ目のレバーはHaikuティアです。$0.70 / $3.50ではSonnet 5より2倍安く、見えない大量の処理を担います。すべてのサブエージェント、すべてのファイル振り分け処理、生成されるすべてのタイトルが対象です。claude-sonnet-4-6はもはや安価なSonnetではありません。$2.10 / $10.50ではSonnet 5より50%高いため、上のスニペットではANTHROPIC_MODEL=claude-sonnet-5を設定しています。

サブエージェントのルーティング — ティアマップではできないこと

ティアの上書きでは、すべてのサブエージェントが1つのモデルに固定されます。CCRなら、さらに細かく設定できます。Claude Codeのリクエストが組み込みルートに一致すると、利用可能なモデルのリストをAgent / Taskツールの説明に挿入します。そしてClaude Codeは、生成する各エージェントのプロンプトの先頭に、使用したいモデル名のタグを付けます。

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCRはタグを取り除き、その1件のリクエストを適切にルーティングします。そのため、検索サブエージェントをHaikuで実行し、レビュー用サブエージェントをOpusで実行するなど、固定ではなくタスクごとに選択できます。この切り替えは見落としやすい点です。Modelsページで少なくとも1つのモデルにDescriptionが設定されるまで、この仕組みは無効です。説明がない場合、CCRは何も挿入せず、すべてのサブエージェントが静かにプロファイルのデフォルトへフォールバックします。説明にはタスクへの適性を書いてください。Haikuには「コード検索、ファイルの振り分け、低コストの並列サブエージェント」、Opusには「アーキテクチャ分析、高リスクのレビュー」などです。動作すると、リクエストログにルート理由としてbuiltin:claude-code-subagentが表示されます。

プロトコルの選択と、キャッシュで発生するコスト

CCRはエンドポイントを調べ、通信プロトコルを選択します。ベースオリジンとしてhttps://api.kunavo.comを指定するとAnthropic Messagesで通信し、https://api.kunavo.com/v1を指定するとOpenAI互換形式で通信します。どちらのインターフェースも同じキーで利用でき、Advanced設定で自動検出を上書きできます。

Anthropic Messages形式を推奨します。これによりcache_controlが通信上に保持されるため、プロンプトキャッシュがモデルまで届き、キャッシュ済み入力は入力料金の10%で課金されます（仕組み）。各ステップで安定したプレフィックスを再送するエージェントループでは、利用可能な節約効果の中で最大です。正直な注意点として、経路上のルーターはリクエストを変更します。CCRはClaude Codeが挿入する課金ヘッダーのシステムメッセージを削除し、サブエージェントのルーティングが有効な場合はツールの説明にモデルリストを追加します。どちらもキャッシュブレークポイントの手前に位置するため、その内容を変更するたびに1回キャッシュミスが発生し、新しいプレフィックスが温まります。その後は安定しますが、実行の手間が少ないことに加え、これがOption Aのキャッシュ効率がOption Bよりわずかに高い実際の理由です。

ただし、OpenAI互換形式でもプロンプトキャッシュはモデルまで届きます。長いプロンプトでは、Kunavoがそのルート上でキャッシュブレークポイントを自ら設定します。設定先は、システムプロンプト、ツール定義、そして会話にアシスタントのターンが含まれていれば最後のメッセージです。メッセージまたはツール定義に付いて届いたcache_controlは保持されます。

フォールバック：再試行とフェイルオーバー

RoutingページのDefault on failureは、必要になる前に設定しておく価値があります。Retryは、408、409、429、5xxの場合に同じモデルへ再送し、Retry-Afterに従い、それがない場合は待機時間を1秒から指数関数的に増やします。待機時間の上限は30秒です。Fallback targetsはバックアップモデルの順序付きリストをたどり、任意の4xxまたは5xxで発動します。モデルが見つからない場合やプロバイダーによる拒否は、現在のターゲットだけに影響している可能性があるためです。個別のルールでグローバル設定を上書きできます。フォールバックが実行されると、レスポンスにx-ccr-fallback-attemptsとx-ccr-fallback-modelが含まれるため、後から確認できます。

実際に経路上にあることを確認する

プロファイルからClaude Codeを起動して1件メッセージを送信し、CCRでRequest logsを開きます。行にはrequest model（Claude Codeが要求したもの）、resolved provider、resolved model（実際の送信先）が表示されます。この3つが証拠です。CLI内では/modelでCCRが公開するモデルを一覧表示できます。Claude Codeが応答するのにログ行が表示されない場合は、CCR経由ではなく自分でClaude Codeを起動しており、プロファイルのスコープがOnly opened from CCRになっています。

コーディングセッションのコスト

Claude Codeは各ステップでシステムプロンプト、会話、新しいファイルコンテキストを再送するため、トークン単価が急速に積み重なります。Kunavoのclaude-sonnet-5料金では、次のようになります。

プロンプトキャッシュ適用前で、メインモデルではおよそ30%安価です。完全な料金はClaude API pricing guideに、独自のトークン数を使った計算はcost calculatorに掲載されています。

現在も動作するもの — そして動作しないもの

Claude Codeを任意のゲートウェイに向けると、いくつかの点が変わります。コミットする前に知っておく価値のある項目は、次のとおりです。

最後の行について：トークンカウントは、Anthropic独自のゲートウェイ仕様でオプションとされている唯一のエンドポイントです。これがない場合、Claude Codeはコンテキスト使用量をローカルで推定します。Kunavoは現在/v1/messages/count_tokensを提供していないため、/contextの値は正確なカウントではなく推定値です。それ以外の点で機能が低下することはありません。自動コンパクションとセッション自体には影響しません。

トラブルシューティング

ベースURLのパス

…ルーターが経路上にある場合

API自体のエラー別の修正方法は、invalid API keyおよびrate limitのトラブルシューティングページにあります。

よくある質問