Codex Router が動かない？トラブルシューティングと修正
Codex Router の問題の大半は原因が限られています：認証情報の欠落、プロバイダー未有効化、カタログの古さ、バックグラウンドサービスの停止、別チェックアウトによって書き込まれた設定。このページはそれらの問題と修正の索引で、リポジトリの docs/TROUBLESHOOTING.md から翻案しています。
ここから始める：doctor コマンド
すべてのトラブルシューティングは同じコマンドから始まります：
./bin/model-router codex doctor各 FAIL 行には的を絞った修正方法が含まれます。リポジトリ管理のファイル・設定・サービス状態だけを再構築する場合：
./bin/model-router codex doctor --fix認識済みの旧 Kimi ルーターが検出された場合はマイグレーションフラグを追加：
./bin/model-router codex doctor --fix --migrate-knownどちらのコマンドも認証情報値を出力しません。修復は未知のルーターオーナーを拒否します。doctor の各チェックの詳細は doctor の詳細をご覧ください。
よくある問題と修正
外部モデルがピッカーに出ない
対象プロバイダーは SHOW と ready の両方を報告する必要があります。./bin/providers、./bin/refresh-catalog、./bin/doctor を実行し、Codex を完全終了・再起動・新規タスク作成——ウィンドウを閉じるだけでは model_catalog_json は再読み込みされません。完全な手順：モデルが表示されない。
ルーティングモデルのサブエージェントが出ない
main を pull してもソースチェックアウトが更新されるだけです。ユーザー単位インストールに適用し、生成されたカスタムエージェントを検証します：
./bin/model-router codex update
./bin/model-router codex doctordoctor は Routed model agents に OK を報告するはずです。出なければ doctor --fix を実行し、Codex を再起動。
状態ディレクトリが別のチェックアウトに属する
doctor が状態所有権の失敗を報告した場合、インストールを実行していないクローンから実行しています。インストール状態を所有するチェックアウト経由で ./bin/model-router codex doctor --fix を実行します。記録されたオーナーが存在する限り、現在のチェックアウトへの所有権移行は、オーナー消失時か MODEL_ROUTER_ALLOW_FOREIGN_STATE=1 設定時にのみ行います。
Kimi OAuth が未準備
kimi login
./bin/model-router codex providers enable kimi-oauth
./bin/model-router codex doctorルーターは公式 Kimi CLI 認証情報を読み取り、クロスプロセスロック下で更新します。OAuth トークンを他の場所にコピーしないでください。
Windows が Grok OAuth CLI をブロック
grok --version が spawn UNKNOWN、“An Application Control policy has blocked this file,” または Smart App Control 通知を返す場合は、xAI API キーで grok-api プロバイダーを使用します。正確なコマンドは Windows ガイドへ。
API キー欠落・無効
非表示の set プロンプトを再実行し、状態を確認：
./bin/model-router codex provider-key deepseek set
./bin/model-router codex provider-key deepseek statusキーが指定システムに属することを確認：Kimi OAuth、Kimi Platform、DeepSeek、Anthropic、阿里云 plan、Z.ai coding キーはすべて独立・非互換の認証情報です。
プロバイダーがモデル ID を変更
プロバイダーの公式モデルリストエンドポイントとレジストリを比較：
./bin/discover-models deepseekディスカバリは読み取り専用です。レジストリリリース前に新発見モデルをローカルで使うには、./bin/curate-models deepseek で自分のマシン用にキュレーションします。
ルーティングスラッグが unrouted_model になる
モデル追加・改名後にピッカーだけが再構築され、バックグラウンドルーターが古いレジストリをメモリに保持している可能性があります。./bin/control service restart でサービスを再起動し、doctor を再実行してください。doctor がスキップされたユーザーモデルを報告したら、そのローカルキュレーション項目を修正または削除します。未知の provider/model はローカルで拒否され、ネイティブモデルと誤認して ChatGPT にプロンプトを送ることはありません。
古い chatgpt-web/* モデルが読み込まれない
非公式 ChatGPT Web ブラウザー自動化プロバイダーは、OpenAI アカウントの停止・永久 BAN のリスクがあるため削除されました。利用を停止し、./bin/curate-models chatgpt-web --remove <slug> で古いキュレーション項目を削除してください。更新後は安全にスキップされてルーティングされませんが、手動削除まで user-models.json に残ります。
ネイティブ GPT モデルが動かなくなった
一時的に Codex をネイティブベース URL に戻す：
./bin/model-router codex disableこれはマークされたブロックと現在のサービスだけを削除し、選択モデル・プロファイル・プロバイダー認証情報・ChatGPT ログインを保持します。ネイティブモデルが戻ったらルーターの健全性を確認し、サポートバンドルを作成。
別プロセスが 4200–4203 ポートを占有
lsof -nP -iTCP:4200 -iTCP:4201 -iTCP:4202 -iTCP:4203 -sTCP:LISTEN所有者と用途が分かるまでプロセスを終了しないでください。インストーラーは認識済みの旧リポジトリサービスだけを移行し、それ以外は競合で停止します。
バックグラウンドサービスが停止
launchctl print "gui/$(id -u)/io.github.codex-router"
./bin/model-router codex doctor --fixLinux は systemctl --user status codex-router.service、Windows は Get-ScheduledTask -TaskName "Codex Router"。リポジトリをインストール時の絶対パスに保ち、移動したら新しいパスからセットアップを再実行します。
Windows では start と restart が schtasks を呼ぶ前にスケジュールタスクの存在を確認するようになりました。タスクがない場合は、schtasks.exe 自身のエラーや誤った {"state":"running"} ではなく、タスク名と service.mjs install、doctor --fix を示すメッセージが表示されます。終了時に状態は変更されません。
初回インストールが 300 秒でタイムアウトした
モデルカタログが大きい場合、サービスとランチャーが正しくインストールされていても、LiteLLM の最初のコールドスタートがインストーラーの 5 分間のヘルス待機を超えることがあります。現在の main は再試行可能な終了コード 75（EX_TEMPFAIL）を返し、サービス、ランチャー、クライアント設定を削除せず保持します。上記のプラットフォーム別手順でサービスを確認し、正常になるまで待ってから ./bin/model-router codex doctor --fix を実行してください。クラッシュループまたはランチャー欠落が確認された場合は、引き続きインストール失敗としてロールバックされます。
更新に失敗
./bin/model-router codex rollback更新は、追跡ファイルへの編集（未追跡ファイルはブロックしません。--force で追跡編集を破棄できます）、非 main 開発ブランチ、未知のオリジン URL を、ローカル作業を上書きせず拒否します。旧版マイグレーションのロールバックは別です：./bin/migrate rollback。
セッションがコンテキストウィンドウを超えたのに圧縮されない
Codex は各レスポンスが報告する input_tokens から自動圧縮のタイミングを決めます。大きなプロンプトに input_tokens: 0 で応答するプロバイダーはカウンターを停滞させ、コンテキストバーがほぼ空に見えたまま、プロバイダーがターンを拒否するまで続きます。ルーターは、大きなプロンプトを明らかに運んだリクエストに対してルーティング応答がゼロプロンプトトークンを明示的に報告した場合にのみ、送信したばかりのプロンプトの推定値を代用します。
置換は隠さず記録されます：使用イベントはプロバイダー自身の数値を保持しつつ estimatedInputTokens を追加し、ルーターはそのターンに estimated-input-tokens=<count> をログに記録します。状態ディレクトリの usage-events.jsonl で数えられます：
grep -c estimatedInputTokens "$CODEX_HOME/codex-router/usage-events.jsonl"ゼロトークン応答はプロバイダーに報告してください——ソースを修正できるのは彼らだけです。Codex でプロバイダー自身の数値を再び見るには、サービス環境で CODEX_ROUTER_ZERO_INPUT_ESTIMATE=0 を設定します。
Responses WebSocket が接続できない
現行リリースは Responses WebSocket v2 アップグレードを受け付けます。401 は通常、Codex が古い管理 URL を使っている印です。./bin/doctor --fix を実行し、Codex を完全終了して再起動してください。426 に対応済みの OpenAI-Beta: responses_websockets=2026-02-06 ヒントが含まれる場合、試行した WebSocket 契約が一致せず Codex は HTTP にフォールバックします。プロバイダーエラーは通常の Responses エラーイベントとして返ります。
Voice モードが未対応の /v1/live ルートを報告
Codex Voice は Responses API とは別のネイティブリアルタイムエンドポイントを使用します。更新後に ./bin/enable を再実行し、Codex を完全終了・再起動して管理対象のリアルタイムオーバーライドを有効にします。
アンインストールでファイルが残る
これは意図的です。./bin/uninstall はアクティブな統合とバックグラウンドサービスのみを削除します。状態ディレクトリには認証情報・ログ・カタログキャッシュ・インストール履歴・ロールバックスナップショットが含まれる場合があります。削除前に手動で確認してください。
サポートバンドルの作成
./bin/support-bundle生成される mode-600 JSON には、バージョン、doctor チェック、サービス状態、プロバイダー存在、設定所有権、ファイルメタデータが含まれ、認証情報値・プロンプト・レスポンス・ログ内容は含まれません。旧 --include-logs はスクリプト互換性のためだけに残る非推奨の no-op です。過去ログには後でローテーション・削除された認証情報が含まれ得るためです。ツールが bundle を自動アップロードすることはありません。
それでも解決しない場合
Codex Router リポジトリ でイシューを開き、脱敏済みサポートバンドルを添付します。doctor 出力と正確なエラーテキストを含めてください。ただし完全な管理 URL や認証情報は絶対に貼り付けないでください。