SECTION 01
Claude Code Routerとは？公式機能との違いと解決できる課題
Claude Code Router（以下 CCR） は、Anthropic 公式の製品・機能ではなく、コミュニティが開発・公開している OSS です。Claude Code のリクエストを中継し、タスクの種類に応じて異なるプロバイダやモデルへ振り分けるプロキシとして機能します。
Anthropic 公式のモデル切替
Anthropic 公式の Claude API は、POST /v1/messages という単一エンドポイントに対して model フィールドでモデルを指定する方式です。モデルごとに別のエンドポイントを用意する必要はありません。
また、Claude Code には公式の model alias が用意されています。
- opus（Opus 4.6）
- sonnet（Sonnet 4.6）
- haiku（Haiku 4.5）
- opusplan：plan mode では Opus、execution では Sonnet に自動切替
公式の自動切替を使うだけであれば、opusplan エイリアスを指定するのが最もシンプルな方法です。
CCR が解決する課題
CCR は公式の model alias とは別のレイヤーで動作し、Anthropic 以外のプロバイダも含めたルーティングを実現します。ルーティングなしで運用を続けると、以下のような課題が出てきます。
- すべてのタスクに高コストモデルを使うことによるコストの肥大化
- 軽量タスクでも重いモデルを呼ぶことによるレスポンス遅延
- モデル選択が属人化することによる出力品質のムラ
特に API を多数のワークフローに組み込んでいる場合、モデル選択を毎回人間が判断するのは現実的ではありません。呼び出し回数が増えるほど、自動化のメリットは大きくなります。
筆者の運用例では、ワークフローが3つ以上に増えた段階でルーターの導入効果を実感しました。コスト問題が顕在化してからでは、すでに無駄な支出が積み上がっている場合があります。
SECTION 02
Claude Code Routerの基本設定と導入手順
CCR の設定は、~/.claude-code-router/config.json で管理します。このファイルに Providers（プロバイダ定義） と Router（振り分けルール） を記述するのが基本です。
config.json の構成要素
最小構成で動かすには、以下の要素を設定します。
- Providers：利用するプロバイダ（Anthropic、OpenRouter、DeepSeek、Ollama、Gemini など）の接続情報
- Router：タスク種別ごとの振り分け先の定義
Router では、以下のタスク種別キーを設定できます。
- default：指定がないリクエストの振り分け先
- background：バックグラウンド処理用
- think：思考・推論用
- longContext：長いコンテキストを扱うリクエスト用
- webSearch：Web 検索を伴うリクエスト用
- image：画像処理を伴うリクエスト用
Anthropic 直 API との違い
Anthropic の API を直接利用する場合は、単一の Messages API（POST /v1/messages）に model フィールドを指定するだけです。同一ワークスペース/プランで利用可能なモデルの範囲では、同じ API キーで model を切り替えて呼び分けられます。
CCR では、これとは別に config.json の Providers セクションで各プロバイダの接続先を定義し、Router セクションでタスク種別ごとの振り分け先を指定します。
最初は default だけを設定して動作確認するのがおすすめです。ルーターが正しく中継できているかを検証してから、think や longContext などの振り分けを追加していきます。
プロジェクト単位で API キーを分けておくと、レートリミットの管理や後々のトラブルシューティングが楽になります。
SECTION 03
振り分けルールの設計：組み込みルーティングとカスタムロジック
CCR には、前述の default / background / think / longContext / webSearch / image という組み込みのタスク種別キーが用意されています。これらを config.json の Router セクションで設定するだけで、基本的なルーティングが実現できます。
組み込みルーティングの使い方
config.json の Router に各キーと振り分け先を記述するだけで機能します。たとえば、default には Sonnet 4.6 相当のモデル、think には Opus 4.6 相当のモデルを割り当てるといった設定です。
カスタムロジックによる拡張
組み込みのタスク種別では対応しきれない場合、CUSTOM_ROUTER_PATH で独自のルーティングロジックを JavaScript で実装できます。以下は、カスタムロジックで実現できる振り分け設計の一例です。
静的ルール：トークン数・キーワード・タスク種別など、事前に決めた条件で分岐させる方法です。
- 入力トークン数が少ないリクエスト → 軽量モデル
- 「レビュー」「校正」などのキーワードを含む → 中量モデル
- 「設計」「アーキテクチャ」を含む → 高性能モデル
動的ルール：まず軽量モデルにリクエストの難易度を判定させ、その結果に応じて上位モデルに回す方法です。精度は高まりますが、判定用の呼び出しが1回増えるため、レイテンシとコストの両方に影響します。
これらはあくまで CUSTOM_ROUTER_PATH で自作するロジックであり、CCR の組み込み機能ではない点に注意してください。
筆者の経験では、最初は組み込みのタスク種別キーだけで運用を始め、振り分けミスのログが溜まった段階でカスタムロジックへ段階的に移行するのが現実的でした。最初からカスタムロジックを組むと、デバッグの難易度が一気に跳ね上がります。
SECTION 04
タスク別モデル振り分けの実践例
以下は、CCR のタスク種別キーや CUSTOM_ROUTER_PATH を使ったモデル振り分けの考え方です。
軽量タスクは Haiku 4.5 相当のモデルに回すのが基本です。テキストの要約、カテゴリ分類、定型フォーマットへの変換など、判断の幅が狭いタスクでは十分な品質が出ます。
中量タスクには Sonnet 4.6 相当のモデルが適しています。コードレビュー、文章の校正、複数の選択肢からの推薦など、ある程度の文脈理解が必要だが定型的なパターンに落とせるタスクです。
Sonnet クラスに振り分ける目安として筆者が意識しているのは、以下の条件です。
- 入出力の長さが中程度で、短すぎず長すぎないもの
- 正解が複数ありえるが、極端に外れた回答は避けたいもの
- レスポンス速度がある程度求められるインタラクティブな用途
重量タスクは Opus 4.6 相当のモデルに回します。複雑なコードの設計判断、マルチステップの推論、長い文脈を保持したまま整合性を取る必要があるタスクが該当します。
判断に迷うグレーゾーンのタスクは、まず Sonnet クラスで処理して出力を検証し、品質が足りなければ Opus クラスで再処理するという段階的エスカレーションが実用的です。
SECTION 05
コスト削減と品質劣化の境界線をどう見極めるか
ルーティングの最大のリスクは、コスト削減を追求しすぎて品質が崩れることです。安いモデルに流しすぎると、ユーザーが気づかないレベルで出力の質が下がり、後工程での手戻りが増えます。
品質劣化が起きやすい典型パターンは以下の通りです。
- 文脈の長いタスクを軽量モデルに流してしまう
- 指示が曖昧なプロンプトを Haiku クラスに任せて意図と違う出力が出る
- 連鎖的なタスクの途中ステップを軽量モデルにして、後続の精度が落ちる
品質チェックの仕組みとしては、出力に対する簡易スコアリングを自動で走らせる方法が効果的です。たとえば Sonnet の出力を Haiku で評価させ、一定の基準を下回ったら Opus で再生成するという二段構えにします。
筆者の運用経験では、コスト最適化の「落としどころ」は全体の呼び出し回数に対する上位モデルの比率で管理するのがわかりやすい方法でした。比率が極端に偏いていないかを定期的にチェックするだけで、大きな品質事故を防ぎやすくなります。
SECTION 06
実運用で必要なエラーハンドリングとフォールバック設計
本番環境でルーターを動かすなら、エラーハンドリングとフォールバックの設計は必須です。API の呼び出しには必ず失敗の可能性があり、単一モデルへの依存は障害時に全機能が止まるリスクを抱えます。
最低限組み込むべきエラー処理は以下の3つです。
- タイムアウト処理：モデルの応答が遅い場合に一定時間で打ち切る
- リトライ処理：レートリミットや一時的なエラー時に指数バックオフで再試行する
- フォールバック処理：指定モデルが利用不可の場合に代替モデルへ切り替える
フォールバックの設計では、上位から下位への切り替えを基本ラインにします。Opus が不調なら Sonnet へ、Sonnet も使えなければ Haiku へという降順のチェーンを組んでおけば、最低限の機能は維持できます。
逆に下位から上位へのフォールバックは慎重に設計してください。Haiku の代わりに Opus が呼ばれると、コストが想定外に跳ね上がる可能性があります。上位へのフォールバックには呼び出し回数の上限を設けておくのが安全です。
筆者の運用例では、リトライの回数は最大3回程度に留めています。それ以上リトライしても成功する可能性は低く、ユーザーの待ち時間だけが伸びる傾向がありました。リトライ上限を超えたらエラーを返し、ログに記録する設計にしておきます。
SECTION 07
ログの取り方と振り分け精度の改善サイクル
ルーターの運用は、導入して終わりではなく、ログを基に継続的に改善するものです。振り分けルールが適切かどうかは、実際のリクエストデータを見なければ判断できません。
ログに記録すべき項目は以下の通りです。
- リクエストの内容（プロンプトのハッシュやカテゴリラベル）
- 振り分け先のモデルと実際のレスポンス時間
- 出力に対する品質スコア（自動評価または人間レビューの結果）
ログが溜まったら、振り分けミスのパターンを分析します。Haiku に回したが品質が低かったケース、Opus に回したが実は Sonnet で十分だったケースを洗い出し、ルールの閾値を調整します。
筆者の運用例では、改善サイクルは週次〜隔週で回すのが現実的でした。毎日チューニングするほどの変化はなく、ある程度のサンプル数が溜まってから傾向を見るほうが、ノイズに振り回されずに済みます。
また、筆者は 「振り分けミス率」を1つの KPI として追跡する方法を採用しています。ミス率が一定以上に上がったら、ルールの見直しをトリガーする運用にしておくと、品質劣化を早期に検知しやすくなります。
SECTION 08
自作ルーター vs CCR（OSS）の選び方
ルーターを自作するか、CCR のような OSS を使うかは、チームの規模と運用の長期性で判断するのが合理的です。どちらにも明確なメリットとデメリットがあります。
自作のメリットは、振り分けロジックを完全にコントロールできることです。自社のタスク体系に合わせた細かいルール設計が可能で、外部の OSS への依存もありません。ただし、保守コストはすべて自分たちが負います。
自作する場合に見落としがちなコストは以下です。
- モデルのバージョンアップへの追従（新モデル追加時のルール更新）
- エッジケースの対応（想定外のリクエストパターンへの対処）
- 監視・アラートの構築（振り分け異常の検知と通知）
CCR のような OSS ルーターは初期構築のコストを大幅に下げられます。すでにエラーハンドリングやプロバイダ接続の仕組みが組み込まれていることが多く、導入してすぐに使い始められるのが強みです。
結論として、個人や少人数での開発なら CCR をそのまま活用し、チームで固有の要件がある場合は CCR を土台にカスタマイズするのが、保守コストと柔軟性のバランスが取れた選択です。最初から完璧なルーターを目指すより、小さく始めて実運用の中で育てていく姿勢が重要です。
SECTION 09
実運用で押さえておきたい設計のコツ
ルーターを本番に載せる前に、テスト環境で十分なリクエストパターンを流しておくことが大切です。開発中は気づかなかった振り分けの漏れが、本番の多様なリクエストで一気に表面化します。
CCR の config.json はルーターのルール部分だけを更新できる設計になっているため、設定変更時にアプリケーション全体を再起動せずに済む場合があります。
モデルのバージョンアップ時に注意すべき点は以下です。
- 既存ルールとの互換性確認（新モデルで出力フォーマットが変わっていないか）
- 品質スコアの再キャリブレーション（新モデルのほうが全体的にスコアが高い場合、閾値調整が必要）
- コスト単価の再計算（モデル更新で料金体系が変わる可能性）
複数のワークフローが同じルーターを共有する場合は、ワークフローごとにネームスペースを分けてログを取ると、振り分け精度の分析がしやすくなります。全体のログを一括で見ると、どのワークフローで問題が起きているのか特定しにくくなります。
最後に、ルーティングの効果測定は「コスト削減額」だけで判断しないことが重要です。レスポンス速度の改善、出力品質の安定化、運用負荷の軽減など、複数の軸で効果を見ることで、ルーターへの投資判断がより正確になります。
