Codex 出问题别急着重装：一套从现象、证据到恢复的排障方法

Codex 报错时，很多人的第一反应是：

重装客户端；
删除配置；
切换账号；
开启完全访问；
把所有代理变量都加进去；
让 Codex 自己“继续修到成功”。

这些动作可能暂时改变现象，却也会破坏原本的证据。

更可靠的排障原则是：先判断问题发生在哪一层，再做最小恢复。

第一步：保留现场

在修改配置前记录：

完整错误字符串；
发生时间；
Codex App 或 CLI 版本；
操作系统；
当前项目和工作目录类型；
最近改过的配置、provider、代理或权限；
同一问题能否在新线程复现。

日志分享前必须脱敏，不要公开邮箱、account id、conversation id、session id、真实 IP、私有仓库名、本机用户名和 token。

第二步：先按层级分类

项目上下文层

现象：

找不到正确入口；
不知道怎样运行测试；
总是在错误目录修改。

检查：

当前是否位于项目根目录；
是否有 README 和 AGENTS.md；
monorepo 是否说明包边界；
任务是否指定了相关目录。

任务范围层

现象：

改动文件过多；
出现无关重构；
为了修一个问题改变了架构。

处理：

明确“只修改哪些文件”；
先要求只读计划；
把大任务拆成多个阶段；
在 review 中拒绝范围外改动。

依赖与环境层

现象：

测试命令不存在；
安装失败；
编译器或运行时版本不对。

处理：

先从仓库配置确认正确命令；
区分代码错误和环境缺失；
记录阻塞，不要为了让命令变绿而乱改业务代码。

账号、权限和组织策略层

现象：

登录失败；
功能不可用；
命令一直被拒绝；
权限与预期不一致。

检查：

客户端和 CLI 版本；
当前账号和计划；
组织策略；
沙盒与审批配置；
外部应用是否需要独立授权。

Desktop 一直 Reconnecting 怎么排

Reconnecting 不是根因，只是连接没有稳定建立。

可以先分成三层：

层级	现象	方向
主连接	新线程也一直重连	网络、代理、客户端进程
会话流	特定旧线程中断	会话恢复、WebSocket/SSE、服务端
工具 Worker	主界面正常，MCP 或 Browser 失败	工具自己的环境和代理

如果使用代理，先验证：

端口是否真实监听；
HTTP、HTTPS 或 SOCKS 协议是否匹配；
Desktop 启动进程是否继承变量；
MCP Worker 是否需要单独的环境配置。

不要只因为浏览器能联网，就假设 Codex 进程一定走了同一代理。

修改变量后应完全退出并重启客户端，而不是只关闭当前窗口。

切换 Provider 后旧会话不可见

旧会话不显示，不一定等于文件被删除。

可能原因包括：

会话 metadata 仍指向旧 provider；
SQLite 状态和项目路径缓存没有同步；
CLI 能看到，但 Desktop 首屏只展示部分最近会话；
跨 provider 的加密内容无法继续使用。

正确顺序是：

只读检查会话文件是否还存在；
对比 CLI 与 Desktop 的可见性；
判断是显示限制还是 metadata 不一致；
修改本地状态前先备份；
第三方同步工具只用于它明确支持的范围。

不要把 metadata 同步工具当成账号切换或认证修复工具。

让 Codex 帮你排障时怎样提问

可以使用：

请先不要修改任何文件或配置。

根据当前错误输出：
1. 按可能性列出根因；
2. 为每个根因给出支持或反对证据；
3. 说明下一条最小只读检查；
4. 区分本次改动、环境旧问题和外部服务问题；
5. 未确认前不要重装、删除配置或扩大权限。

这种问法可以防止 Codex 从“诊断”直接跳到“修改一切”。

什么时候应该停止自己排查

出现以下情况时，应整理证据后升级到官方支持、管理员或项目维护者：

同一问题在干净环境稳定复现；
涉及组织权限和账号状态；
服务端返回明确内部错误；
客户端崩溃或数据损坏；
安全、支付或生产数据可能受到影响；
需要读取不应暴露的私有日志才能继续。

升级问题时提供最小复现、版本、平台、时间和脱敏错误，不要直接上传完整日志。

写在最后

好的排障过程是一条证据链：

记录现象
→ 确定层级
→ 提出假设
→ 运行最小只读检查
→ 验证或排除
→ 执行最小修复
→ 重新验证
→ 记录结论

排障的目标不是让报错暂时消失，而是知道问题为什么发生，以及下次怎样更快恢复。