Troubleshooting

排障

先确认故障发生在 Mixin 网关、供应商、Agent 接入，还是 Web 面板。查看当前版本和错误，避免直接删除配置或客户端账号。

网关没有运行

从菜单栏、托盘或 Web 服务页面启动网关。CLI 对照：

codex-mixin service status --json
codex-mixin service start
codex-mixin doctor --quick
codex-mixin service logs --lines 200

自动端口在 8000–9000 范围分配，日常使用默认启动方式即可。状态残留或权限问题可运行 doctor --fix，并检查实际结果。

客户端没有模型或仍使用旧配置

1. 在「模型与服务」确认供应商已启用、模型已选中并保存。
2. 确认网关运行、Agent 页面显示已接入。
3. 重启客户端或打开新 CLI 会话。
4. 升级后接口或端口仍旧时，执行 codex-mixin service restart，再检查接入状态。

需要恢复时在 Agent 页面断开接入；退出 App 不会恢复配置。不要删除 Codex 的账号或会话数据库。

供应商测试、OAuth 或模型调用失败

先在界面测试连接、刷新模型；检查 Key / 登录是否有效、API 根地址和协议是否匹配、账号是否有模型权限，以及代理、DNS 与上游限流。

codex-mixin provider test <id> --json
codex-mixin provider discover <id>
codex-mixin provider probe <id>

probe 会发真实模型请求。Antigravity 登录超时可取消后重试，模型目录与额度查询不依赖其 CLI。模型返回名称不一致时，查看用量明细中的请求与返回模型，结合上游路由配置判断。

Web 面板打不开

• 使用本次启动打印的地址与 Token；重启面板后重新获取。
• 确认面板进程仍在运行，浏览器使用实际端口。
• 远端访问时使用开发机可访问的地址与实际端口，确认对应端口可达，见 安装。
• 面板正常、模型请求失败时，另查模型网关；两者的端口与访问控制独立。

用量为空或新页面报接口不存在

确认已有请求经过当前网关；检查时间范围、Provider 筛选。不会补录旧回复，本地只保留最近 5000 条。升级 App 后旧网关仍在运行时，先重启网关。

配置导入或解密失败

导出备份与工作配置不是同一格式。缺少 config.json.key 时，新生成的密钥不能解开旧配置；优先导入可信的 .b64 备份。目标版本应不低于源版本，文件损坏或引用无效时导入会明确失败。

进一步诊断

codex-mixin doctor
codex-mixin service logs --lines 200

完整诊断会访问上游。ECH 问题见 ECH。提交 Issue 时附版本、系统、复现步骤和脱敏日志；不要附凭据、配置备份或面板 Token。