Codex 报错的时候，屏幕上通常只有一句话，甚至只有一个 Reconnecting。剩下判断哪出了问题，都得自己来。同一句报错，有时是环境没配好，有时只是桌面端断线重连。先把现象归到正确的类别，再决定动手做什么，比反复重装省事得多。
这份清单按现象在前，先查什么在后的顺序排。前半段是任务和项目层面的问题，靠改提示词和补项目说明就能解决。后半段转到连接层面，要动的是代理，环境变量和配置文件。
任务与项目层面的六类现象
| 现象 | 常见原因 | 先查什么 |
|---|---|---|
| 找不到项目上下文 | 没在项目根目录，仓库缺 README 或测试命令 | 让它只读目录并总结项目结构，补一份 AGENTS.md，任务里指定相关目录 |
| 改动范围太大 | 任务没说清动哪些文件 | 写明只修改这些文件，要求先输出计划，把任务拆小，review 时拒绝无关重构 |
| 测试跑不起来 | 测试命令不对，依赖没装 | 先定位测试命令，检查依赖，区分环境问题和代码问题 |
| 生成内容不准确 | 没有要求引用依据 | 要求引用依据文件，官方事实附链接，区分已确认和推测，先读代码再写文档 |
| 登录或权限出问题 | 版本旧，账号计划或组织策略有限制 | 更新 CLI 到最新版本，重走登录流程，查官方 Help Center 的 Codex 文章 |
| 改动没落地 | 没看 diff 就提交 | 提交前用 git diff 过一遍，让它自查有没有无关改动 |
测试这类问题的处理有一条分界线。属于环境缺口的，让它把阻塞记下来，而不是继续乱改。属于代码问题的，才进入正常的定位和修复流程。这两件事混在一起，改动就会越滚越大。
Desktop 一直显示 Reconnecting
这个现象不是一个具体根因。主连接，会话恢复，流的协议和代理设置，都可能让它出现。第一反应不要重装 Codex，也不要覆盖 config.toml，更不要急着换账号。先按三层判断。
| 层级 | 现象 | 先做什么 |
|---|---|---|
| 主连接 | 新线程也一直 Reconnecting | 验证 Codex 进程能不能走到正确代理 |
| 会话流 | 偶发 stream disconnected before completion | 看是不是旧会话，或者 WebSocket 和服务端连接的问题 |
| 工具 worker | 主界面恢复，但 MCP 和 Browser 仍然失败 | 再查 config.toml 里的 MCP 环境变量 |
代理要先验证再写进配置
macOS 上可以先查一遍系统代理设置，再用 curl 走一次代理，确认协议真的通。端口和协议都验证通过之后，再把最小的一组变量写进用户目录下的 .codex/.env，然后完全退出并重新打开桌面端。
网上有一些 macOS 一键脚本，会读取 scutil 的输出并更新这份 .env。这类脚本可以当模板用，运行前至少要确认三件事：它会备份原文件，它不会覆盖其他 secret，而且它明确只适用于 macOS。
Windows 原生桌面端优先检查用户环境变量。WSL 模式不要只写 .bashrc，因为桌面端启动 WSL 进程时不一定经过 login shell。改完环境变量要完全重启 Codex。
主界面恢复之后，如果 MCP 或者 node_repl 还是断，就要看这个 MCP server 是不是需要单独配一份环境变量。
切换 provider 后旧会话不可见
改过根级 config.toml 里的 model_provider 之后，旧会话可能在列表里消失。文件通常还在，只是会话 metadata 和项目路径缓存仍然指向旧 provider。另一种可能是桌面端只显示最近 50 条会话，旧的自然被挡在外面。
处理顺序是先看 .codex/sessions 里文件还在不在，归档目录也一并翻一下。如果只是桌面端看不见，先排除 50 条显示限制。确认是 metadata 不一致，再动配置文件。用第三方工具之前先备份整个 .codex 目录，也别把这类工具当成官方认证或者账号切换工具。
日志在哪儿，求助时贴什么
macOS 的应用日志默认在用户目录下的 Library/Logs/com.openai.codex 里，按年月日分目录存放。会话记录在 .codex/sessions，也可以用 CODEX_HOME 这个环境变量指过去。
发 issue 或者群里求助的时候，只贴脱敏之后的错误字符串。时间点，Codex 版本，平台和网络拓扑这几项也可以带上。下面这些不要公开：
- 完整日志
- 邮箱和 account id
- conversation id 和 session id
- 真实出口 IP
- 本机路径和私有仓库名
- token
Windows 桌面端另有一套社区维护的排障库。Microsoft Store 或者 winget 安装出的问题能在里面找到对应条目。Windows sandbox 和 Worktree 的异常也单独归类。浏览器插件，电脑操控插件，WSL 混合路径则各有章节。这些条目按证据等级和复现等级整理，还带只读诊断脚本。提交日志或截图之前，也要先去掉用户名，本机路径和账号信息。
