在 Windows 上正确安装 OpenAI Codex CLI：一次完整的 pnpm 全局环境修复实录

本文记录了一次在 Windows + pnpm 环境下安装 OpenAI Codex CLI 的完整踩坑与修复过程。

如果你遇到过 pnpm global 失败、NO_GLOBAL_BIN_DIR、安装卡死、PATH 混乱等问题，这篇文章可以作为一份可复用的工程级解决方案。

一、问题背景：Codex 安装为什么会这么"折磨"

我最初的目标非常简单：

css 复制代码

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 官方初始化命令

arduino 复制代码

pnpm setup

成功后，pnpm 会：

创建 PNPM_HOME
修改用户级 PATH
输出提示：需要重开终端

⚠️ 这一步之后必须关闭 PowerShell 窗口并重新打开

2️⃣ 验证环境变量是否生效

重新打开 PowerShell 后执行：

bash 复制代码

echo $env:PNPM_HOME
pnpm -v

期望结果类似：

makefile 复制代码

C:\Users\xxx\AppData\Local\pnpm
10.x.x

四、一个容易误判的点：PNPM_HOME 里只有 `store/` 正常吗？

刚完成 pnpm setup 后，我看到的目录是：

makefile 复制代码

C:\Users\xxx\AppData\Local\pnpm
└── store/

这是正常的，但还不算"完成" 。

原因是：

pnpm 只有在 第一次发生全局安装行为时，才会生成全局可执行文件（pnpm / pnpx shim）。

五、触发 pnpm 全局 bin 初始化（v10 正确方式）

在 pnpm v10 之后：

❌ 不再允许 pnpm add -g pnpm
✅ 正确方式是：

lua 复制代码

pnpm self-update

执行完成后，再查看：

bash 复制代码

ls $env:PNPM_HOME

此时应该能看到类似内容：

swift 复制代码

.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

arduino 复制代码

pnpm config set registry https://registry.npmmirror.com

避免 100MB+ 包下载卡死。

2️⃣ 安装 Codex（带 ndjson 日志）

sql 复制代码

pnpm add -g @openai/codex --reporter ndjson

在日志中你应该能看到：

@openai/codex@x.y.z resolved
fetched（完整下载）
imported
linked
没有 postinstall 错误

八、Codex 是否真正安装成功？最终验收标准

不要只看安装日志，看这一步：

bash 复制代码

codex --help

如果你能看到完整的 CLI 帮助，例如：

exec
review
mcp / mcp-server
sandbox
apply
--version

👉 这意味着 Codex CLI 已 100% 可用

九、关于 `where codex` 没有输出的说明

在 Windows + pnpm 场景下：

可执行文件通常是 codex.CMD
PowerShell 的 where 有时不会显示 shim
只要 codex 能直接运行，就不是问题

十、登录与使用

首次使用前执行：

复制代码

codex login

认证信息会保存在 ~/.codex/，不污染环境变量。

十一、一些经验总结（非常重要）

1️⃣ 不要急着怪 Codex

Codex 安装慢 / 失败
→ 99% 是 Node 全局环境问题

2️⃣ Windows 下推荐顺序

sql 复制代码

pnpm setup
→ 重开终端
→ pnpm self-update
→ pnpx 验证
→ pnpm add -g @openai/codex

3️⃣ 如果只是"想用"，npx / pnpx 也是合理选择

bash 复制代码

pnpx @openai/codex

在 Windows 上正确安装 OpenAI Codex CLI：一次完整的 pnpm 全局环境修复实录