Codex WSL2 安装、配置与常见问题
Codex 可以原生运行在 Windows 的 PowerShell 环境，也可以让代理运行在 WSL2 的 Linux 环境。需要 Linux 工具链、仓库本来就在 WSL2，或原生 Windows 沙箱受策略限制时，再选择 WSL2。
::: tip 当前支持边界
官方文档说明：当前 Codex 的 Linux 沙箱需要 WSL2；WSL1 从 Codex 0.115 起不再支持。桌面应用切换代理环境后需要重启才会生效。
:::
原生 Windows 和 WSL2 怎么选
| 场景 | 建议环境 |
|---|---|
仓库在 C:\，主要使用 PowerShell 和 Windows 工具 | 原生 Windows |
| 仓库在 Linux home，依赖 bash、apt 或 Linux 工具链 | WSL2 |
| 需要 Windows 原生沙箱 | 原生 Windows |
| 团队开发环境统一使用 Linux | WSL2 |
| 需要最佳 Windows 原生 App 与沙箱体验 | 原生 Windows |
不要在同一个项目中频繁切换环境并分别维护两套配置，否则容易出现 PATH、文件权限、换行符和认证状态不一致。
安装 WSL2
以管理员身份打开 PowerShell 或 Windows Terminal：
wsl --install
按 Windows 提示重启，然后检查：
wsl --status
wsl --list --verbose
确认发行版的 VERSION 是 2。如果 WSL 已安装但状态异常，可以先更新：
wsl --update
wsl --shutdown
在 WSL2 内安装 Codex CLI
进入 WSL：
wsl
在 Linux shell 中运行官方安装脚本：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex --version
codex
Windows 中安装的 codex 和 WSL 中安装的 codex 是两个运行环境。应分别检查命令路径和版本。
项目应该放在哪里
如果代理本身运行在 WSL2，建议把仓库放在 Linux home，例如：
mkdir -p ~/code
cd ~/code
git clone https://github.com/your/repo.git
长期在 /mnt/c/... 处理大型仓库可能遇到较慢的 I/O、权限或符号链接问题。Windows 可以通过 \\wsl$\<发行版>\home\<用户> 访问 WSL 文件。
如果继续使用 Windows 原生代理，则更适合把项目保存在 Windows 文件系统，再从 WSL 通过 /mnt/<drive>/... 访问。
桌面应用切换到 WSL
- 打开 Codex/ChatGPT 桌面应用设置。
- 把代理环境从 Windows native 切换为 WSL。
- 完全重启应用。
- 重新打开项目并确认终端路径。
集成终端和代理环境是两个独立选项。终端显示 WSL 不代表代理一定运行在 WSL，反之亦然。
在 VS Code 中使用
安装 VS Code 的 WSL 扩展后，在 WSL 项目目录运行：
code .
确认 VS Code 状态栏显示 WSL: <发行版>，并在集成终端运行：
echo $WSL_DISTRO_NAME
which codex
如果找不到 Codex，说明它没有安装到当前 WSL 发行版，或安装目录没有加入 WSL 的 PATH。
WSL 配置和认证为什么不一致
Windows 原生 Codex 通常使用：
%USERPROFILE%\.codex
WSL 内 CLI 默认使用：
~/.codex
因此两边不会自动共享 config.toml、认证缓存和会话。可以分别配置；确实需要共享时，再按照 Windows 应用官方文档 设置 CODEX_HOME。共享前应理解权限和密钥暴露边界。
WSL 登录失败
- 在 WSL 内运行
which codex和codex --version，确认调用的是 Linux 版本。 - 明确使用 ChatGPT 登录还是 API Key 登录。
- 浏览器登录完成后，确认回调返回的是当前 WSL 中的 Codex。
- 检查 WSL 网络和系统时间。
- 不要把 Windows 的
auth.json直接复制到公开或多用户 Linux 环境。
如果 Windows CLI 能登录而 WSL 不能，优先比较两边的网络、CODEX_HOME 和凭据位置，而不是重复注册账号。
WSL 代理不生效
先在 WSL 内单独验证网络，不要只看 Windows 浏览器能否访问：
curl -I https://chatgpt.com
env | grep -i proxy
Windows 系统代理不一定自动传入 WSL。代理地址还要考虑 WSL 的网络模式和监听范围。不要把包含用户名、密码或 API Key 的代理配置粘贴到公开日志。
reconnecting 或环境读取异常
按顺序检查：
wsl --list --verbose是否显示发行版正在使用 WSL2。- WSL 内
which codex和codex --version是否正常。 - 项目路径是否真实存在于当前发行版。
- Windows 与 WSL 是否各自使用了不同配置或 API Key。
- 代理是否只在 Windows 生效，WSL 内无法联网。
- 更新 WSL 后执行
wsl --shutdown，再重新启动桌面应用。
大型仓库卡顿时，优先把项目从 /mnt/c 移到 ~/code，再比较速度。
Native Windows 和 WSL2 不要混用哪些东西
- 不要在同一终端里混用 Windows 与 Linux 的
codex路径。 - 不要让两个环境同时写同一个配置文件或认证缓存。
- 不要在
/mnt/c和~/code各保留一份不清楚哪个是最新的仓库。 - 不要假设 Windows 系统代理、证书和环境变量会自动进入 WSL。
选择一个主环境完成安装、配置和验证；只有确实需要另一套工具链时再切换。