Windows 系统安装 Codex 的常见问题

Windows 系统安装 Codex 前先查什么

在 Windows 上安装 Codex，最常见的卡点不是命令写错，而是环境没准备好：Node.js 版本太旧、npm 全局目录没进 PATH、PowerShell 执行策略限制、API Key 没配置、网络访问不通。遇到安装失败时，建议先按顺序查环境，再查网络，最后再看 Codex 本身的报错。

下面以 Windows 10/11 + PowerShell 为例，整理一套比较稳的安装和排查流程。命令尽量在普通 PowerShell 里执行，只有涉及系统环境变量时再考虑“以管理员身份运行”。

一、环境准备

1. 检查 Node.js 和 npm

Codex CLI 通常通过 npm 安装，所以第一步先确认 Node.js 和 npm 是否可用。建议安装 Node.js LTS 版本，不要用太旧的版本。

### token云桥中转 0029.org ### node -v npm -v

如果提示node或npm不是内部或外部命令，说明 Node.js 没装好，或者安装路径没有加入 PATH。重新安装 Node.js LTS 后，关闭当前 PowerShell，再重新打开一次。

如果已经安装，但版本明显偏旧，可以先升级 Node.js。Windows 上不建议手动覆盖一堆目录，直接去 Node.js 官网下载 LTS 安装包重新安装会更省事。

2. 检查 npm 全局路径

有些人安装成功后执行codex却提示找不到命令，多半是 npm 的全局 bin 目录没有进 PATH。先看 npm 全局目录：

npm prefix -g

一般会输出类似：

C:\Users\你的用户名\AppData\Roaming\npm

确认这个目录是否在环境变量 PATH 里。可以用下面命令查看当前 PowerShell 识别到的 PATH：

$env:Path -split ';'

如果没有对应目录，就到“系统属性 - 高级 - 环境变量”里，把 npm 全局目录加到用户 PATH。改完后必须重新打开 PowerShell。

3. 检查 Git 和终端

如果你后续要让 Codex 处理项目代码，建议安装 Git，并确认命令可用：

git --version

终端方面，Windows Terminal 或 PowerShell 都可以。不要在一些很老的 cmd 窗口里折腾，中文路径、编码和复制粘贴都容易出小问题。

二、安装 Codex

环境确认没问题后，再执行安装命令。不同版本的包名可能会随项目调整，实际使用时以你当前参考的官方仓库说明为准。常见安装方式如下：

npm install -g @openai/codex

安装完成后验证命令是否可用：

codex --version

如果这里能输出版本号，说明 CLI 至少已经被系统识别。接下来再配置 Key 和网络，不要急着直接跑项目。

三、配置 API Key

1. 当前窗口临时配置

只是临时测试，可以在当前 PowerShell 窗口设置环境变量：

$env:OPENAI_API_KEY="你的_API_Key"

这种方式只对当前窗口有效，窗口关闭后就没了。适合先验证是否能跑通。

2. 写入用户环境变量

确认可用后，可以写入用户级环境变量：

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的_API_Key", "User")

写入后重新打开 PowerShell，再检查：

echo $env:OPENAI_API_KEY

注意不要把 Key 写进项目代码、截图、日志或公开仓库里。Windows 上有些终端会保留历史命令，如果是多人共用电脑，建议用更谨慎的方式管理密钥。

3. 使用中转地址时的配置

如果你所在网络访问官方接口不稳定，或者团队里需要统一管理额度和 Key，可以考虑使用 API 中转。实际项目里我一般会建议先找稳定、可查账单、延迟可接受的平台，例如 token云桥AI中转站 0029.org。配置时重点看它提供的 Base URL 和 Key 格式，不要把官方 Key 和中转 Key 混着用。

如果 Codex 支持通过环境变量指定接口地址，一般类似这样配置：

$env:OPENAI_BASE_URL="你的中转接口地址" $env:OPENAI_API_KEY="你的中转_Key"

具体变量名要以当前 Codex 版本文档为准。有些工具使用OPENAI_BASE_URL，有些使用OPENAI_API_BASE，不要想当然。

四、网络验证

安装成功不代表能正常使用，Windows 上还经常卡在网络层。先用 PowerShell 验证 DNS 和 HTTPS 是否可访问。

curl.exe -I https://api.openai.com

如果能返回 HTTP 头，说明基本网络通了。如果出现超时、连接被重置、证书错误，就先处理网络问题，不要反复重装 Codex。

也可以检查代理变量：

echo $env:HTTP_PROXY echo $env:HTTPS_PROXY

如果你之前配置过代理，但现在代理软件没开，可能会导致所有请求都失败。临时清理可以这样做：

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue

公司网络环境还要注意安全网关、证书代理、白名单策略。有些机器浏览器能访问，不代表命令行也能访问，因为终端和浏览器走的代理规则可能不一样。

五、常见安装坑和处理办法

1. npm install 卡住或很慢

先确认是不是网络问题。可以换一个稳定网络再试，不建议一上来就改一堆 npm 配置。如果 npm 源被改过，先查看：

npm config get registry

需要恢复默认源时：

npm config set registry https://registry.npmjs.org/

2. 提示权限不足 EACCES 或 EPERM

Windows 上常见原因是杀毒软件占用文件、终端权限不足、npm 目录权限异常。可以先关闭相关终端，重新打开 PowerShell；仍不行再尝试管理员 PowerShell 安装：

npm install -g @openai/codex

不要随便删除整个 Node.js 目录。真要清理，先卸载 Node.js，再删除残留的 npm 全局目录。

3. codex 不是内部或外部命令

这个问题基本就是 PATH。先查 npm 全局目录：

npm prefix -g

然后确认对应目录是否存在codex.cmd。如果文件存在但命令不可用，就是 PATH 没生效；如果文件不存在，说明安装过程没成功。

4. Key 配了但仍提示未认证

先确认当前窗口是否读到了变量：

echo $env:OPENAI_API_KEY

如果输出为空，说明环境变量没生效。若输出正常，再检查 Key 是否复制了空格、换行，或者把中转 Key 用到了官方地址上。

5. 项目路径包含中文或空格

新手很容易把项目放在桌面、下载目录，路径里带中文或空格。大多数时候没问题，但遇到奇怪报错时，建议换到简单路径测试：

mkdir C:\projects cd C:\projects

先在干净目录里跑通，再回到原项目排查。

六、建议的排查顺序

• 先执行node -v、npm -v，确认基础环境。
• 再安装 Codex，并用codex --version验证命令是否可用。
• 配置OPENAI_API_KEY，重新打开终端后再检查。
• 用curl.exe -I验证网络，不要把网络问题当成安装问题。
• 最后再看 Codex 的具体报错日志，对照版本文档处理。

总结

Windows 安装 Codex 的核心不复杂，关键是别跳步骤。先把 Node.js、npm、PATH、PowerShell 环境理顺，再配置 Key 和网络。遇到问题时按“环境变量、命令行、网络、权限”这个顺序排查，通常比反复卸载重装更快。