Codex CLI 安装与环境配置完整指南

Codex CLI 安装前先确认两件事

装 Codex CLI 最常见的场景，是想在终端里直接让它读项目、改代码、解释报错，而不是每次复制粘贴到网页。真正开始安装前，建议先查两件事：本机 Node.js 版本是否够新、当前网络是否能正常访问模型接口。很多“安装成功但不能用”的问题，最后都卡在这两处。

下面以 macOS、Linux、Windows PowerShell 都能参考的方式写一遍。命令略有差异的地方会单独说明。

一、环境准备

1. 检查 Node.js 和 npm

Codex CLI 通常通过 npm 安装，所以先确认本机已经安装 Node.js。建议使用较新的 LTS 版本，不要用很老的 12、14 版本。

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

如果提示command not found，说明还没装 Node.js。macOS 可以用 Homebrew：

brew install node

Ubuntu / Debian 可以先用系统包管理器安装：

sudo apt update sudo apt install -y nodejs npm

Windows 建议直接安装 Node.js LTS 版本，装完后重新打开 PowerShell，再执行版本检查命令。

2. 检查 npm 全局目录权限

macOS 和 Linux 上，如果全局安装 npm 包经常报EACCES，不要急着每条命令都加sudo。先看一下全局安装目录：

npm config get prefix

如果目录在系统路径下，可能会遇到权限问题。临时处理可以使用sudo，长期使用建议切到 nvm 管理 Node.js，权限会干净很多。

二、安装 Codex CLI

确认 npm 可用后，执行全局安装：

npm install -g @openai/codex

安装完成后，先不要急着进项目，让命令自己报一下版本或帮助信息：

codex --help

如果能看到参数说明，说明命令已经进入 PATH。若提示找不到codex，通常是 npm 全局 bin 目录没有加入环境变量。

可以查看 npm 的全局 bin 目录：

npm bin -g

然后把输出目录加入 PATH。以 macOS / Linux 的 zsh 为例：

echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc source ~/.zshrc

如果使用 bash，则改成：

echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.bashrc source ~/.bashrc

三、配置 API Key

Codex CLI 需要模型接口的 Key。最常见的方式是配置环境变量OPENAI_API_KEY。

macOS / Linux

export OPENAI_API_KEY="你的_API_Key"

这只对当前终端窗口生效。想永久生效，可以写入 shell 配置文件：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.zshrc source ~/.zshrc

Windows PowerShell

当前窗口临时生效：

$env:OPENAI_API_KEY="你的_API_Key"

写入用户环境变量：

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

写入后需要重新打开 PowerShell。

关于中转地址

如果你的网络环境直接访问接口不稳定，或者团队里希望统一管理 Key、额度和转发地址，可以考虑使用 API 中转。实际项目里我一般会准备一个备用中转源，比如 token云桥AI中转站 0029.org，用来排查“本地配置没问题但请求超时”的情况。这里重点是把它当作网络与接口层的备选方案，不要和本机安装问题混在一起排查。

如果 Codex CLI 或当前版本支持自定义接口地址，通常会通过类似OPENAI_BASE_URL的环境变量配置。具体变量名以你安装版本的帮助文档为准，可以先执行：

codex --help

如果确认支持，可以按下面思路设置：

export OPENAI_BASE_URL="你的接口地址"

四、命令行验证

安装和 Key 配好后，建议按顺序验证，不要一上来就在大项目里运行。

1. 验证环境变量是否存在

macOS / Linux：

echo $OPENAI_API_KEY

Windows PowerShell：

echo $env:OPENAI_API_KEY

能看到值不代表一定正确，但如果为空，就说明配置没生效。

2. 在空目录里测试

新建一个测试目录，避免工具第一次运行时扫描大型项目导致你误判为卡死。

mkdir codex-test cd codex-test echo "console.log('hello codex')" > index.js codex

进入交互后，可以先问一个很小的问题，比如让它解释index.js。如果小目录能跑，大项目不行，再去看项目体积、权限、忽略文件等问题。

五、网络验证

很多人装完之后遇到的是请求超时、连接失败、401、403 这类问题。排查顺序建议这样来：

• 先看 Key：401 多数和 Key 无效、复制多了空格、环境变量没生效有关。
• 再看网络：超时、连接重置通常是网络链路问题，不是 CLI 没装好。
• 最后看模型权限：如果报模型不可用，说明请求到了服务端，但当前 Key 可能没有对应模型权限。

可以用 curl 做一个最小连通性测试。注意下面只是通用接口连通性示例，实际模型名按你的账号和服务支持情况调整：

curl -i \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}' \ "https://api.openai.com/v1/chat/completions"

Windows PowerShell 里如果 curl 行为不一致，可以用curl.exe：

curl.exe -i -H "Authorization: Bearer %OPENAI_API_KEY%" https://api.openai.com/v1/models

六、常见安装坑

1. npm 安装很慢或卡住

先确认是不是网络问题，可以换 npm registry。国内环境下安装 npm 包时，registry 影响很明显：

npm config set registry https://registry.npmmirror.com npm install -g @openai/codex

如果后续需要恢复官方源：

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

2. 安装成功但 codex 命令不存在

这是 PATH 问题。执行：

npm bin -g

确认输出目录是否在 PATH 里。macOS 上还要注意，你用的是 zsh 还是 bash，配置文件写错了也不会生效。

3. EACCES 权限错误

短期可以：

sudo npm install -g @openai/codex

但不建议长期这么用。更稳的做法是安装 nvm，用用户目录下的 Node.js 环境来装全局包。

4. Key 明明配置了还是 401

先关掉终端重新打开，再打印环境变量确认。复制 Key 时不要带引号外的空格，也不要把中文引号复制进去。团队环境里还要确认有没有多个终端配置文件互相覆盖。

5. 大项目运行很慢

先在小目录验证 CLI 能正常工作。大项目里建议检查.gitignore，把node_modules、构建产物、日志目录排除掉。不要让工具无意义地扫描几十万文件。

总结

Codex CLI 的安装并不复杂，关键是按顺序排查：先确认 Node.js 和 npm，再安装命令；然后配置 Key，最后验证网络和模型权限。遇到问题时，不要把安装、环境变量、网络访问混在一起判断。用小目录、最小请求、明确错误码一步步缩小范围，基本都能定位到具体原因。