Codex Router故障排查清單從doctor診斷到rollback回滾的15個常見問題【免費下載鏈接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.項目地址: https://gitcode.com/gh_mirrors/co/codex-router本文是一份Codex Router 故障排查清單Codex Router 是一個本地模型路由器讓 Codex 客戶端免改造直連 Kimi、DeepSeek、xAI 等外部模型。當你遇到服務不啟動、模型消失、401 報錯或更新失敗時跟著這份從doctor診斷到rollback回滾的 15 條清單可以快速把路由環(huán)境恢復健康。一、30 秒上手故障排查三步路徑Codex Router 把診斷—修復—回滾做成了三條命令先記住這條主線診斷./bin/model-router codex doctor—— 每個FAIL都附帶一條針對性修復建議修復./bin/doctor --fix—— 只重建倉庫托管的文件、配置與服務狀態(tài)不打印任何憑據(jù)值?回滾./bin/rollback—— 更新出問題的一鍵退回上一穩(wěn)定版本 如果 doctor 報告檢測到舊版 Kimi 路由器用./bin/doctor --fix --migrate-known遷移修復會拒絕未知歸屬的路由器避免誤傷其他工具。完整條目見官方文檔 docs/TROUBLESHOOTING.md。二、服務與狀態(tài)類問題1–4問題 1后臺服務停了路由不在一切外部模型都會失敗。各平臺確認方式macOSlaunchctl print gui/$(id -u)/io.github.codex-routerLinuxsystemctl --user status codex-router.serviceWindowsGet-ScheduledTask -TaskName Codex Router?? Windows 上路由以無窗口方式運行沒看到窗口不代表掛了去看狀態(tài)目錄里的router.log。修復./bin/doctor --fix。問題 2端口 4200–4203 被其他進程占用用lsof -nP -iTCP:4200-4203 -sTCP:LISTEN或 PowerShell 的Get-NetTCPConnection找到占用者。先確認進程歸屬再決定處理不要上來就殺進程——安裝器只會遷移被識別的舊版服務其余情況直接報沖突并停下。問題 3狀態(tài)目錄屬于另一個克隆doctor 報 state ownership 失敗說明你從一個沒有執(zhí)行安裝的克隆目錄運行了命令。安全做法是讓擁有已安裝狀態(tài)的克隆去修復./bin/model-router codex doctor --fix確需把歸屬轉移到當前克隆時設置MODEL_ROUTER_ALLOW_FOREIGN_STATE1再跑上面的命令記錄的所有者仍然健在時它只在歸屬方消失后才轉移。問題 4新原生模型如 GPT-7沒出現(xiàn)在選擇器永遠不需要卸載。路由合并了原生 外部目錄檢測到賬號目錄或 Codex 可執(zhí)行文件指紋漂移會自動重發(fā)布。但model_catalog_json只在 Codex 啟動時讀一次——必須完全退出并重開 Codex關窗口不算。若日志提示 resolved Codex CLI is older than...是 PATH 里有個更舊的codex排在前面用CODEX_BIN/path/to/codex ./bin/refresh-catalog指向正確版本。三、模型與路由類問題5–8問題 5外部模型沒出現(xiàn)在模型選擇器按順序跑三件套./bin/providers→./bin/refresh-catalog→./bin/doctor。目標 provider 必須同時顯示SHOW和ready沒啟用就用./bin/providers enable PROVIDER打開。之后完全退出重開 Codex再開一個新任務。想直接看 Codex 啟動時加載了什么codex debug models。問題 6路由模型 Agent 沒生成git pull只更新源碼克隆還需應用到你的用戶級 Codex 安裝./bin/model-router codex update ./bin/model-router codex doctordoctor 應報告Routed model agents為OK否則./bin/model-router codex doctor --fix。生成的個人 Agent 定義存放在~/.codex/agents/。問題 7廠商改了模型 ID / 想用新發(fā)現(xiàn)的模型./bin/discover-models deepseek只做發(fā)現(xiàn)、不改注冊表。想在本機先用起來./bin/curate-models deepseek條目會寫入狀態(tài)目錄的user-models.json含上下文窗口、圖像支持等元數(shù)據(jù)后續(xù)官方注冊表上架同模型會自動跳過。正式進注冊表則需能力元數(shù)據(jù) 覆蓋文本/流式/工具/壓縮的計費實測./bin/test-model provider/model --live --yes。問題 8會話總是過早壓縮、干不了幾輪活早期整理的模型沿用了保守默認contextWindow: 131072百萬級上下文的模型會在 11 萬 token 就被壓。對比廠商目錄./bin/discover-models PROVIDER --json然后修正user-models.json里的contextWindow和autoCompact約為窗口 85%再./bin/install并重啟服務。四、憑據(jù)與登錄類問題9–11問題 9Kimi OAuth 沒就緒三步kimi login→./bin/providers enable kimi-oauth→./bin/doctor。路由只讀官方 Kimi CLI 存放在~/.kimi-code下的憑據(jù)并在跨進程鎖下刷新——不要把 OAuth token 拷進 Codex 配置、API key 文件或環(huán)境變量。問題 10API Key 缺失或 401用./bin/provider-key kimi-api set輸入隱藏回車后回報字符數(shù)粘貼重復會被提示。?? Kimi Code OAuth、Kimi Platform、DeepSeek、Anthropic、阿里云 Model Studio 計劃、Z.ai 編碼計劃的 key互不通用——一條路由 401通常是存了另一條路由的 key。新 key 下一次請求即生效無需重啟服務。問題 11Windows 攔截了 Grok OAuth CLI先跑grok --version驗證 CLI 本身能跑但 doctor 仍報 blocked多半是舊版選了無擴展名 shim先升級。若報spawn UNKNOWN或 Smart App Control 提示保持安全策略開啟沒有安全的單應用豁免改用 API key 路由./model-router.ps1 codex provider-key grok-api set ./model-router.ps1 codex providers enable grok-apiOAuth 會話不是永久解法——token 到期時路由會再次調用被攔截的 CLI會話最終停止刷新。五、更新、回滾與支持12–15問題 12原生 GPT 請求 502 連接超時報錯含 timed out connecting to chatgpt.com 說明是網(wǎng)絡路徑問題不是憑據(jù)也不是模型。連接階段上限 3 秒、重試預算約 3 倍該值還到用戶手里說明整個預算內全部嘗試失敗。依次檢查本機到同主機的連通性有線/Wi?Fi 兩條路徑分開測、DNS 是否正常、router.log里UND_ERR_CONNECT_TIMEOUT是否成簇出現(xiàn)。臨時想回到原生./bin/disable只移除托管塊與當前服務保留所選模型、配置與登錄。問題 13Agent 任務中途無聲停止上游 200 但無文本、無工具調用的空回復在 Codex 眼里就是模型沒說話于是記錄為已完成輪次。路由內置空回復防護整包持有響應直到確認有內容否則丟棄并重試一次再空則返回明確的502 empty_completion絕不靜默成功。重試輪次會標記在usage-events.jsonl的emptyCompletionRetried: true持續(xù)出現(xiàn)說明該報給上游廠商。問題 14更新失敗如何回滾更新器失敗時自動還原到上一修訂版回滾引用維護在refs/codex-router/rollback邏輯見 src/update.mjs。手動回滾./bin/rollback注意更新會拒絕跟蹤文件的本地編輯、非main分支和未知 origin未跟蹤文件不阻塞--force只丟棄跟蹤文件編輯。舊版遷移的回滾是獨立命令./bin/migrate rollback。問題 15提交問題前先造一個 support bundle./bin/support-bundle生成 mode 600 的 JSON版本、doctor 檢查結果、服務狀態(tài)、provider 存在性、文件元數(shù)據(jù)。憑據(jù)值、提示詞、響應內容與日志全文一律排除且工具絕不會自動上傳實現(xiàn)見 src/support-bundle.mjs。六、15 個問題速查表#癥狀首選動作1后臺服務停了./bin/doctor --fix2端口 4200–4203 被占先查進程歸屬勿盲目殺3狀態(tài)目錄歸屬沖突在擁有方克隆跑doctor --fix4新原生模型不顯示完全退出重開 Codex5外部模型消失providers→refresh-catalog→doctor6路由 Agent 缺失model-router codex update7模型 ID 變更discover-models/curate-models8過早壓縮修正contextWindow后重裝9Kimi OAuth 未就緒kimi login 啟用 provider10API key 401核對 key 歸屬系統(tǒng)后重設11Windows 攔截 Grok升級或切換 grok-api12原生 502 超時測網(wǎng)絡路徑./bin/disable兜底13中途靜默停止查emptyCompletionRetried14更新失敗./bin/rollback15要提 issue./bin/support-bundle七、修復后如何驗證恢復./bin/status查看脫敏后的運行狀態(tài)可安全分享自動隱去本地能力 URL控制中心 Dashboard 的Service Health區(qū)應顯示 Router / Gateway 均 ReadyTraffic 圖表恢復出數(shù)打開 Codex 新任務確認選擇器里目標模型可用相關模塊與文檔 官方故障排查手冊docs/TROUBLESHOOTING.md doctor 檢查項實現(xiàn)src/doctor.mjs 更新與回滾邏輯src/update.mjs 支持包生成src/support-bundle.mjs 路由原理請求流向四件套docs/HOW-IT-WORKS.md遇到本文未覆蓋的報錯先跑一遍doctor把帶Fix:行的輸出和 support bundle 一起提交通常就能快速定位?！久赓M下載鏈接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.項目地址: https://gitcode.com/gh_mirrors/co/codex-router創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Codex Router故障排查清單：從doctor診斷到rollback回滾的15個常見問題
Codex Router故障排查清單從doctor診斷到rollback回滾的15個常見問題【免費下載鏈接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.項目地址: https://gitcode.com/gh_mirrors/co/codex-router本文是一份Codex Router 故障排查清單Codex Router 是一個本地模型路由器讓 Codex 客戶端免改造直連 Kimi、DeepSeek、xAI 等外部模型。當你遇到服務不啟動、模型消失、401 報錯或更新失敗時跟著這份從doctor診斷到rollback回滾的 15 條清單可以快速把路由環(huán)境恢復健康。一、30 秒上手故障排查三步路徑Codex Router 把診斷—修復—回滾做成了三條命令先記住這條主線診斷./bin/model-router codex doctor—— 每個FAIL都附帶一條針對性修復建議修復./bin/doctor --fix—— 只重建倉庫托管的文件、配置與服務狀態(tài)不打印任何憑據(jù)值?回滾./bin/rollback—— 更新出問題的一鍵退回上一穩(wěn)定版本 如果 doctor 報告檢測到舊版 Kimi 路由器用./bin/doctor --fix --migrate-known遷移修復會拒絕未知歸屬的路由器避免誤傷其他工具。完整條目見官方文檔 docs/TROUBLESHOOTING.md。二、服務與狀態(tài)類問題1–4問題 1后臺服務停了路由不在一切外部模型都會失敗。各平臺確認方式macOSlaunchctl print gui/$(id -u)/io.github.codex-routerLinuxsystemctl --user status codex-router.serviceWindowsGet-ScheduledTask -TaskName Codex Router?? Windows 上路由以無窗口方式運行沒看到窗口不代表掛了去看狀態(tài)目錄里的router.log。修復./bin/doctor --fix。問題 2端口 4200–4203 被其他進程占用用lsof -nP -iTCP:4200-4203 -sTCP:LISTEN或 PowerShell 的Get-NetTCPConnection找到占用者。先確認進程歸屬再決定處理不要上來就殺進程——安裝器只會遷移被識別的舊版服務其余情況直接報沖突并停下。問題 3狀態(tài)目錄屬于另一個克隆doctor 報 state ownership 失敗說明你從一個沒有執(zhí)行安裝的克隆目錄運行了命令。安全做法是讓擁有已安裝狀態(tài)的克隆去修復./bin/model-router codex doctor --fix確需把歸屬轉移到當前克隆時設置MODEL_ROUTER_ALLOW_FOREIGN_STATE1再跑上面的命令記錄的所有者仍然健在時它只在歸屬方消失后才轉移。問題 4新原生模型如 GPT-7沒出現(xiàn)在選擇器永遠不需要卸載。路由合并了原生 外部目錄檢測到賬號目錄或 Codex 可執(zhí)行文件指紋漂移會自動重發(fā)布。但model_catalog_json只在 Codex 啟動時讀一次——必須完全退出并重開 Codex關窗口不算。若日志提示 resolved Codex CLI is older than...是 PATH 里有個更舊的codex排在前面用CODEX_BIN/path/to/codex ./bin/refresh-catalog指向正確版本。三、模型與路由類問題5–8問題 5外部模型沒出現(xiàn)在模型選擇器按順序跑三件套./bin/providers→./bin/refresh-catalog→./bin/doctor。目標 provider 必須同時顯示SHOW和ready沒啟用就用./bin/providers enable PROVIDER打開。之后完全退出重開 Codex再開一個新任務。想直接看 Codex 啟動時加載了什么codex debug models。問題 6路由模型 Agent 沒生成git pull只更新源碼克隆還需應用到你的用戶級 Codex 安裝./bin/model-router codex update ./bin/model-router codex doctordoctor 應報告Routed model agents為OK否則./bin/model-router codex doctor --fix。生成的個人 Agent 定義存放在~/.codex/agents/。問題 7廠商改了模型 ID / 想用新發(fā)現(xiàn)的模型./bin/discover-models deepseek只做發(fā)現(xiàn)、不改注冊表。想在本機先用起來./bin/curate-models deepseek條目會寫入狀態(tài)目錄的user-models.json含上下文窗口、圖像支持等元數(shù)據(jù)后續(xù)官方注冊表上架同模型會自動跳過。正式進注冊表則需能力元數(shù)據(jù) 覆蓋文本/流式/工具/壓縮的計費實測./bin/test-model provider/model --live --yes。問題 8會話總是過早壓縮、干不了幾輪活早期整理的模型沿用了保守默認contextWindow: 131072百萬級上下文的模型會在 11 萬 token 就被壓。對比廠商目錄./bin/discover-models PROVIDER --json然后修正user-models.json里的contextWindow和autoCompact約為窗口 85%再./bin/install并重啟服務。四、憑據(jù)與登錄類問題9–11問題 9Kimi OAuth 沒就緒三步kimi login→./bin/providers enable kimi-oauth→./bin/doctor。路由只讀官方 Kimi CLI 存放在~/.kimi-code下的憑據(jù)并在跨進程鎖下刷新——不要把 OAuth token 拷進 Codex 配置、API key 文件或環(huán)境變量。問題 10API Key 缺失或 401用./bin/provider-key kimi-api set輸入隱藏回車后回報字符數(shù)粘貼重復會被提示。?? Kimi Code OAuth、Kimi Platform、DeepSeek、Anthropic、阿里云 Model Studio 計劃、Z.ai 編碼計劃的 key互不通用——一條路由 401通常是存了另一條路由的 key。新 key 下一次請求即生效無需重啟服務。問題 11Windows 攔截了 Grok OAuth CLI先跑grok --version驗證 CLI 本身能跑但 doctor 仍報 blocked多半是舊版選了無擴展名 shim先升級。若報spawn UNKNOWN或 Smart App Control 提示保持安全策略開啟沒有安全的單應用豁免改用 API key 路由./model-router.ps1 codex provider-key grok-api set ./model-router.ps1 codex providers enable grok-apiOAuth 會話不是永久解法——token 到期時路由會再次調用被攔截的 CLI會話最終停止刷新。五、更新、回滾與支持12–15問題 12原生 GPT 請求 502 連接超時報錯含 timed out connecting to chatgpt.com 說明是網(wǎng)絡路徑問題不是憑據(jù)也不是模型。連接階段上限 3 秒、重試預算約 3 倍該值還到用戶手里說明整個預算內全部嘗試失敗。依次檢查本機到同主機的連通性有線/Wi?Fi 兩條路徑分開測、DNS 是否正常、router.log里UND_ERR_CONNECT_TIMEOUT是否成簇出現(xiàn)。臨時想回到原生./bin/disable只移除托管塊與當前服務保留所選模型、配置與登錄。問題 13Agent 任務中途無聲停止上游 200 但無文本、無工具調用的空回復在 Codex 眼里就是模型沒說話于是記錄為已完成輪次。路由內置空回復防護整包持有響應直到確認有內容否則丟棄并重試一次再空則返回明確的502 empty_completion絕不靜默成功。重試輪次會標記在usage-events.jsonl的emptyCompletionRetried: true持續(xù)出現(xiàn)說明該報給上游廠商。問題 14更新失敗如何回滾更新器失敗時自動還原到上一修訂版回滾引用維護在refs/codex-router/rollback邏輯見 src/update.mjs。手動回滾./bin/rollback注意更新會拒絕跟蹤文件的本地編輯、非main分支和未知 origin未跟蹤文件不阻塞--force只丟棄跟蹤文件編輯。舊版遷移的回滾是獨立命令./bin/migrate rollback。問題 15提交問題前先造一個 support bundle./bin/support-bundle生成 mode 600 的 JSON版本、doctor 檢查結果、服務狀態(tài)、provider 存在性、文件元數(shù)據(jù)。憑據(jù)值、提示詞、響應內容與日志全文一律排除且工具絕不會自動上傳實現(xiàn)見 src/support-bundle.mjs。六、15 個問題速查表#癥狀首選動作1后臺服務停了./bin/doctor --fix2端口 4200–4203 被占先查進程歸屬勿盲目殺3狀態(tài)目錄歸屬沖突在擁有方克隆跑doctor --fix4新原生模型不顯示完全退出重開 Codex5外部模型消失providers→refresh-catalog→doctor6路由 Agent 缺失model-router codex update7模型 ID 變更discover-models/curate-models8過早壓縮修正contextWindow后重裝9Kimi OAuth 未就緒kimi login 啟用 provider10API key 401核對 key 歸屬系統(tǒng)后重設11Windows 攔截 Grok升級或切換 grok-api12原生 502 超時測網(wǎng)絡路徑./bin/disable兜底13中途靜默停止查emptyCompletionRetried14更新失敗./bin/rollback15要提 issue./bin/support-bundle七、修復后如何驗證恢復./bin/status查看脫敏后的運行狀態(tài)可安全分享自動隱去本地能力 URL控制中心 Dashboard 的Service Health區(qū)應顯示 Router / Gateway 均 ReadyTraffic 圖表恢復出數(shù)打開 Codex 新任務確認選擇器里目標模型可用相關模塊與文檔 官方故障排查手冊docs/TROUBLESHOOTING.md doctor 檢查項實現(xiàn)src/doctor.mjs 更新與回滾邏輯src/update.mjs 支持包生成src/support-bundle.mjs 路由原理請求流向四件套docs/HOW-IT-WORKS.md遇到本文未覆蓋的報錯先跑一遍doctor把帶Fix:行的輸出和 support bundle 一起提交通常就能快速定位?！久赓M下載鏈接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.項目地址: https://gitcode.com/gh_mirrors/co/codex-router創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考