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 条清单可以快速把路由环境恢复健康。一、30 秒上手故障排查三步路径Codex Router 把诊断—修复—回滚做成了三条命令先记住这条主线诊断./bin/model-router codex doctor—— 每个FAIL都附带一条针对性修复建议修复./bin/doctor --fix—— 只重建仓库托管的文件、配置与服务状态不打印任何凭据值⏪回滚./bin/rollback—— 更新出问题的一键退回上一稳定版本 如果 doctor 报告检测到旧版 Kimi 路由器用./bin/doctor --fix --migrate-known迁移修复会拒绝未知归属的路由器避免误伤其他工具。完整条目见官方文档 docs/TROUBLESHOOTING.md。二、服务与状态类问题1–4问题 1后台服务停了路由不在一切外部模型都会失败。各平台确认方式macOSlaunchctl print gui/$(id -u)/io.github.codex-routerLinuxsystemctl --user status codex-router.serviceWindowsGet-ScheduledTask -TaskName Codex Router⚠️ Windows 上路由以无窗口方式运行没看到窗口不代表挂了去看状态目录里的router.log。修复./bin/doctor --fix。问题 2端口 4200–4203 被其他进程占用用lsof -nP -iTCP:4200-4203 -sTCP:LISTEN或 PowerShell 的Get-NetTCPConnection找到占用者。先确认进程归属再决定处理不要上来就杀进程——安装器只会迁移被识别的旧版服务其余情况直接报冲突并停下。问题 3状态目录属于另一个克隆doctor 报 state ownership 失败说明你从一个没有执行安装的克隆目录运行了命令。安全做法是让拥有已安装状态的克隆去修复./bin/model-router codex doctor --fix确需把归属转移到当前克隆时设置MODEL_ROUTER_ALLOW_FOREIGN_STATE1再跑上面的命令记录的所有者仍然健在时它只在归属方消失后才转移。问题 4新原生模型如 GPT-7没出现在选择器永远不需要卸载。路由合并了原生 外部目录检测到账号目录或 Codex 可执行文件指纹漂移会自动重发布。但model_catalog_json只在 Codex 启动时读一次——必须完全退出并重开 Codex关窗口不算。若日志提示 resolved Codex CLI is older than...是 PATH 里有个更旧的codex排在前面用CODEX_BIN/path/to/codex ./bin/refresh-catalog指向正确版本。三、模型与路由类问题5–8问题 5外部模型没出现在模型选择器按顺序跑三件套./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 / 想用新发现的模型./bin/discover-models deepseek只做发现、不改注册表。想在本机先用起来./bin/curate-models deepseek条目会写入状态目录的user-models.json含上下文窗口、图像支持等元数据后续官方注册表上架同模型会自动跳过。正式进注册表则需能力元数据 覆盖文本/流式/工具/压缩的计费实测./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并重启服务。四、凭据与登录类问题9–11问题 9Kimi OAuth 没就绪三步kimi login→./bin/providers enable kimi-oauth→./bin/doctor。路由只读官方 Kimi CLI 存放在~/.kimi-code下的凭据并在跨进程锁下刷新——不要把 OAuth token 拷进 Codex 配置、API key 文件或环境变量。问题 10API Key 缺失或 401用./bin/provider-key kimi-api set输入隐藏回车后回报字符数粘贴重复会被提示。⚠️ 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 说明是网络路径问题不是凭据也不是模型。连接阶段上限 3 秒、重试预算约 3 倍该值还到用户手里说明整个预算内全部尝试失败。依次检查本机到同主机的连通性有线/Wi‑Fi 两条路径分开测、DNS 是否正常、router.log里UND_ERR_CONNECT_TIMEOUT是否成簇出现。临时想回到原生./bin/disable只移除托管块与当前服务保留所选模型、配置与登录。问题 13Agent 任务中途无声停止上游 200 但无文本、无工具调用的空回复在 Codex 眼里就是模型没说话于是记录为已完成轮次。路由内置空回复防护整包持有响应直到确认有内容否则丢弃并重试一次再空则返回明确的502 empty_completion绝不静默成功。重试轮次会标记在usage-events.jsonl的emptyCompletionRetried: true持续出现说明该报给上游厂商。问题 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 检查结果、服务状态、provider 存在性、文件元数据。凭据值、提示词、响应内容与日志全文一律排除且工具绝不会自动上传实现见 src/support-bundle.mjs。六、15 个问题速查表#症状首选动作1后台服务停了./bin/doctor --fix2端口 4200–4203 被占先查进程归属勿盲目杀3状态目录归属冲突在拥有方克隆跑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 归属系统后重设11Windows 拦截 Grok升级或切换 grok-api12原生 502 超时测网络路径./bin/disable兜底13中途静默停止查emptyCompletionRetried14更新失败./bin/rollback15要提 issue./bin/support-bundle七、修复后如何验证恢复./bin/status查看脱敏后的运行状态可安全分享自动隐去本地能力 URL控制中心 Dashboard 的Service Health区应显示 Router / Gateway 均 ReadyTraffic 图表恢复出数打开 Codex 新任务确认选择器里目标模型可用相关模块与文档 官方故障排查手册docs/TROUBLESHOOTING.md doctor 检查项实现src/doctor.mjs 更新与回滚逻辑src/update.mjs 支持包生成src/support-bundle.mjs 路由原理请求流向四件套docs/HOW-IT-WORKS.md遇到本文未覆盖的报错先跑一遍doctor把带Fix:行的输出和 support bundle 一起提交通常就能快速定位。【免费下载链接】codex-routerExternal-model router for Codex with guided Kimi OAuth/API, DeepSeek, safe migration, and rollback.项目地址: https://gitcode.com/gh_mirrors/co/codex-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考