1. 为什么值得花时间把 Codex CLI 装明白Codex CLI 是 OpenAI 推出的命令行 AI 编程助手直接跑在终端里能读你本地的代码、执行命令、改文件、跑测试把“对话式编程”从网页搬到了你每天敲命令的地方。它不是一个简单的聊天窗口套壳而是一个能真正操作你项目目录的 agent 工具。你可以在终端里让它“帮我把这个函数重构成异步的”“找出这个 bug 并修复”“给这个模块补上单元测试”它会自己去读文件、改代码、跑验证。但问题来了——这东西的安装过程比想象中要折腾。我在几个不同环境里装过macOS 的 M 系列芯片、Intel 芯片的旧 Mac、Windows 11 的 PowerShell、还有一台 Ubuntu 的云主机。踩过的坑包括但不限于codex: command not found、chatgpt failed to start. unable to locate the codex cli binary or required runtime components、npm 全局安装后 PATH 没配好、Windows 上 PowerShell 执行策略拦截 npm 脚本、Homebrew 在 Intel Mac 上装到一半报错、Node.js 版本太老导致依赖装不上。这篇是系列第一篇只干一件事把 Codex CLI 装到你的机器上并且能正常跑起来。不管你是 macOS、Windows 还是 Linux不管你用 npm 还是 Homebrew我都会把每条路径讲清楚包括那些官方文档一笔带过、但实际会卡住你的细节。适合刚接触命令行工具的新手也适合装了一半卡住的老手直接跳到你对应的章节。核心关键词先摆出来Codex CLI、npm、Homebrew、Node.js、安装指南。这四个词贯穿全文你只要跟着走装完不会有“unable to locate the codex cli binary”这种报错。2. 装之前先搞清楚Codex CLI 到底依赖什么2.1 运行时的硬性依赖Node.js 版本是第一个门槛Codex CLI 是通过 npm 分发的本质是一个 Node.js 包。这意味着你的机器上必须先有 Node.js而且版本不能太低。根据我实际测试Node.js 18 是最低要求推荐 20 LTS 或更高。如果你用的是 Node.js 16 甚至更早npm 在解析依赖树的时候就会报错典型的是The requested module node:util does not provide an export named这类 ESM 相关的错误——因为新版本的包用了较新的 Node API老运行时根本不认。怎么查自己当前的版本node -v npm -v如果node -v输出的是v16.x或者更低别犹豫先去升级 Node.js。升级方式取决于你当初怎么装的用 Homebrew 装的走brew upgrade node用官方安装包装的去官网下新的 pkg用 nvm 管理的直接nvm install 20 nvm use 20。我强烈建议用 nvm 管理 Node 版本尤其是你机器上还有别的项目依赖老版本 Node 的时候nvm 能让你在不同版本之间秒切不会互相污染。注意不要用sudo npm install -g去装全局包。用 sudo 装出来的全局包后续升级、卸载都会遇到权限问题而且 PATH 经常配不对。如果遇到权限报错正确做法是配置 npm 的全局目录到用户目录下而不是加 sudo。2.2 包管理器选型npm、Homebrew 还是直接下二进制Codex CLI 官方主推的安装方式是通过 npm 全局安装。但在 macOS 上Homebrew 也是一个可选路径。这两条路各有适用场景我整理了一个对照表安装方式适用平台优点缺点推荐场景npm 全局安装全平台官方主推版本最新升级方便依赖 Node.js 环境PATH 需配置已有 Node.js 环境的开发者HomebrewmacOS / Linux自动处理依赖卸载干净Intel Mac 上偶发报错版本可能滞后macOS 用户且已用 Homebrew 管理软件直接下载二进制全平台不依赖 Node.js需手动配置 PATH升级麻烦不想装 Node.js 的极简主义者我的建议很直接如果你已经在写 JavaScript/TypeScript直接用 npm 装最省事。如果你机器上压根没有 Node.js又不想为了一个工具装整个运行时那 macOS 用户走 Homebrew其他平台走二进制。下面每个路径我都会展开讲。2.3 网络环境的现实问题npm 源和下载速度国内网络环境下npm 默认源registry.npmjs.org的下载速度经常让人崩溃装一个包等几分钟是常态有时候直接超时失败。这不是 Codex CLI 的问题是网络链路的问题。解决办法是切换到国内镜像源。临时切换只对当前命令生效npm install -g openai/codex --registryhttps://registry.npmmirror.com永久切换写入 npm 配置npm config set registry https://registry.npmmirror.com切完之后可以用npm config get registry确认。想切回官方源就npm config set registry https://registry.npmjs.org。这个镜像源是同步官方仓库的包的内容一致只是下载走国内 CDN速度快很多。我实测同一个包官方源 3 分钟没下完镜像源 15 秒搞定。提示切换镜像源之后如果遇到某个包版本对不上先npm cache clean --force清一下缓存再重装。镜像同步有延迟极少数情况下最新版本还没同步过来。3. macOS 安装实操从零到 codex 能跑3.1 先装 Homebrew如果还没装Homebrew 是 macOS 上最主流的包管理器装软件、装依赖都靠它。检查是否已安装brew --version如果提示command not found说明没装。官方安装命令是一条 Ruby 脚本但国内网络直接跑大概率卡住。我的做法是先用国内镜像的安装脚本/bin/zsh -c $(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)这个脚本会引导你选择镜像源然后自动完成安装。装完之后关键一步是配置环境变量。M 系列芯片的 MacHomebrew 装在/opt/homebrewIntel 芯片的 Mac装在/usr/local。你需要把对应的 bin 目录加到 PATH 里。脚本一般会自动帮你写好但如果你手动装的检查~/.zshrc里有没有这两行# M 系列芯片 eval $(/opt/homebrew/bin/brew shellenv) # Intel 芯片 eval $(/usr/local/bin/brew shellenv)改完source ~/.zshrc生效。这时候再跑brew --version应该能正常输出了。Intel Mac 用户特别注意有些老系统版本上Homebrew 安装会报Error: Failure while executing之类的错误多半是 Xcode Command Line Tools 没装全。跑一下xcode-select --install把命令行工具补齐再重试。3.2 用 Homebrew 装 Node.jsNode.js 装好是后续所有操作的基础brew install node装完验证node -v npm -v正常应该输出类似v20.x.x和10.x.x。如果node -v报错检查 PATH 里有没有/opt/homebrew/bin或/usr/local/bin。Homebrew 装的 Node 会自动带上 npm不需要单独装。3.3 用 npm 全局安装 Codex CLI这一步是核心npm install -g openai/codex如果你已经切了国内镜像源这条命令应该几十秒内完成。装完之后验证codex --version能输出版本号就说明装好了。如果报command not found说明 npm 的全局 bin 目录不在 PATH 里。查一下全局目录在哪npm config get prefix假设输出是/opt/homebrew那 bin 目录就是/opt/homebrew/bin确认它在 PATH 里。如果输出是/usr/local同理。如果 prefix 指向一个奇怪的地方比如~/.npm-global你需要手动把~/.npm-global/bin加到 PATH。3.4 Homebrew 直接装 Codex CLI可选路径如果你不想通过 npmHomebrew 也能直接装brew install codex但要注意Homebrew 的 formula 更新可能滞后于 npm 官方版本。装完同样用codex --version验证。这条路径的好处是卸载干净brew uninstall codex坏处是版本可能不是最新的。我个人还是推荐 npm 路径版本跟进更及时。4. Windows 安装实操绕开 PowerShell 的那些坑4.1 装 Node.js官网下载还是包管理器Windows 上装 Node.js 最稳的方式是去官网下 LTS 版本的安装包.msi双击一路下一步。安装程序会自动把 Node 和 npm 加到系统 PATH 里。装完打开新的 PowerShell 或 CMD 窗口跑node -v和npm -v验证。如果你用 winget也可以winget install OpenJS.NodeJS.LTS装完记得关掉当前终端重新开一个否则 PATH 更新不会生效。这是 Windows 上最常见的“装了但找不到命令”的原因。4.2 解决 npm.ps1 无法加载的问题Windows 上跑 npm 命令很多人会遇到这个报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这是 PowerShell 的执行策略Execution Policy在拦截脚本。解决办法是以管理员身份打开 PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。这条命令的意思是允许当前用户运行本地脚本和已签名的远程脚本。改完之后再跑 npm 命令就不会被拦了。注意不要用Set-ExecutionPolicy Unrestricted那等于完全放开安全性差。RemoteSigned是微软推荐的平衡方案。4.3 全局安装 Codex CLI 并配置 PATH执行npm install -g openai/codex装完跑codex --version。如果报codex 不是内部或外部命令说明 npm 全局目录不在 PATH。查一下npm config get prefix假设输出C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统环境变量 PATH 里。操作步骤Win 键搜索“环境变量” → 编辑系统环境变量 → 环境变量 → 在“用户变量”里找到 Path → 编辑 → 新建 → 粘贴路径 → 确定。改完必须重开终端。4.4 Windows Terminal 里的特殊情况有反馈说在 Windows Terminal 里codex --version能查到版本但实际运行时报unable to locate the codex cli binary or required runtime components。这种情况多半是 Codex CLI 在运行时去 spawn 子进程但子进程的环境变量和当前 shell 不一致导致的。我的排查思路是确认where codex能找到可执行文件路径确认该路径和npm config get prefix下的 bin 目录一致在 CMD 里不是 PowerShell跑一次codex --version排除 shell 差异如果 CMD 正常、PowerShell 不正常检查 PowerShell 的 profile 里有没有覆盖 PATH实在搞不定用 CMD 作为默认终端跑 Codex CLI能绕开大部分 PowerShell 特有的问题。5. Linux 安装实操最顺滑但也别大意5.1 用 nvm 装 Node.jsLinux 上我强烈推荐用 nvm 管理 Node 版本避免和系统自带的 Node 冲突很多发行版自带老版本 Node直接apt install nodejs装出来的版本可能不满足要求。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完重开终端或者source ~/.bashrc。然后nvm install 20 nvm use 20 nvm alias default 20nvm alias default 20这步很重要它让新开的终端默认用 Node 20不然每次都要手动nvm use。5.2 npm 全局安装与权限处理npm install -g openai/codexLinux 上如果遇到EACCES权限错误不要加 sudo。正确做法是配置 npm 的全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH写进~/.bashrc或~/.zshrcexport PATH~/.npm-global/bin:$PATH重开终端后重新装一次就不会有权限问题了。5.3 验证安装与首次运行codex --version codex --help--help能列出所有子命令和参数说明安装完整。首次运行 Codex CLI 会引导你配置 API 认证这一步涉及账号登录按提示操作即可。如果认证环节报错先确认网络能正常访问相关服务再检查版本是不是最新的npm update -g openai/codex。6. 装完之后的验证清单和常见报错速查6.1 安装成功的三个验证动作装完别急着用先跑这三步确认环境没问题node -v输出 18 以上npm -v正常输出版本号codex --version正常输出版本号三个都过基本就没问题了。再跑一次codex --help确认子命令列表完整。6.2 常见报错与对应解法速查表报错信息根本原因解决方法codex: command not foundnpm 全局 bin 不在 PATH把npm config get prefix下的 bin 目录加入 PATHunable to locate the codex cli binary or required runtime components运行时找不到二进制或环境变量不一致确认where codex路径正确换 CMD 测试重装npm : 无法加载文件 npm.ps1PowerShell 执行策略拦截Set-ExecutionPolicy RemoteSigned -Scope CurrentUserThe requested module node:util does not provide an export namedNode.js 版本过低升级到 Node 18推荐 20 LTSEACCES权限错误全局目录权限不足配置 npm prefix 到用户目录不要用 sudoHomebrew 安装报错Xcode CLT 缺失或镜像问题xcode-select --install换国内镜像脚本npm 安装超时默认源网络慢切换国内镜像源registry.npmmirror.com6.3 我踩过的几个坑你可以直接跳过第一个坑在 Intel Mac 上用官方 Homebrew 脚本装卡在Downloading半小时没动静。换成国内镜像脚本两分钟装完。第二个坑Windows 上装完 Node 没重开终端一直报npm 不是内部或外部命令折腾了二十分钟才反应过来。第三个坑用sudo npm install -g装完后来升级时各种权限报错最后只能手动删目录重装。第四个坑Node 版本是 16装 Codex CLI 时依赖解析直接失败报了一堆 ESM 相关的错升级到 20 之后一次过。这些坑的共同点是都不是 Codex CLI 本身的问题而是环境准备没做到位。所以我在前面花了大量篇幅讲 Node.js 版本、PATH 配置、镜像源、执行策略这些才是决定安装成败的关键。6.4 升级和卸载的正确姿势升级npm update -g openai/codex或者指定版本npm install -g openai/codexlatest卸载npm uninstall -g openai/codexHomebrew 装的用brew upgrade codex和brew uninstall codex。卸载后如果还有残留的配置目录一般在~/.codex或~/.config/codex手动删掉即可。我一般会保留配置目录因为里面可能有认证信息和自定义设置重装后能直接复用。装好之后下一篇我会讲 Codex CLI 的实际使用怎么让它读项目、怎么下指令、怎么控制它改文件的范围、怎么接入日常工作流。安装只是第一步真正提效的是用起来之后的那些技巧。如果你在安装过程中遇到这篇没覆盖的报错把完整报错信息贴出来多半是环境变量或者版本的问题顺着这两条线查基本都能解决。