Codex 8.26 Windows 升级故障排查与回退指南
Codex 8.26 升级后，部分 Windows 用户遇到客户端无法启动、插件与路径失效、项目列表消失等问题。文章按故障类型梳理排查顺序，给出配置备份、WSL/CLI 替代、版本回退和项目数据恢复的具体步骤，并说明各方案的适用场景与风险。
Codex 8.26 版本推送后，一些 Windows 用户的升级过程并不顺利：客户端直接打不开，或能打开但执行任务时插件、路径全部失效，还有人发现项目列表被清空。问题都出现在升级之后，很容易让人误以为是自己的项目或配置坏了。实际排查时，先把启动问题、配置问题和数据展示问题分开，会少走很多弯路。
从目前可见的反馈看，同一版本下的表现并不一致：有人回退版本后立即恢复，有人改用 WSL 或 Codex CLI 后正常，也有人只是项目列表消失、会话记录仍然保留。这说明很难归结为单一原因，更像是升级过程触发了 Windows 本地环境、WSL 远程连接、配置索引等多个薄弱点。
先判断故障类型
| 现象 | 更可能的方向 | 优先动作 |
|---|---|---|
| 升级后客户端无法启动、闪退 | WSL/远程连接、启动组件同步、安装损坏 | 备份后回退，保留日志 |
| 能启动但任务失败、插件或路径失效 | config.toml 被改写、工作目录或环境变量不对 | 对比备份配置，检查项目路径 |
| 项目列表消失、会话记录还在 | 索引或配置显示问题，未必是数据丢失 | 停止写入，备份 .codex 后恢复 |
如果客户端完全打不开，不要先反复卸载重装，也不要让 AI 直接清理缓存。先保留现场，备份用户目录下的 .codex 文件夹，再决定回退还是修复。
升级前后都该做的备份
在 Windows PowerShell 中可以先关闭 Codex 客户端和后台进程，然后执行：
$src = Join-Path $env:USERPROFILE ".codex"
$dst = Join-Path $env:USERPROFILE ("codex-backup-" + (Get-Date -Format "yyyyMMdd-HHmm"))
New-Item -ItemType Directory -Path $dst | Out-Null
Copy-Item (Join-Path $src "*") $dst -Recurse -Force
这份备份至少应包含 config.toml、会话数据、项目索引和日志。升级前还应记录当前版本号，保留一份可用的官方旧版安装包。备份不要只放在同一块磁盘上，也不要在客户端运行时直接复制数据库文件。
配置被改写：js_repl 不是唯一答案
有反馈把问题指向 config.toml 中的 js_repl 被改成 false，但另一台机器上同样为 false 却工作正常。因此它可能是诱因之一，却不足以解释所有故障。不要在不知道原值的情况下直接改这一项，更不要照抄陌生配置。
可以按下面的顺序检查：
- 关闭客户端，把当前 config.toml 与升级前备份做对比，只看差异项。
- 如果确认某项被升级意外改写，先恢复原值，不要顺手改其他配置。
- 检查 TOML 语法是否完整，路径中是否含有特殊字符或多余空格。
- 在一个简单的小项目里重新执行任务，确认插件和路径是否恢复。
- 没有备份时，让 Codex 只读检查，不要让它自动修改。
可以这样提问：
只读检查用户目录下 .codex 文件夹中的 config.toml 和升级日志，说明本次升级后哪些配置项发生了变化，列出可能导致插件或路径失效的项。不要修改任何文件，先给出修复方案和风险。
确认原因后，再逐项修改并保留备份。
启动失败与 WSL 远程连接
反馈较集中的场景是 Windows 客户端通过远程连接使用 WSL 或 Linux 环境。升级后，如果远程启动组件、同步目录或客户端版本不匹配，就可能出现无法启动。类似问题并非首次出现，官方是否已经修复，要以最新版本说明和 issue 状态为准。
如果工作不能停，回退上一版通常是最快的处理方式。如果必须使用新版本，可以改为在 WSL 内直接运行 Codex CLI：
wsl -l -v
wsl -d <发行版名称>
cd /path/to/project
codex
如果 WSL 中尚未安装，可按官方文档安装。使用 Node.js 的环境常见做法是：
npm install -g @openai/codex
安装方式和包名请以官方最新文档为准。需要注意，Windows 下的 .codex 与 WSL 用户目录下的 .codex 是两套独立配置，不要直接互相覆盖。项目放在 /mnt/c 下可能遇到性能和权限差异，测试时可先放到 Linux 主目录。
项目列表消失后的恢复
会话记录还在，说明数据未必全部丢失，更可能是项目索引或界面配置没有正确加载。此时最重要的是停止继续写入，并马上备份 .codex 文件夹。
恢复步骤可以这样安排：
- 退出客户端，确认后台进程已结束。
- 复制整个 .codex 文件夹到安全位置。
- 不要清空缓存、不要反复重装，以免覆盖可恢复的数据。
- 检查 .codex 下的配置、索引或数据库文件，确认是否有升级前备份。
- 让 Codex 先做只读诊断，再执行经过确认的修复步骤。
可以使用这样的提示词：
项目列表在升级后消失，但会话记录仍在。请只读检查用户目录下 .codex 中的配置、索引或数据库文件以及升级日志，判断项目列表存储在哪里、是否有备份。先输出修复步骤和风险，禁止直接删除或覆盖任何文件。
如果数据库文件需要打开，先复制一份再操作。修复完成后，重新添加项目并验证会话能否正常打开。若多次让 AI 自动修复仍无效，就应停止尝试，转而从备份恢复或回退版本。
回退版本与替代方案怎么选
| 方案 | 适用场景 | 取舍与注意 |
|---|---|---|
| 回退上一版 | 无法启动、急着交付 | 见效快，但可能失去新功能，要防止自动更新再次覆盖 |
| 改用 WSL 或 CLI | 必须用新版本，或项目依赖 Linux 工具链 | 环境更稳定，但路径、权限和插件行为可能与客户端不同 |
| 修复配置或索引 | 只有局部功能异常、项目列表丢失 | 成本低，但必须先备份，避免误删数据 |
| 等官方修复 | 问题可复现但不影响工作 | 保留日志和最小复现步骤，关注官方发布说明 |
桌面客户端回退时，应使用官方提供的历史安装包或商店的回滚方式，不要从第三方网盘下载。若使用 npm 安装的 CLI，可以先查看可用版本，再安装指定旧版本：
npm view @openai/codex versions --json
npm install -g @openai/codex@<上一版本>
回退后先关闭自动更新或固定版本，确认稳定后再决定是否继续升级。长期停留在旧版本并不是理想状态，尤其是涉及安全和兼容性更新时。
检查清单与小结
推荐的处理顺序是：先备份，再判断故障类型；能回退就先回退；必须使用新版本时，再考虑 WSL 或 CLI；最后才处理配置和项目数据。每次升级后做三项验证：新建一个测试项目、运行一个简单任务、检查插件和路径是否正常。
如果每次升级都复现，记录 Codex 版本、Windows 版本、WSL 发行版、错误日志和操作步骤，提交给官方排查。具体修复进度和版本兼容性，请以官方最新说明为准，不要依赖未经验证的“偏方”直接改配置或删数据。
