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

Codex CLI 安装前先确认两件事装 Codex CLI 最常见的场景是想在终端里直接让它读项目、改代码、解释报错而不是每次复制粘贴到网页。真正开始安装前建议先查两件事本机 Node.js 版本是否够新、当前网络是否能正常访问模型接口。很多“安装成功但不能用”的问题最后都卡在这两处。下面以 macOS、Linux、Windows PowerShell 都能参考的方式写一遍。命令略有差异的地方会单独说明。一、环境准备1. 检查 Node.js 和 npmCodex CLI 通常通过 npm 安装所以先确认本机已经安装 Node.js。建议使用较新的 LTS 版本不要用很老的 12、14 版本。### token云桥中转 0029.org ### node -v npm -v如果提示command not found说明还没装 Node.js。macOS 可以用 Homebrewbrew install nodeUbuntu / Debian 可以先用系统包管理器安装sudo apt update sudo apt install -y nodejs npmWindows 建议直接安装 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 KeyCodex CLI 需要模型接口的 Key。最常见的方式是配置环境变量OPENAI_API_KEY。macOS / Linuxexport OPENAI_API_KEY你的_API_Key这只对当前终端窗口生效。想永久生效可以写入 shell 配置文件echo export OPENAI_API_KEY你的_API_Key ~/.zshrc source ~/.zshrcWindows 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 / Linuxecho $OPENAI_API_KEYWindows PowerShellecho $env:OPENAI_API_KEY能看到值不代表一定正确但如果为空就说明配置没生效。2. 在空目录里测试新建一个测试目录避免工具第一次运行时扫描大型项目导致你误判为卡死。mkdir codex-test cd codex-test echo console.log(hello codex) index.js codex进入交互后可以先问一个很小的问题比如让它解释index.js。如果小目录能跑大项目不行再去看项目体积、权限、忽略文件等问题。五、网络验证很多人装完之后遇到的是请求超时、连接失败、401、403 这类问题。排查顺序建议这样来先看 Key401 多数和 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/completionsWindows PowerShell 里如果 curl 行为不一致可以用curl.execurl.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.org2. 安装成功但 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最后验证网络和模型权限。遇到问题时不要把安装、环境变量、网络访问混在一起判断。用小目录、最小请求、明确错误码一步步缩小范围基本都能定位到具体原因。