Codex CLI Windows 安装完整指南 2026

Windows 上安装 Codex CLI 的三种方式

根据你的开发环境和习惯，有三种主流安装方式，选最适合自己的：

方式一：WSL2（推荐）

WSL2 提供完整的 Linux 内核，Node.js 工具链在 Linux 环境下兼容性最好，npm 全局包权限问题最少，也最接近生产服务器环境。如果你平时已经在用 WSL2 做开发，这是首选。

前提：已安装 WSL2 和 Ubuntu（或其他 Linux 发行版）。如未安装，在管理员 PowerShell 里运行：

PS> wsl --install
# 安装完成后重启 Windows，默认安装 Ubuntu

进入 WSL2（打开 Ubuntu 或在 Terminal 切换到 Ubuntu 标签），安装 Node.js 18+ 和 Codex CLI：

# 安装 nvm（Node 版本管理器）
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重开终端后安装 Node 22
$ nvm install 22 && nvm use 22
$ node -v   # v22.x.x

# 安装 Codex CLI
$ npm install -g @openai/codex

# 验证
$ codex --version

方式二：PowerShell + Node.js for Windows

不想装 WSL2 的用户，可以直接在 Windows 原生 PowerShell 里安装，使用 Windows 版 Node.js。

第一步：安装 Node.js LTS（从 nodejs.org 下载安装包，或用 winget）：

# 用 winget 安装 Node.js LTS（推荐，无需手动下载）
PS> winget install OpenJS.NodeJS.LTS

# 安装完成后重开 PowerShell 验证
PS> node -v   # v22.x.x 或更高

第二步：安装 Codex CLI：

PS> npm install -g @openai/codex
PS> codex --version

方式三：Git Bash / Scoop

如果你在用 Git Bash（Git for Windows 自带）或 Scoop 包管理器，也可以通过这些工具安装：

# 用 Scoop 安装 Node.js
> scoop install nodejs-lts

# 在 Git Bash 或 Scoop 环境下安装 Codex
> npm install -g @openai/codex
> codex --version

Git Bash 是 MSYS2 环境，行为上接近 Linux shell，大多数 bash 脚本可以直接运行。但路径格式（/c/Users/...）和 Windows 原生路径不同，偶尔需要注意。

Windows 特有的 Proxy 配置问题

这是 Windows 上运行 Codex CLI 最常见的拦路虎。不同安装方式的代理配置方法不同：

PowerShell 代理设置

在 PowerShell 中，系统代理不会自动被 Node.js 继承，需要手动设置环境变量：

# 假设本地代理监听在 7890 端口（Clash 默认）
PS> $env:HTTPS_PROXY = "http://127.0.0.1:7890"
PS> $env:HTTP_PROXY  = "http://127.0.0.1:7890"

# 验证代理生效
PS> codex "你好，测试连接"

如果想让代理在每次打开 PowerShell 时自动生效，把上面两行写入 PowerShell Profile：

# 打开 Profile 文件（不存在会自动创建）
PS> notepad $PROFILE

# 在 Profile 末尾添加：
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY  = "http://127.0.0.1:7890"

Clash / V2Ray 用户注意事项

使用 Clash for Windows 或 V2RayN 时，需要确保以下设置正确：

• 开启「允许局域网连接」（Allow LAN）——否则其他进程（包括 WSL2）无法通过 127.0.0.1 连接代理
• 确认 HTTP/HTTPS 代理端口（Clash 默认 7890，V2RayN 默认 10809）
• 使用系统代理模式时，PowerShell 里的 Node.js 进程不会自动读取 Windows 系统代理，仍需手动设置 $env:HTTPS_PROXY

WSL2 网络代理穿透（最常见问题）

WSL2 使用独立的虚拟网络适配器，有自己的 IP 地址，与 Windows 主机通过 NAT 通信。这意味着：

• Windows 系统代理设置对 WSL2 内的进程完全无效
• 在 Windows 里开了 Clash/V2Ray 等代理，WSL2 里的 Codex 照样无法连接 OpenAI
• 需要在 WSL2 内将 HTTPS_PROXY 指向 Windows 主机 IP

方法一：使用 Windows 主机 IP（推荐）

WSL2 的默认网关（即 Windows 主机在 WSL2 网络里的 IP）可以从 /etc/resolv.conf 里读取：

# 查看 Windows 主机 IP（WSL2 网关）
$ cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
# 通常输出类似 172.x.x.1

# 一行命令设置代理（替换 7890 为你实际的代理端口）
$ export HTTPS_PROXY=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):7890
$ export HTTP_PROXY=$HTTPS_PROXY

# 测试
$ curl -I https://api.openai.com

把这两行 export 写入 ~/.bashrc 或 ~/.zshrc 可以永久生效：

$ cat >> ~/.bashrc <<'EOF'
# Codex CLI / WSL2 代理配置
export HTTPS_PROXY=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):7890
export HTTP_PROXY=$HTTPS_PROXY
export NO_PROXY=localhost,127.0.0.1
EOF
$ source ~/.bashrc

方法二：使用 proxychains

如果你不想修改全局环境变量，可以用 proxychains-ng 为单个命令设置代理：

# 安装 proxychains-ng
$ sudo apt install proxychains4

# 编辑配置（把最后一行改为你的代理地址）
$ sudo nano /etc/proxychains4.conf
# 最后一行改为：
# http 172.x.x.1 7890

# 使用 proxychains 运行 codex
$ proxychains4 codex "帮我创建 hello.js"

PowerShell 无法运行脚本问题

Windows 默认限制 PowerShell 脚本执行，运行 codex 时可能报：

codex.ps1 cannot be loaded because running scripts is disabled on this system.
File ... cannot be loaded because the execution of scripts is disabled...

解决方法：以当前用户权限放开脚本执行策略（无需管理员权限）：

PS> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 输入 Y 确认

# 验证策略已更改
PS> Get-ExecutionPolicy -Scope CurrentUser
# RemoteSigned

RemoteSigned 策略允许运行本地脚本和来自可信发行者签名的远程脚本，是安全和实用性的平衡点。不建议使用 Unrestricted 或 Bypass。

Windows 常见报错

EPERM: operation not permitted

现象：npm install 或 codex 运行时出现 EPERM: operation not permitted, mkdir ... 或类似权限错误。

原因与解决：

• npm 全局目录权限问题：不要用 npm install -g 加 Administrator 账户，改用 nvm-windows（nvm-windows）管理 Node，nvm 的 npm 全局目录在用户目录下，无权限问题
• 防病毒软件拦截：Windows Defender 或第三方杀毒软件可能拦截 npm 包解压，临时关闭实时防护或为 npm 缓存目录设置排除
• 文件系统权限：在 WSL2 里，不要把项目放在 /mnt/c/...（Windows 文件系统），性能差且权限问题多；把项目放在 ~/（WSL2 Linux 文件系统）里

# 从 https://github.com/coreybutler/nvm-windows/releases 下载安装
# 安装后在普通 PowerShell（非管理员）里：
PS> nvm install 22
PS> nvm use 22
PS> npm install -g @openai/codex

'node' 不是内部命令 / node is not recognized

现象：'node' is not recognized as an internal or external command

原因：Node.js 安装路径没有加入 PATH 环境变量。

解决：

1. 用 winget 重新安装 Node：winget install OpenJS.NodeJS.LTS，安装程序会自动处理 PATH
2. 或手动添加：在「系统属性 → 环境变量 → Path」里加入 Node 安装目录（通常 C:\Program Files\nodejs）
3. 修改 PATH 后必须重开 PowerShell 才能生效

SSL 证书错误（企业网络）

现象：UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 SELF_SIGNED_CERT_IN_CHAIN

原因：公司网络使用了 SSL 检查（SSL inspection），用自签名企业证书替换了 OpenAI 的证书。

解决：让 IT 提供企业根证书（.crt 或 .pem 文件），然后：

# 方法一：通过环境变量指定额外的 CA 证书文件
PS> $env:NODE_EXTRA_CA_CERTS = "C:\path\to\company-root-ca.pem"

# 方法二（npm 安装时）：配置 npm cafile
PS> npm config set cafile "C:\path\to\company-root-ca.pem"

测试安装是否成功

完成安装和代理配置后，用以下步骤验证 Codex CLI 完全可用：

1. 检查版本号：
   终端复制

   $ codex --version
   # 输出版本号（如 0.1.x）即安装成功

2. 发送简单指令测试连接：
   终端复制

   $ codex "帮我创建一个 hello.js，输出 Hello from Codex!"
   # 正常会询问确认后创建文件

3. 运行生成的文件：
   终端复制

   $ node hello.js
   # Hello from Codex!

常见问题