Claude Code を 9Router に接続する作業は、設定を貼り付けるだけでは終わりません。クライアント、9Router の Provider、対象モデルの名前を一致させる必要があります。401、404、または「モデルを利用できない」が出たら、API key を何度も変える前に層ごとに確認します。
設定前に確認する3点
- 9Router サービスが起動しており、ローカル管理画面を開けること。
- 9Router に Provider を追加済みで、key と接続が正常であること。
- 9Router が OpenAI-compatible クライアント向けに公開している Base URL、API key、利用可能なモデルまたは Combo 名を控えること。
Claude Code が要求すべきなのは 9Router の Base URL だけです。どの Provider とモデルに送るかは 9Router のルールに任せます。導入の背景は 9Router 使用ガイドを参照してください。
推奨する接続順序
最初に 9Router で単一 Provider のテストルートを作り、Claude Code をそこへ向けます。単純な会話が成功してから fallback、複数アカウント、ローカルモデルを加えます。
設定時は次を確認します。
- Base URL が上流ベンダーではなく 9Router の OpenAI-compatible endpoint であること。
- API key が現在の 9Router インスタンスで発行されたものであること。
- Claude Code のモデル名が 9Router のモデル名または Combo 名と完全に一致すること。
- 環境変数や設定の変更後に、端末と Claude Code を再起動したこと。
上流 Provider の key を複数プロジェクトへ散在させないでください。key は 9Router に置き、Claude Code にはローカルルーターに必要な最小限の認証情報だけを持たせると、移行と無効化が容易です。
よくあるエラーの切り分け
401 または Unauthorized
まず要求がローカル 9Router に届いているかを確認し、その後 API key を確認します。管理画面にはログインできるのにクライアントだけが 401 なら、誤った key を使っているか、別インスタンスを指していることが多いです。
404 または endpoint not found
Base URL のパスを余分に書いた、または省いた可能性があります。/v1 を推測で付けず、9Router が現在表示する OpenAI-compatible のアドレスを使い、最小要求で検証してください。
model not found
9Router のモデル一覧を確認します。Provider 本来のモデル名、独自の別名、Combo 名は異なる場合があります。Claude Code にはルーターが公開する名前を指定します。
要求は送れるが常に fallback する
第1候補 Provider の状態、残高または上限、モデル権限、要求ログを確認します。fallback は保険であり、優先モデルが失敗する理由を修正する代わりにはなりません。
最小テスト設定を残す
複雑なルーティングを導入する前に、「Provider 1つ、モデル 1つ、fallback なし」の設定を保存します。問題が起きたらこの基準に戻ります。基準が正常ならルール側、基準も失敗するならネットワーク、認証、または Provider 側を確認します。
Claude Code 自体の導入、権限、プロジェクト環境が問題なら、Claude Code の複数プロジェクト記憶と Hooksも参照してください。
まとめ
9Router と Claude Code の接続では、Base URL をルーターに向け、モデル名をルーターに合わせ、上流のロジックをルーターへ集約します。「接続性—認証—モデル名—ルール」の順で確認すれば、多くの設定問題を避けられます。
切り分けやすい設定モデル
呼び出しの連鎖を Claude Code → 9Router endpoint → Provider → 実際のモデル の4層として考えます。クライアントがルーターへ届いたか、ルーターが認証を受け入れたか、ルールが Provider を選んだか、Provider がモデルを呼べるかを、各層で1つずつ確認します。ログとテストもこの4層で分けます。
たとえば Claude Code ではまず固定のモデル名を使い、9Router でその名前を1つの Provider にだけ結びます。安定してから Combo に変え、2つ目の Provider を追加します。Claude Code に複数の上流名を直接見せると、各プロジェクトに保守しにくい設定が増えます。
長いタスクではなく最小要求で検証する
設定を1層終えるたびに、低コストのテストを行います。
- 9Router のヘルス情報または管理画面で待受状態を確認する。
- ツール呼び出しのない単純な要求で API key とモデル名を確認する。
- Claude Code に現在のディレクトリの短い文章を説明させ、応答を確認する。
- その後にだけ、ファイル読み取り、テスト実行、長いコンテキスト、並列 Agent を試す。
長いタスクにはネットワーク、ツール権限、コンテキスト、再試行の変数が混ざります。最小要求はトラブルシュート用メモに残しておくと、更新や別PCでも使えます。
安定したルーティングルールの設計
「標準モデル」と「高コストモデル」を分けます。標準モデルは日常の質問、整形、低リスク変更に使い、複雑な推論、コードレビュー、長いコンテキストでは強いモデルを明示的に選びます。これにより費用が分かりやすくなり、どのタスクに上位モデルが必要かもログで見えます。
fallback の条件も保守的にします。ネットワークエラー、明確な上限エラー、Provider 障害では切替可能ですが、回答品質が期待より低いだけで複数 Provider を自動再試行すべきではありません。token 消費が増え、結果も再現しにくくなります。
配置と認証情報の安全チェックリスト
- アクセス制御なしで 9Router を公開インターネットに出さない。
DATA_DIR、バックアップ、ログには Provider 情報が含まれる可能性があるため、機密設定として扱う。- 上流 key をリポジトリ、スクリーンショット、Claude Code のプロジェクト説明に書かない。
- 更新前にバックアップし、最小要求で確認してから本番ルートを戻す。
FAQ：すべてのプロジェクトで 9Router を設定する必要がありますか？
通常はありません。クライアントレベルの環境変数や管理ツールで複数プロジェクトが1つの endpoint を共有できます。専用モデル、権限、課金分離が本当に必要なリポジトリだけでプロジェクト設定を使います。
FAQ：ローカルモデルが頻繁に fallback するのはなぜですか？
サービスログでメモリ不足、コンテキスト上限、並列待ち行列、モデル名の不一致を確認します。主ルートにする前に、短いプロンプトだけでなく実際のタスク長で継続的に検証してください。