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 只更新源码检出。把它应用到按用户安装并验证生成的自定义代理：

./bin/model-router codex update
./bin/model-router codex doctor

doctor 应对 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 token 复制到别处。

Windows 阻止 Grok OAuth CLI

如果 grok --version 报 spawn UNKNOWN、“An Application Control policy has blocked this file,” 或 Smart App Control 通知，请改用带 xAI API Key 的 grok-api 供应商。具体命令见 Windows 指南。

API Key 缺失或无效

重新运行隐藏 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 恢复到原生 base URL：

./bin/model-router codex disable

这只移除标记块与当前服务，保留所选模型、配置档案、供应商凭据与 ChatGPT 登录。原生模型恢复后，检查路由器健康并创建 support bundle。

其他进程占用 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 --fix

Linux 用 systemctl --user status codex-router.service；Windows 用 Get-ScheduledTask -TaskName "Codex Router"。保持仓库在安装时使用的绝对路径；移动后从新路径重跑安装。

更新失败

./bin/model-router codex rollback

更新会拒绝脏检出、非 main 开发分支与未知源 URL，而不是覆盖本地工作。旧版迁移回滚是独立的：./bin/migrate rollback。

WebSocket 警告后 HTTP 回退

这是预期行为。路由器拒绝可选的 Responses WebSocket 升级，当前 Codex 回退到压缩 HTTP。仅警告不代表模型请求失败。

Voice 模式报告不支持的 /v1/live 路由

Codex Voice 使用与 Responses API 分离的原生实时端点。更新后重新运行 ./bin/enable，完全退出 Codex 再重新打开，让托管的实时覆盖生效。

卸载保留了文件

这是有意为之。./bin/uninstall 只移除活动集成与后台服务；状态目录可能包含凭据、日志、目录缓存、安装历史与回滚快照。删除任何内容前请手动检查。

创建 support bundle

./bin/support-bundle

生成的 mode-600 JSON 包含版本、doctor 检查、服务状态、供应商存在性、配置所有权与文件元数据——不含凭据值、提示、响应与日志内容。仅在确实需要日志上下文时使用 ./bin/support-bundle --include-logs，分享前先检查输出，绝不自动上传。

仍然卡住？

在 Codex Router 仓库 开 issue，附上脱敏的 support bundle。包含 doctor 输出与确切报错文本，但绝不粘贴完整托管 URL 或任何凭据。