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 深入解析。
常见问题与修复
ClinePass 返回包装或失败响应
路由器现在会把 ClinePass 非流式的 success: true / data 成功响应解包为 Chat Completions。unsuccessful 包装响应会报告为供应商失败，不再被当作成功答案转发。如果 Codex 显示空白或格式错误的 ClinePass 转轮，请更新路由器。
服务自动启动反复失败
连续的自动启动探测失败现在会让后续尝试依次等待 1、2、4、8、最多 15 分钟，日志会显示 backing off。修复原因后，显式执行服务 start 或 restart 可重置退避。Windows 上的 ./codex-router.ps1 start --foreground 也恢复前台运行，不再占用托管服务记录；无法验证停止时，服务 stop/restart 会明确报错。
Z.ai Coding Plan 在长推理停顿中断开
推理流在序言结束后有独立的三分钟空闲时限。如有需要，在服务环境中将 CODEX_ROUTER_ZAI_CODING_STREAM_STALL_MS 设为 1 至 240000 毫秒的整数，再重新加载服务定义。其它供应商的时限不变。
自定义 OpenAI-Responses 网关在压缩时失败
要求流式请求的通用 OpenAI-Responses 网关此前会在自动压缩时返回 400 Stream must be set to true，导致上下文满后对话无法继续。压缩现在与普通转轮一样采用流式响应，不完整或失败的响应也进入常规故障转移流程。如果在对话上下文满后遇到此错误，请更新路由器。
Ollama 离线时 Control Center 卡住
如果 Ollama API 探测已失败，Control Center 快照现在会跳过 CLI 调用，本地模型探测也有短超时。Ollama 未运行时不应再拖住面板。
升级 Node 后刷新报 ENOENT
路由器子进程现在优先使用安装时记录的 Node 路径，否则回退到当前解释器。这避免 brew upgrade node 删除旧 Homebrew Cellar 路径后刷新失败。
Windows 服务重启后无法启动
服务首次探测进程身份时现在最多等待 45 秒，超时后重试一次。服务进程记录的 ACL 加固失败只记录警告，不再阻止启动；凭据文件的 ACL 故障仍会阻止启动。
外部模型在选择器里缺失
目标供应商必须同时报告 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确认所有者与用途前不要杀进程。安装器只迁移已识别的旧仓库服务，否则遇到冲突会停止。
后台服务停止
在 Control Center 打开 Status → Service health → Fix，然后检查 Router 健康状态，切回已知可用的聊天模型。Fix 会修复并重启已安装的 Router，可能中断路由对话；它不会启用 OpenRouter Decisions 等独立工具客户端。
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。
返回 HTTP 200，但生成失败
HTTP 200 只确认响应已传送，不代表模型回合已完成。查看 Control Center 近期请求中的生成结果：failed、incomplete、canceled 或 indeterminate 的回合仍可能产生计费 token；旧用量记录没有生成结果字段。如果流式文本在结尾丢失未闭合的字面推理标签或末尾空白，请更新路由器；流适配器现在会在结束前输出暂存文本，且不会重复事件。
取消 Claude Code 请求后仍在生成
更新到上游当前 main。关闭 Claude Code 客户端连接后，路由器现在会在等待响应头或读取 JSON、SSE 时中止上游 Responses 生成，避免已取消的请求继续在后台运行。
非流式 Responses 出现乱码
更新到上游当前 main。路由器现在会跨 HTTP 数据块连续解码 UTF-8；助手正文、工具参数和元数据中的字符即使被拆开，也不会变成 �。
重试用量低于供应商的计费总量
更新到上游当前 main。某次重试未给出计费 token 数时，路由器会先回退到该次报告的输入、输出数，再累加各次计费用量；明确报告的计费零值仍保留为零。这修正本地记录，不改变供应商实际收费。
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 或任何凭据。