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