31. Windows 使用指南

本节目标：搞懂 Codex 在 Windows 上怎么装、原生还是 WSL 怎么选、路径和换行两个特有坑怎么躲、Windows 沙箱跟 Mac/Linux 差在哪，以及遇到 1385/1223 报错怎么办。

前面三十章默认你在 Mac 或 Linux 上敲命令，但国内一大半人手里是 Windows。路径是反斜杠，换行符是历史包袱，沙箱是另一套—这些坑不提前知道，迟早踩。

一句话结论：默认用原生 Windows

先把结论甩出来：默认就用原生 Windows + elevated 沙箱，这是官方推荐的跑法，速度最快、安全性不打折。只有当你的工作流本来就泡在 Linux 里、或者两种原生沙箱在你电脑上都跑不起来时，才退回去用 WSL2。

打个比方，装宽带。师傅先给你接光纤入户（elevated），这是最快最稳的方案；只有布线被卡住了，才退而求其次拉根网线（unelevated）；实在都不行，才考虑搬去隔壁有网的房间办公（WSL2）。多数人直接接光纤就完事。

安装方法

Windows 上装 Codex CLI，官方最直接的路子是 PowerShell 安装脚本，一行搞定。

打开 PowerShell 或 Windows Terminal
执行官方安装脚本
关掉终端重开一个，让 PATH 生效
验证安装是否成功

# 方式一：官方安装脚本（推荐）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# 方式二：npm 安装（需要 Node.js）
npm install -g @openai/codex

# 方式三：winget 安装
winget install OpenAI.Codex

# 验证安装
codex --version

能打印出版本号就说明装好了。如果使用 IDE 扩展，建议额外备上 C++ 构建工具：

winget install --id Microsoft.VisualStudio.2022.BuildTools -e

Note

前置依赖盯紧三样：Windows 11（推荐）或 Windows 10 1809+、winget 可用、管理员审批权限。缺 C++ 构建工具时 IDE 扩展会转圈不响应。

原生还是 WSL：看你的代码活在哪

这是 Windows 用户最该先想明白的选择题。标准很简单：看你的代码和日常工作流活在哪儿。

维度	原生 PowerShell	WSL2
安装难度	一条脚本搞定	需要先装 WSL 发行版
速度	原生最快	跨盘符 I/O 较慢
沙箱	Windows 专属两套	走 Linux 的 bubblewrap
适合谁	大多数 Windows 用户	项目本来在 Linux 里的人

选原生 PowerShell：你就是普通 Windows 用户，平时用 VS Code 写代码、用 Windows 的 Git。直接原生，别装 WSL。

选 WSL2：你需要 Linux 原生工具链，或者仓库和工作流本来就在 WSL2 里，或者两种原生沙箱都跑不通。

要走 WSL2，先在管理员 PowerShell 里安装：

wsl --install
wsl

进了 WSL shell 后，Codex 要在 Linux 里重新装一遍：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

Warning

WSL 访问 Windows 挂载盘（/mnt/c/...）的文件 I/O 特别慢。把仓库挪到 Linux 原生主目录下（~/code/），速度才正常。需要从 Windows 访问时，在资源管理器输 \\wsl$\Ubuntu\home\<user> 即可。

Windows 特有的三个坑

Mac/Linux 用户碰不到的坑，Windows 上一个不少。

坑一：路径反斜杠

Windows 路径用反斜杠 C:\Users\You\project，Unix 用正斜杠。Codex 大多数时候会自动处理，但有两处要自己上心：

写进 config.toml 的路径，建议老老实实写绝对路径
给 Codex 加沙箱可读目录时，路径必须是已存在的绝对目录

/sandbox-add-read-dir C:\absolute\directory\path

执行成功后，本次会话里后续在沙箱中跑的命令就能读这个目录了。注意只对当前会话有效，重开要重新加。

坑二：CRLF 换行符

这是 Windows 上用 Git 的通用问题，但 Codex 会改文件，所以特别容易在它身上撞见。

从 Mac/Linux 同事那 clone 来的项目是 LF，到了 Windows 上 Git 可能默认转成 CRLF。Codex 改完一保存，整个文件每行都「变」了，diff 直接爆炸，满屏 ^M。

最省事的解决办法是项目根目录放个 .gitattributes 文件：

* text=auto eol=lf

或者全局关掉 Git 的自动转换：

git config --global core.autocrlf false

Tip

别让换行符在平台间被偷偷改掉，否则你和 Codex 的每次改动都会被换行噪音淹没。团队统一约定即可。

坑三：Everyone 可写权限警告

原生跑的时候，Codex 可能会警告「某些文件夹对 Everyone 可写」。这不是 bug，是提醒你这些文件夹的 Windows 权限太宽了，沙箱保护不住。处理办法是去掉那些文件夹的 Everyone 写权限，然后重启 Codex。

坑	症状	怎么躲
路径反斜杠	配置路径不生效	写绝对路径，`/sandbox-add-read-dir` 用已存在的目录
CRLF 换行	diff 里每行都被改、满屏 `^M`	`.gitattributes` 统一 `eol=lf`
Everyone 可写	Codex 警告文件夹权限过宽	去掉 Everyone 写权限后重启

沙箱差异：Windows 跟 Mac/Linux 不一样

Codex 的沙箱在每个平台实现不同。Mac 用系统的 sandbox-exec，Linux 用 bubblewrap，Windows 是一套完全独立的两种模式。

原生 Windows 上，沙箱在 agent 模式下会拦住工作区之外的文件写入，也会拦住没经你同意的网络访问。在 config.toml 里配置：

# ~/.codex/config.toml
[windows]
sandbox = "elevated"
sandbox_private_desktop = true

两种模式的区别：

模式	强度	怎么实现	什么时候用
`elevated`（首选）	更强	专用低权限沙箱用户 + 文件系统权限边界 + 防火墙规则	默认就用它
`unelevated`（退路）	较弱	从当前用户派生受限令牌 + ACL 边界	elevated 装不上时顶着用

Warning

这跟某些老教程说的「推荐 unelevated」恰恰相反。官方明确写 elevated 是首选，unelevated 只是 elevated 因权限受限装不上时的临时退路。两种模式默认都开了「私有桌面」做 UI 隔离，别去关 sandbox_private_desktop。

报错排查：1385 和 1223

elevated 模式装不上，最典型的报错有两个。

报错 1385：意思是 Windows 拒绝给沙箱用户所需的登录权限。多见于公司管控电脑被 IT 策略拦截。按以下步骤排查：

找 IT 确认设备策略有没有给沙箱用户授予登录权限
对比组策略或 OU 差异
急着干活就先切 unelevated 顶着
把 CODEX_HOME/.sandbox/sandbox.log 连同 Windows 版本一起发给团队排查

报错 1223：症状是 elevated 模式下一让它改文件就报 ShellExecuteExW failed to launch setup helper: 1223，常伴随 libpng warning 和「找不到指定的模块」弹窗。多半是 npm 装的 sandbox-setup 二进制损坏了，重装覆盖即可：

npm.cmd uninstall -g @openai/codex
npm.cmd install   -g @openai/codex

Tip

碰到 elevated 模式不工作，按这条链走：先看报错码—1385 找 IT 放登录权限，1223 用 npm 重装覆盖—都解不了，再切 unelevated 顶着干活。

环境变量与代理配置

Windows 下设置 Codex 相关环境变量：

# 设置 Codex 主目录
set CODEX_HOME=C:\Users\YourName\.codex
set CODEX_SQLITE_HOME=C:\Users\YourName\.codex

# 设置代理
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

公司网络用了企业 TLS 代理或私有根 CA 时，直连会因证书校验失败而断：

set CODEX_CA_CERTIFICATE=C:\path\to\corporate-root-ca.pem

日志位置在 %USERPROFILE%\.codex\log\codex-tui.log，出问题时翻它能看到详细的错误信息。

PowerShell 与 CMD 中使用

Codex 在 PowerShell 和 CMD 里都能跑，会自动检测终端类型并优化输出：

# 启动交互模式
codex

# 非交互模式
codex exec "审查代码"

# 执行 PowerShell 命令
codex ! Get-Process

Note

推荐使用 Windows Terminal 或 PowerShell 7+，老版本 PowerShell 5.1 的 Out-File -Encoding utf8 会给文件加 BOM 头，可能让 git diff 多出编码噪音。PowerShell 7+ 可以改用 Set-Content -Encoding utf8NoBOM。

常见问题

Q：原生版本和 WSL 版本哪个好？

大多数用户选原生版本更好，更快更简单。只有项目本身在 Linux 里时才选 WSL2。

Q：可以和 WSL 共存吗？

可以，两者同时安装使用，互不干扰。

Q：需要管理员权限吗？

unelevated 模式不需要管理员权限。elevated 模式初始化时会弹 UAC 提示，自己的电脑点同意即可；公司电脑可能被锁。

Q：支持 PowerShell ISE 吗？

推荐使用 Windows Terminal 或新版 PowerShell，ISE 兼容性不佳。

小结

默认跑法：原生 Windows + elevated 沙箱，官方首选，最快且安全不打折
安装：一条 PowerShell 脚本搞定 CLI，前置盯紧 Windows 版本、winget 可用、管理员权限
三个特有坑：路径写绝对、换行用 .gitattributes 锁成 LF、Everyone 权限警告别忽视
沙箱差异：Windows 是独立的 elevated/unelevated 两套，跟 Mac 的 sandbox-exec、Linux 的 bubblewrap 都不一样
报错排查：1385 找 IT 放登录权限，1223 用 npm 重装覆盖，都解不了切 unelevated 顶着

Windows 上用 Codex 不比 Mac 难，就是多了「换行」和「沙箱模式」这两层 Windows 特有的认知税，交过一次就再也不踩了。