Codex on Windows + WSL2 实战指南

一份面向 Windows Codex 用户的 WSL2 迁移、验证与故障排查指南，内容来自真实迁移记录。

如果你遇到以下问题，这份指南可以帮你快速定位：

• Codex 看似使用 Bash，实际仍运行在 Windows 上；
• 工作目录混入 C:\...、/mnt/c/... 或 WindowsApps/resources；
• Windows 沙箱访问 C:\Users\Default 时被拒绝；
• 切换 WSL 后，node_repl 或 MCP 因旧 Windows 路径启动失败；
• WebSocket 断开、回退 HTTPS，难以判断是环境还是网络问题。

核心结论

稳定使用 Codex + WSL2，需要同时确认：

1. WSL2 发行版能够正常启动；
2. Codex 桌面应用已启用 WSL Agent；
3. 新任务从 /home/<user>/code/<project> 打开；
4. uname、pwd、Shell 和工具路径均指向 Linux 环境；
5. MCP、REPL 等扩展没有继续引用失效的 Windows 运行时路径。

推荐架构

Windows
├── Codex 桌面应用（界面、登录、通知）
└── WSL2 / Ubuntu
    ├── Codex Agent 与 Bash
    ├── Git、Node.js、Python 等开发工具
    └── 项目：/home/<user>/code/<project>

高频读写的代码仓库建议放在 WSL 的 Linux 文件系统中，而不是长期放在 /mnt/c/... 下。

快速验证

在 Codex 集成终端或 Agent 中执行：

uname -a
cat /etc/os-release
printf 'shell=%s\n' "$SHELL"
pwd
command -v codex
codex --version
stat -f -c '%T' .

理想结果应包括：

• uname 显示 Linux 与 WSL2；
• pwd 位于 /home/...；
• Shell、Codex CLI 和开发工具来自 Linux 路径；
• 项目目录没有使用 Windows 挂载文件系统。

完整教程

详细迁移步骤、真实报错、分层排查方法与验收清单，请阅读：

Windows Codex 切换 WSL2：实战避坑与可复用教程

参考资料

• OpenAI：在 Windows 上使用 WSL

License

本文档仅供学习与经验交流。若需转载或改编，请注明来源。