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 で自分のマシン用にキュレーションします。
ネイティブ GPT モデルが動かなくなった
一時的に Codex をネイティブベース URL に戻す：
./bin/model-router codex disableこれはマークされたブロックと現在のサービスだけを削除し、選択モデル・プロファイル・プロバイダー認証情報・ChatGPT ログインを保持します。ネイティブモデルが戻ったらルーターの健全性を確認し、サポートバンドルを作成。
別プロセスが 4100–4103 ポートを占有
lsof -nP -iTCP:4100 -iTCP:4101 -iTCP:4102 -iTCP:4103 -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"。リポジトリをインストール時の絶対パスに保ち、移動したら新しいパスからセットアップを再実行します。
更新に失敗
./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 を設定します。
WebSocket 警告後の HTTP フォールバック
これは期待どおりです。ルーターはオプションの Responses WebSocket アップグレードを拒否し、現在の Codex は圧縮 HTTP にフォールバックします。警告だけではモデルリクエストの失敗ではありません。
Voice モードが未対応の /v1/live ルートを報告
Codex Voice は Responses API とは別のネイティブリアルタイムエンドポイントを使用します。更新後に ./bin/enable を再実行し、Codex を完全終了・再起動して管理対象のリアルタイムオーバーライドを有効にします。
アンインストールでファイルが残る
これは意図的です。./bin/uninstall はアクティブな統合とバックグラウンドサービスのみを削除します。状態ディレクトリには認証情報・ログ・カタログキャッシュ・インストール履歴・ロールバックスナップショットが含まれる場合があります。削除前に手動で確認してください。
サポートバンドルの作成
./bin/support-bundle生成される mode-600 JSON には、バージョン、doctor チェック、サービス状態、プロバイダー存在、設定所有権、ファイルメタデータが含まれます——認証情報値・プロンプト・レスポンス・ログ内容は含まれません。ログコンテキストが本当に必要な場合のみ ./bin/support-bundle --include-logs を使い、共有前に出力を確認し、自動アップロードはしないでください。
それでも解決しない場合
Codex Router リポジトリ でイシューを開き、脱敏済みサポートバンドルを添付します。doctor 出力と正確なエラーテキストを含めてください。ただし完全な管理 URL や認証情報は絶対に貼り付けないでください。