1. 为什么值得花时间装好 Codex CLICodex CLI 是 OpenAI 官方推出的命令行编程助手它把大模型的代码生成、代码解释、文件读写、命令执行能力直接搬进了终端。你可以把它理解成一个住在你终端里的结对程序员你在项目目录下敲一句自然语言它就能读你的代码、改你的文件、跑你的测试甚至帮你把一整个功能模块从零搭起来。对于每天泡在终端里的开发者来说这种不离开命令行就能调用 AI 改代码的体验比在浏览器和编辑器之间来回切换要顺手得多。但问题也很现实Codex CLI 是一个基于 Node.js 生态分发的 npm 包这意味着你的机器上必须先有一套能正常工作的 Node.js 和 npm 环境。听起来简单实际上这一步劝退了相当多的人。我见过太多人在这一步卡住——Mac 上 Homebrew 装到一半报错Windows 上 PowerShell 提示禁止运行脚本npm 全局安装完codex命令却找不到或者运行起来直接甩一句unable to locate the codex cli binary or required runtime components。这些报错单看都很吓人但拆开来看绝大多数都是环境配置问题跟 Codex CLI 本身没多大关系。这篇内容就是来解决这些问题的。我会从零开始把 macOS、Windows、Linux 三个平台上的安装路径都讲清楚重点不是复制粘贴命令而是让你明白每一步在干什么、为什么这么干、出错了该往哪个方向查。适合完全没接触过 Codex CLI 的新手也适合装了但没装明白、被各种报错折腾过的朋友。读完你应该能做到在自己的机器上干净利落地装好 Codex CLI并且知道后续升级、卸载、排错该怎么处理。2. 安装前的环境盘点与方案选型2.1 Codex CLI 到底依赖什么在动手之前先把依赖关系理清楚这能帮你省掉后面一大半的排查时间。Codex CLI 的运行依赖链条其实很短Node.js 运行时Codex CLI 是用 JavaScript/TypeScript 写的通过 npm 分发所以必须有 Node.js。官方建议 Node.js 18 及以上版本我实测下来 20 LTS 和 22 LTS 都跑得很稳。版本太低会在启动时报模块导出相关的错误比如node:util does not provide an export named这类本质就是运行时 API 对不上。npm 包管理器Node.js 安装时会自带 npm一般不需要单独装。但 npm 的版本和镜像源配置会直接影响安装成功率。一个终端macOS 用自带的 Terminal 或 iTerm2 都行Windows 推荐用 Windows TerminalLinux 随意。网络能访问 npm registry这是国内用户最容易忽略的一点后面会专门讲镜像源。这里有个常见误区很多人以为要先把 Codex CLI 的二进制文件下载下来。其实不用它是标准的 npm 包npm install -g一条命令就能拉下来。你看到的unable to locate the codex cli binary报错通常不是没下载二进制而是npm 全局 bin 目录没进 PATH命令装了但系统找不到。2.2 三个平台的安装路径怎么选不同系统的最优路径不一样我按平台给你梳理一下你对号入座平台推荐 Node.js 安装方式包管理器备注macOSHomebrew 或官方 pkg 安装包npmApple Silicon 和 Intel 都支持Windows官方安装包.msi或 nvm-windowsnpm注意 PowerShell 执行策略Linuxnvm 或发行版包管理器npm服务器环境推荐 nvmmacOS 上我强烈建议用 Homebrew 装 Node.js因为后续升级、切换版本都方便。但 Homebrew 本身在 Intel Mac 和老系统上偶尔会出问题如果装不上退回到官方 pkg 安装包也完全可行别在这上面死磕。Windows 上最大的坑是 PowerShell 的执行策略默认状态下 npm 的.ps1脚本是被禁止运行的这个后面单独讲。Linux 服务器上用 nvm 管理 Node.js 版本是最灵活的方案尤其是你机器上还跑着别的 Node 项目、版本需求不一致的时候。2.3 关于镜像源的取舍国内直连 npm 官方源安装 Codex CLI 这种包体积不算大的还好但遇到依赖树深的时候会明显变慢甚至超时。换成国内镜像源能显著提速。但要注意一点镜像源有同步延迟极少数情况下最新版本还没同步过来这时候临时切回官方源即可。我的习惯是全局配一个国内镜像遇到装不上的包再单独指定官方源这样兼顾速度和成功率。3. 分平台安装实操全流程3.1 macOSHomebrew 与官方包两条路先说 Homebrew 这条路。打开终端先确认 Homebrew 是否已经装好brew --version如果提示command not found说明还没装。Homebrew 的安装命令官方会更新建议直接去官网复制最新的一行命令执行。装完之后用 Homebrew 安装 Node.jsbrew install node这条命令会同时装上 Node.js 和 npm。装完验证一下node -v npm -v两个都能打印出版本号说明环境 OK。这里有个细节Homebrew 装的 Node.js 路径在/opt/homebrew/binApple Silicon或/usr/local/binIntel正常情况下 Homebrew 会自动配好 PATH不需要你手动改。如果你在 Intel Mac 上遇到 Homebrew 装不上的情况别慌直接走官方 pkg 路线。去 Node.js 官网下载 LTS 版本的.pkg安装包双击一路下一步它会自动把 node 和 npm 装到/usr/local/bin并配好 PATH。这条路最省心缺点是升级要手动重新下载。装好 Node.js 之后安装 Codex CLI 就一条命令npm install -g openai/codex-g表示全局安装这样在任何目录下都能调用codex命令。装完验证codex --version能打印版本号就成功了。3.2 Windows绕开 PowerShell 执行策略的坑Windows 上装 Node.js我推荐直接去官网下载.msi安装包双击安装勾选Add to PATH。装完打开 Windows Terminal 或 CMD验证node -v和npm -v。接下来是重头戏。很多人在 Windows 上执行 npm 命令时会遇到这个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 npm 坏了而是 PowerShell 的默认执行策略Execution Policy出于安全考虑禁止运行.ps1脚本。解决办法有两个方案一改用 CMD 或 Git Bash 执行 npm 命令绕开 PowerShell 的限制。这是最省事的做法我个人在 Windows 上就习惯用 Git Bash。方案二修改 PowerShell 执行策略。以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的意思是本地写的脚本可以跑从网上下载的脚本需要有签名才能跑。这个策略在安全性和便利性之间比较平衡。改完之后重新打开终端npm 命令就能正常用了。注意不要图省事把执行策略设成Unrestricted那等于对所有脚本放行安全风险偏高。RemoteSigned足够日常开发使用。环境通了之后同样执行npm install -g openai/codex然后用codex --version验证。3.3 Linuxnvm 管理多版本更灵活Linux 上如果只是临时用一下用发行版自带的包管理器装 Node.js 也行比如 Ubuntu 上sudo apt install nodejs npm。但发行版仓库里的 Node.js 版本往往偏旧可能不满足 Codex CLI 对 Node.js 18 的要求。更推荐的做法是用 nvmNode Version Manager。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重新加载 shell 配置或者重开终端然后安装 Node.js 20 LTSnvm install 20 nvm use 20 nvm alias default 20nvm alias default 20这步很关键它把 20 设为默认版本否则每次新开终端都要手动nvm use。之后同样npm install -g openai/codex即可。3.4 配置 npm 镜像源提速不管你用哪个平台装之前建议先配好镜像源。查看当前源npm config get registry设置成国内镜像npm config set registry https://registry.npmmirror.com如果某个包在镜像上还没同步临时用官方源装npm install -g openai/codex --registryhttps://registry.npmjs.org这个技巧很实用平时用镜像享受速度遇到同步延迟时单独指定官方源两全其美。4. 安装后的验证与首次运行4.1 确认命令真的可用codex --version能打印版本号只说明命令被找到了。但有时候会出现一种诡异情况在某个终端里能用换个终端就提示codex: command not found。这几乎可以肯定是 PATH 的问题。npm 全局安装的包可执行文件会被放到 npm 的全局 bin 目录。查这个目录在哪npm config get prefix在 macOS/Linux 上全局 bin 目录通常是prefix/binWindows 上是prefix。如果这个目录不在你的 PATH 里命令就找不到。解决办法是把它加进 PATH。macOS/Linux 上编辑~/.zshrc或~/.bashrc加一行export PATH$(npm config get prefix)/bin:$PATHWindows 上则在系统环境变量的 Path 里加上 npm 全局目录通常是C:\Users\你的用户名\AppData\Roaming\npm。4.2 首次启动与登录命令可用之后在任意项目目录下执行codex首次运行会引导你完成登录授权。按提示操作即可。登录成功后你就进入了 Codex CLI 的交互界面可以直接用自然语言让它读代码、改代码。如果启动时报unable to locate the codex cli binary or required runtime components先别急着怀疑人生。这个报错九成是两种情况一是 Node.js 版本太低二是全局 bin 目录没进 PATH。按前面讲的方法逐一排查基本都能解决。4.3 一个最小可用示例装好之后找个测试项目试一下。进入一个空目录执行codex然后输入类似帮我写一个 Python 脚本读取当前目录下所有 txt 文件并统计行数这样的需求。看它能不能正常生成代码、能不能读写文件。这一步的目的是确认整条链路——模型调用、文件访问、命令执行——都是通的。5. 常见报错排查速查表安装过程中遇到的报错翻来覆去就那么几类。我把高频问题和对应解法整理成表方便你快速定位报错信息根本原因解决方向npm: command not foundNode.js/npm 没装或没进 PATH重装 Node.js检查 PATHnpm.ps1 因为在此系统上禁止运行脚本PowerShell 执行策略限制改用 CMD/Git Bash或设 RemoteSignedunable to locate the codex cli binary全局 bin 目录不在 PATH把 npm prefix 加进 PATHnode:util does not provide an export namedNode.js 版本过低升级到 18推荐 20 LTScodex --version有输出但运行报错运行时组件缺失或版本不匹配重装 Codex CLI确认 Node 版本安装卡住或超时网络访问 npm 源慢换国内镜像源npm warn deprecated node-domexception依赖包废弃警告属正常警告不影响使用可忽略关于最后那条node-domexception的废弃警告我特别说明一下这是某个间接依赖包发出的警告意思是这个包已经不再维护、建议用平台原生实现替代。它只是警告不是错误Codex CLI 照样能装能用。很多人看到黄色警告就以为装失败了其实完全没必要紧张。真正要关注的是红色的ERR开头的错误。再补充一个排查思路当你遇到任何 npm 相关的诡异问题先执行这三条命令看状态node -v npm -v npm config get prefix这三条能覆盖 80% 的环境问题。版本对不对、npm 在不在、全局目录在哪一目了然。6. 升级、卸载与几个实操心得6.1 升级和卸载怎么做Codex CLI 迭代比较快升级很简单npm update -g openai/codex或者直接重装最新版npm install -g openai/codexlatest卸载npm uninstall -g openai/codex如果你是用 Homebrew 装的 Node.js想彻底清理环境brew uninstall node之后还要注意清理残留的全局包目录否则重装后可能因为旧缓存出问题。Homebrew 卸载残留是个老话题简单做法是brew cleanup加上手动删掉~/.npm缓存目录。6.2 我踩过的几个坑第一个坑是版本混装。我早期在一台 Mac 上先用官方 pkg 装了 Node.js后来又用 Homebrew 装了一遍结果两个版本打架which node指向的路径和npm config get prefix对不上装完的 codex 命令死活找不到。后来把其中一个彻底卸干净才恢复正常。所以一台机器上尽量只用一种方式管理 Node.js。第二个坑是 Windows 上的终端选择。我在 PowerShell 里配好了环境结果换到 Windows Terminal 的另一个 profile 又不行了原因是不同 shell 读的环境变量不一样。Windows 上建议统一用一个终端并且改完环境变量后一定要重开终端窗口光刷新是不生效的。第三个坑是镜像源切换后忘了切回来。有次为了装一个刚发布的包临时用了官方源装完忘了改回镜像后面几天所有 npm 操作都慢得离谱查了半天才发现是源的问题。现在我的习惯是临时切换用命令行参数--registry不动全局配置避免这种低级失误。6.3 给新手的几条建议装环境这件事最忌讳的就是报错了就到处搜、搜到命令就复制粘贴。每个报错背后都有明确的原因先读懂报错信息再对症下药比盲目试错快得多。另外装完之后把node -v、npm -v、codex --version的输出记下来以后出问题时有对照基准。最后别在环境配置上追求一次到位装最新版LTS 版本才是生产环境该用的稳定压倒一切。Codex CLI 的安装本身不复杂复杂的是它背后那套 Node.js 工具链在不同系统上的差异。把这一层理顺了后面用它写代码、改项目就是水到渠成的事。下一篇我会讲装好之后怎么把它真正用起来包括项目上下文怎么给、常用命令怎么组织、怎么让它稳定地帮你干活。