在 Windows 上正确安装 OpenAI Codex CLI：一次完整的 pnpm 全局环境修复实录
本文记录了一次在 Windows + pnpm 环境下安装 OpenAI Codex CLI 的完整踩坑与修复过程。
如果你遇到过pnpm global失败、NO_GLOBAL_BIN_DIR、安装卡死、PATH 混乱等问题，这篇文章可以作为一份可复用的工程级解决方案。
一、问题背景：Codex 安装为什么会这么“折磨”
我最初的目标非常简单：
pnpm i -g @openai/codex
结果却遇到了以下问题组合：
- pnpm 报错：
ERR_PNPM_NO_GLOBAL_BIN_DIR - npm / pnpm 全局安装长时间“转圈”
- Windows 下 PATH / 全局 bin 行为不透明
- 即使安装成功，也无法确认
codex是否真正可用
这类问题并不是 Codex 独有，而是 Windows + Node 全局工具链 的系统性问题。
二、核心结论先行（给着急的人）
如果你只关心最终答案：
在 Windows 上使用 pnpm 全局 CLI 的前提是：必须正确初始化
PNPM_HOME，并确保全局 bin 被实际生成。
Codex 安装失败，90% 不是 Codex 的问题，而是 pnpm 全局环境未就绪。
三、第一步：正确初始化 pnpm 全局环境（关键）
1️⃣ 执行 pnpm 官方初始化命令
pnpm setup
成功后，pnpm 会：
- 创建
PNPM_HOME - 修改用户级 PATH
- 输出提示：需要重开终端
⚠️ 这一步之后必须关闭 PowerShell 窗口并重新打开
2️⃣ 验证环境变量是否生效
重新打开 PowerShell 后执行：
echo $env:PNPM_HOME
pnpm -v
期望结果类似：
C:\Users\xxx\AppData\Local\pnpm
10.x.x
四、一个容易误判的点：PNPM_HOME 里只有 store/ 正常吗？
刚完成 pnpm setup 后，我看到的目录是：
C:\Users\xxx\AppData\Local\pnpm
└── store/
这是正常的，但还不算“完成” 。
原因是：
pnpm 只有在 第一次发生全局安装行为时，才会生成全局可执行文件（pnpm / pnpx shim）。
五、触发 pnpm 全局 bin 初始化（v10 正确方式）
在 pnpm v10 之后：
- ❌ 不再允许
pnpm add -g pnpm - ✅ 正确方式是：
pnpm self-update
执行完成后，再查看：
ls $env:PNPM_HOME
此时应该能看到类似内容：
.tools/
store/
pnpm
pnpm.CMD
pnpx
pnpx.CMD
这一步是 pnpm 全局环境真正就绪的标志。
六、验证 pnpx 是否可用（重要验收点）
不要用 pnpx --version（这是不支持的）。
正确的验证方式是：
pnpx cowsay hello
如果你看到一只牛输出 hello，说明：
- PNPM_HOME ✔
- PATH ✔
- pnpx / dlx 执行链 ✔
七、正式安装 OpenAI Codex CLI（可观测方式）
1️⃣（可选但强烈推荐）设置国内 registry
pnpm config set registry https://registry.npmmirror.com
避免 100MB+ 包下载卡死。
2️⃣ 安装 Codex（带 ndjson 日志）
pnpm add -g @openai/codex --reporter ndjson
在日志中你应该能看到：
@openai/codex@x.y.zresolved- fetched（完整下载）
- imported
- linked
- 没有 postinstall 错误
八、Codex 是否真正安装成功？最终验收标准
不要只看安装日志，看这一步：
codex --help
如果你能看到完整的 CLI 帮助，例如：
execreviewmcp / mcp-serversandboxapply--version
👉 这意味着 Codex CLI 已 100% 可用
九、关于 where codex 没有输出的说明
在 Windows + pnpm 场景下：
- 可执行文件通常是
codex.CMD - PowerShell 的
where有时不会显示 shim - 只要
codex能直接运行，就不是问题
十、登录与使用
首次使用前执行：
codex login
认证信息会保存在 ~/.codex/，不污染环境变量。
十一、一些经验总结（非常重要）
1️⃣ 不要急着怪 Codex
- Codex 安装慢 / 失败
→ 99% 是 Node 全局环境问题
2️⃣ Windows 下推荐顺序
pnpm setup
→ 重开终端
→ pnpm self-update
→ pnpx 验证
→ pnpm add -g @openai/codex
3️⃣ 如果只是“想用”，npx / pnpx 也是合理选择
pnpx @openai/codex
