9Router トラブルシューティング完全ガイド：よくあるエラー8種の原因と対処法-酒店常州论坛

9Router トラブルシューティング完全ガイド：よくあるエラー8種の原因と対処法

【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40+ providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router

本記事は、9Router（オープンソースのAIエンドポイント・プロキシ）を利用中に遭遇する代表的なエラー——空レスポンス、レート制限、OAuthトークン期限切れ、接続拒否、モデル未発見、応答遅延、APIキー無効、コスト高騰——の原因と解決策を体系的に解説する実践ガイドです。Dashboard操作・CLIコマンド・APIリクエストの3層から対処手順を示し、あわせてリポジトリ内のソースコード（open-sse/services/tokenRefresh.js、open-sse/services/usage/など）で裏付けされた動作原理を確認できます。本記事を読み終えると、9Routerの障害を自己診断し、Comboフォールバック・クォータ監視・トークン自動更新を駆使してダウンタイムを最小化できるようになります。

1. はじめに：9Routerの動作モデルとエラー分類

9Routerは、Claude Code・Codex・Cursor・Cline・CopilotなどのAI CLIツールと、40以上のプロバイダー（無料・サブスク・低価格API）をつなぐ統合エンドポイントです。クライアントはローカルプロキシ（既定ポート20128）またはクラウドエンドポイントに向けてリクエストを送り、9Routerがモデルルーティング・クォータ管理・OAuth認証・トークン自動更新を一手に引き受けます。

この構成ゆえに、エラーは大きく次の3層に分類できます。

層	代表的なエラー	原因の主な所在
クライアント層	ECONNREFUSED、Invalid API key	起動状態、ポート、設定値
プロキシ層	Rate limit exceeded、Token expired	クォータ管理、OAuth自動更新
プロバイダー層	Language model did not provide messages	上流APIの利用不可・クォータ枯渇

以降の章では、公式トラブルシューティングドキュメント（gitbook/content/ja/troubleshooting.md）の8つの問題を順に取り上げます。

2. "Language model did not provide messages"：空レスポンスが返る

症状と原因

リクエストが空レスポンス、またはエラーメッセージを伴わず失敗します。主な原因は次の3つです。

プロバイダーのクォータが消費済み（無料枠・サブスク枠の使い切り）
APIキーが無効または期限切れ
モデルが利用不可（モデルIDの誤り、プロバイダー側の障害）

対処手順

1. クォータ状況を確認

Dashboard → Providers → クォータトラッカーを表示

クォータが消費済みなら、リセットを待つかプロバイダーを切り替えます。9Routerのクォータ追跡はプロバイダーごとに実装されており、たとえばClaudeのクォータ取得処理（open-sse/services/usage/claude.js）では、five_hour（5時間セッション）・seven_day（週次）・モデル別週次クォータの3種類を取得し、それぞれのresetAt（リセット時刻）を返します。つまり「いつリセットされるか」を画面で確認できるのは、こうした上流APIのレスポンスをパースして表示しているためです。

2. コンボフォールバックを使用

Dashboard → Combos → フォールバックチェーンを作成 例: cc/claude-opus → glm/glm-4.7 → if/kimi-k2

Comboとは、優先度順に並べたモデルのフォールバックチェーンです。先頭のモデルがクォータ枯渇やエラーで失敗すると、自動的に次のモデルへ切り替わります（詳細はgitbook/content/ja/features/combos.md）。

3. プロバイダー接続を確認

Dashboard → Providers → 必要に応じて再接続

3. レート制限："Rate limit exceeded" / "Too many requests"

症状と原因

上流プロバイダーからレート制限エラーが返ります。原因は主に次の3つです。

サブスクリプションのクォータ枯渇（5時間/日次/週次の制限）
APIレート制限に到達
同時リクエストが多すぎる

対処手順

1. リセット時間を確認

Dashboard → Quota Tracking → リセットカウントダウンを表示

2. 低価格階層へ切り替え

使用: glm/glm-4.7 (100万トークンあたり$0.6) minimax/MiniMax-M2.1 (100万トークンあたり$0.20)

3. フォールバックコンボを追加

Dashboard → Combos → バックアップモデルを追加 優先: cc/claude-opus (サブスクリプション) バックアップ: glm/glm-4.7 (低価格) 緊急時: if/kimi-k2 (無料)

実装の補足：クォータ取得API自体が429を返した場合、9RouterはOAuthの使用量ポーリングをクールダウンさせる処理を実装しています（open-sse/services/usage/claude.js）。つまり上流のレート制限は、そのままクライアントへのエラーとなるだけでなく、内部の監視ループにも影響するため、まずはリクエスト頻度そのものを落とすことが有効です。

4. OAuthトークン期限切れ："Unauthorized" / "Token expired"

症状と原因

OAuthトークンが期限切れ（自動更新に失敗した場合）
プロバイダーセッションが無効化された
更新中のネットワーク問題

対処手順

1. 自動更新（デフォルト）

9Routerはトークンを自動更新します。30秒待ってから再試行してください。この自動更新は、プロバイダーごとのリフレッシュ関数群として実装されており、Claude・Codex・Gemini・Kimi・Kiro・iFlow・GitHub・Copilot・Trae・Zed・Windsurf・Qwen・X（旧Twitter）など16種類以上のリフレッシュ処理がopen-sse/services/tokenRefresh.jsに集約されています。各関数はOAUTH_ENDPOINTSとREFRESH_LEAD_MS（リフレッシュを開始する期限前リード時間）を参照して動作します（open-sse/config/appConstants.js）。

2. 手動で再接続

Dashboard → Providers → [プロバイダー名] → Reconnect → OAuthフローを再度完了

3. プロバイダーステータスを確認

Claude Code、Codexなど、プロバイダー側のサービスがオンラインであることを確認します。自動更新が失敗し続ける場合は、上流側でセッションが無効化されている可能性が高いため、Reconnectによる再認証が最短の解決策です。

5. 高コスト：予期しない使用量・請求額

症状と原因

不必要に高価なモデルを使用している
低価格階層へのフォールバックがない
大きなコンテキストウィンドウを送り続けている

対処手順

1. 使用統計を確認

Dashboard → Usage Stats → トークン消費量を表示 → 高コストモデルを特定

2. より安いモデルへ切り替え

置換: cc/claude-opus (月$20〜100サブスクリプション) へ: glm/glm-4.7 (100万トークンあたり$0.6) minimax/MiniMax-M2.1 (100万トークンあたり$0.20)

3. 無料階層を使用

if/kimi-k2-thinking (無料) qw/qwen3-coder-plus (無料) kr/claude-sonnet-4.5 (無料) gc/gemini-3-flash-preview (月18万無料)

4. プロンプトを最適化

コンテキストサイズを削減（メッセージ履歴のトリミング）
長い応答にはストリーミングを使用
一般的なプロンプトをキャッシュ

実装の補足：9Routerには、RTK（Reasoning Token Kill）機能としてopen-sse/rtk/配下にトークン削減フィルタ（open-sse/rtk/index.js）が実装されており、リクエストを送信する前に推論トークン等の冗長部分を削ることで、実質的なトークン消費を減らす仕組みがあります。高コスト対策の一環として、CLIツール側のコンテキスト剪定機能とあわせて利用できます。

6. Connection Refused："ECONNREFUSED" / "Cannot connect to localhost:20128"

症状と原因

クライアントがローカルプロキシに接続できません。

9Routerが起動していない
ポート20128がブロックされている
ファイアウォールが接続をブロック

対処手順

1. 9Routerを起動

9router

ダッシュボードが http://localhost:3000 で開くはずです。なお、APIプロキシの既定ポートは20128で、これは.env.exampleのPORT=20128として明示されています。

2. ポート20128を確認

# ポートがリッスンしているか確認 lsof -i :20128 # またはWindowsで netstat -ano | findstr :20128

3. ファイアウォールを確認

macOS：システム設定 → ネットワーク → ファイアウォール
Windows：Windows Defenderファイアウォール → アプリを許可
Linux：sudo ufw allow 20128

4. クラウドエンドポイントを使用

localhostが機能しない場合（例：Cursor IDEが別コンテナ/別ホストから接続する場合）：

Endpoint: https://9router.com/v1

実装の補足：プロキシの待ち受けポートは環境変数PORTで制御されます（.env.example）。ポートを変更した場合は、クライアント側のBase URLも同じポートに合わせる必要があります。

7. ダッシュボードが開かない：localhost:3000 にアクセスできない

症状と原因

ポート3000がすでに使用中
9Routerがクラッシュした
ブラウザキャッシュの問題

対処手順

1. 9Routerが実行中か確認

# プロセスを確認 ps aux | grep 9router # ポート3000を確認 lsof -i :3000

2. 競合するプロセスを終了

# macOS/Linux lsof -ti:3000 | xargs kill -9 # Windows netstat -ano | findstr :3000 taskkill /PID <PID> /F

3. 9Routerを再起動

# 停止 pkill -f 9router # 起動 9router

4. ブラウザキャッシュをクリア

Chrome：Ctrl+Shift+Delete → キャッシュをクリア
シークレットモードを試す

5. ファイアウォール設定を確認

ポート3000がブロックされていないことを確認します。

実装の補足：ダッシュボードはNext.jsアプリとして実装されており（src/app）、APIプロキシとは別のポートで配信される構成です。.env.exampleのBASE_URL=http://localhost:20128からも分かるように、ダッシュボード（ポート3000）とAPIプロキシ（ポート20128）は役割が分かれており、両方が起動していることが正常動作の前提です。

8. モデルが見つからない："Model not found" / "Invalid model"

症状と原因

プロバイダーが接続されていない
モデルIDのタイポ
プロバイダーが非アクティブ

対処手順

1. プロバイダー接続を確認

Dashboard → Providers → ステータスを確認（緑 = アクティブ）

2. モデルID形式を確認

正しい: cc/claude-opus-4-5-20251101 誤り: claude-opus-4-5-20251101 形式: [provider-prefix]/[model-name]

モデルIDはプロバイダープレフィックス＋スラッシュ＋モデル名という形式です。プレフィックス（cc=Claude Code、glm=GLM、if=iFlow、kr=Kiro、gc=Gemini CLI、qw=Qwenなど）を省略すると「Invalid model」になります。

3. 利用可能なモデルを一覧表示

curl http://localhost:20128/v1/models \ -H "Authorization: Bearer your-api-key"

4. プロバイダーを再接続

Dashboard → Providers → [Provider] → Reconnect

実装の補足：プロバイダーのモデル定義はopen-sse/providers/registry/にプロバイダーごとのファイル（例：open-sse/providers/registry/claude.js、open-sse/providers/registry/glm.js）として登録されており、プレフィックスとモデル名の対応関係はこのレジストリで管理されています。/v1/modelsエンドポイントはこのレジストリを参照して一覧を返すため、モデルが一覧に出ない場合はプロバイダー接続そのものを見直すのが先決です。

9. 応答が遅い：リクエストのタイムアウト

症状と原因

プロバイダーのレイテンシ
ネットワーク問題
大きなコンテキスト/レスポンス
プロバイダーのレート制限

対処手順

1. プロバイダーステータスを確認

Dashboard → Providers → レイテンシ統計を表示

2. 高速モデルへ切り替え

高速: cc/claude-haiku-4-5 (HaikuはOpusより高速) gc/gemini-3-flash-preview qw/qwen3-coder-flash

3. ストリーミングを使用

{ "model": "cc/claude-opus-4-5", "messages": [...], "stream": true }

4. ネットワークを確認

# レイテンシをテスト ping api.anthropic.com ping api.openai.com

5. コンテキストサイズを削減

メッセージ履歴をトリミング
短いプロンプトを使用
CLIツールでコンテキストの剪定を有効化

実装の補足：stream: trueを指定した場合、9Routerは上流からのSSE（Server-Sent Events）ストリームを逐次クライアントへ中継する実装になっています（open-sse/utils/stream.js、open-sse/handlers/chatCore/streamingHandler.js）。最初のトークンが届き次第表示が始まるため、体感待ち時間が大幅に短縮されます。

10. APIキー無効："Invalid API key" / "Authentication failed"

症状と原因

間違ったAPIキーをコピーした
APIキーが期限切れ
APIキーが生成されていない

対処手順

1. APIキーを再生成

Dashboard → Settings → API Keys → Generate New Key → 新しいキーをコピーして使用

2. キー形式を確認

正しい: 9r_xxxxxxxxxxxxxxxxxxxxxxxx 誤り: 9r_プレフィックスがない

9RouterのAPIキーは必ず9r_プレフィックスで始まります。プレフィックスがない場合、9Routerのキーではなく別のサービス（OpenAI等）のキーが設定されている可能性が高いです。

3. CLI設定でキーを確認

# Cursor Settings → Models → OpenAI API Key # Cline Settings → API Key # 環境変数 export OPENAI_API_KEY="9r_your_key"

4. APIキーをテスト

curl http://localhost:20128/v1/models \ -H "Authorization: Bearer 9r_your_key"

正常なキーであればモデル一覧がJSONで返り、無効なキーであれば認証エラーが返ります。

実装の補足：APIキーによる認証は、環境変数REQUIRE_API_KEYで必須化を制御できます（.env.example）。また、プロキシのAPIキー検証はAPI_KEY_SECRETをシードにした署名・検証ロジックと連動しているため、API_KEY_SECRETを変更した場合は再生成したキーでクライアント側を更新する必要があります。

11. さらなるヘルプが必要な場合

GitHub Issues：バグ報告・機能要望はGitHub Issuesへ
公式ドキュメント：最新のドキュメント（gitbook/content/ja/index.md）を参照
FAQ：faq.md

トラブルシューティングの基本原則は「エラーを層で切り分ける」ことです。クライアント設定（APIキー・モデルID・Base URL）→ プロキシ状態（ポート・プロセス・クォータ）→ 上流プロバイダー（レート制限・セッション）の順に確認すれば、大半の問題は数分で切り分けられます。そして、Comboフォールバックチェーンとクォータ監視を常時有効にしておくことで、単一プロバイダー起因の障害を未然に吸収できる構成を維持することが、9Router運用の最大のコツです。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析