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 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 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 为你自己的机器定制。
路由模型报 unrouted_model
模型新增或改名后，选择器可能已经重建，但后台路由器内存中仍是旧注册表。运行 ./bin/control service restart 重启服务，再执行 doctor。如果 doctor 报告被跳过的用户模型，请修正或移除对应的本地定制条目。路由器现在会在本机拒绝未知的 provider/model，不会再误把提示当作原生模型请求发送给 ChatGPT。
旧 chatgpt-web/* 模型停止加载
非官方 ChatGPT Web 浏览器自动化供应商已被移除，因为使用它可能导致操作者的 OpenAI 账户被暂停甚至永久封禁。请停止使用这些路线，并用 ./bin/curate-models chatgpt-web --remove <slug> 逐个删除旧定制条目。更新后旧条目会被安全跳过，不会继续路由，但在手动删除前仍留在 user-models.json。
原生 GPT 模型停止工作
临时把 Codex 恢复到原生 base URL：
./bin/model-router codex disable这只移除标记块与当前服务，保留所选模型、配置档案、供应商凭据与 ChatGPT 登录。原生模型恢复后，检查路由器健康并创建 support bundle。
其他进程占用 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。如果任务缺失，你会看到指明任务名以及 service.mjs install 和 doctor --fix 的提示，而不是 schtasks.exe 自己的报错和错误的 {"state":"running"}。退出过程中不会修改任何状态。
首次安装在 300 秒后超时
模型目录较大时，LiteLLM 第一次冷启动可能超过安装器五分钟的健康检查，即使服务和启动器已经正确安装。当前 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 的提供商会让计数器停滞，上下文条看起来近乎为空，直到提供商拒绝该轮。当且仅当路由响应明确报告零提示 token、而该请求明显携带了大型提示时，路由器会用刚发送提示的估算值替代。
替代会被记录而不会隐藏：用量事件保留提供商的原始数字并增加 estimatedInputTokens，路由器在该轮记录 estimated-input-tokens=<count>。可在状态目录的 usage-events.jsonl 中统计：
grep -c estimatedInputTokens "$CODEX_HOME/codex-router/usage-events.jsonl"请向提供商报告零 token 响应——只有它们能修复源头。要再次在 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 只移除活动集成与后台服务；状态目录可能包含凭据、日志、目录缓存、安装历史与回滚快照。删除任何内容前请手动检查。
创建 support bundle
./bin/support-bundle生成的 mode-600 JSON 包含版本、doctor 检查、服务状态、供应商存在性、配置所有权与文件元数据，不含凭据值、提示、响应与日志内容。旧的 --include-logs 选项现在只是为脚本兼容保留的弃用空操作，因为历史日志可能包含后来已轮换或删除的凭据。工具绝不会自动上传 bundle。
仍然卡住？
在 Codex Router 仓库 开 issue，附上脱敏的 support bundle。包含 doctor 输出与确切报错文本，但绝不粘贴完整托管 URL 或任何凭据。