mac 上跑npm install -g openai/codex装 Codex CLI 的时候不少朋友应该都撞过这个场景命令刚执行没几秒终端就蹦出一串红色报错里面最扎眼的那个是npm error code ENOTEMPTY。我头一回看到这个错误码也愣了一下ENOTEMPTY 平时真不常见网上一搜信息还特别零散有人说清缓存有人让删目录还有人干脆建议重装 Node.js——这显然不是最优解。这篇就围绕「mac npm codex ENOTEMPTY」这条报错链路把问题背后的安装机制拆开讲清楚再给一套从环境自检到彻底重装的完整操作流程。顺带把安装成功后 codex 运行时可能碰到的代理报错、deprecated 提示这类后遗症一起解决掉。适合初次在 mac 上安装 codex 的新手也适合想彻底搞懂 npm 这类诡异报错的开发者。1. 先把 ENOTEMPTY 的来龙去脉搞清楚1.1 报错信息拆解npm 到底在哪个环节翻了车很多人看到npm error code ENOTEMPTY的第一反应是“没看懂继续搜”但拆开看其实并不复杂。ENOTEMPTY 是系统层面的错误码英文全称是Directory not empty翻译过来就是“目录非空”。macOS 文件系统在执行某些操作时如果发现目标目录里面还有文件或子目录并且操作要求目标目录必须为空就会返回这个错误。npm 的安装过程并不是很多人以为的“把包解压到 node_modules 就完事”。npm 在安装一个全局包时大致会分这么几步把包下载到 npm 自己的缓存目录~/.npm/_cacache在目标 node_modules 下创建临时目录常见的是一级.staging目录把解压好的文件从缓存中写入.staging临时目录最后把临时目录重命名成正式的包目录比如node_modules/openai/codex。问题就出在第 4 步。这个“重命名”操作要求目标位置不能存在同名目录或者如果存在同名目录这个目录得是空的。当系统发现node_modules/openai/codex已经存在并且里面还有一堆残留文件时就会直接丢出 ENOTEMPTY。我实际遇到过的情况是之前一次安装因为网络抖动被中断npm 已经把 codex 的部分文件写进了openai/codex目录但后续步骤没有完成。第二次重装时npm 想重新创建这个目录结果发现它非空于是直接罢工。1.2 为什么 macOS 上这个错误尤其容易复现ENOTEMPTY 并不是 mac 专属Linux 上也会出现但 macOS 上有几个特有的“坑”会显著提高触发概率这里值得单独说一下。第一macOS 默认的 APFS 文件系统对大小写不敏感。这意味着OpenAI和openai在绝大多数情况下会被当成同一个目录。npm 在安装openai/codex时会同时操作node_modules/openai这个作用域目录如果之前曾经用某个包创建过同名但大小写不同的目录文件系统层面就可能产生冲突。第二macOS 的 Spotlight 索引、第三方安全软件实时扫描会在文件重命名瞬间短暂占用目录句柄。虽然这个概率不高但在包体积较大、目录层级较深时更容易触发。Codex 这个 CLI 工具本身依赖不少原生模块文件数量多重命名耗时相对长恰好就比普通包更容易踩中这个窗口期。第三也是最常见的原因全局 node_modules 目录的权限混乱。很多 mac 用户安装 Node.js 时用的是 Homebrew而 Homebrew 安装 Node 的目录要么是/usr/local要么是/opt/homebrew。如果你之前使用过sudo npm install安装过全局包那么某些目录的 owner 就变成了 root。后续再用普通用户身份执行 npm 安装时npm 无法删除或覆盖这些 root 属主的目录也会在“目录非空”这一步直接报错。1.3 从日志里找真正原因不要盲猜ENOTEMPTY 报错信息本身比较简短但 npm 通常会附上更详细的上下文。执行安装命令时如果报错不要急着关终端把完整输出多看几行重点找这几类线索npm error path ...报错的具体路径能直接告诉你到底是哪个目录出了问题npm error syscall rename说明卡在重命名阶段npm error errno -66-66 是 ENOTEMPTY 在 macOS 上的数字编号npm error dest ...重命名的目标目录。如果输出信息不够多还可以用npm install -g openai/codex --loglevel verbose重新跑一遍npm 会打印每一步操作的详细日志能看到它具体在哪一步、操作哪个路径时失败。注意macOS 上看到syscall rename和errno -66这两个信息基本可以锁定是 ENOTEMPTY不用再怀疑其他原因。2. 动手修复前先做一轮环境自检2.1 确认 Node.js 和 npm 的版本与全局目录我见过不少人装 codex 报错排查了半天最后发现是自己 Node.js 版本太老npm 的行为和现代版本不一样导致一系列诡异问题。所以第一步不是清理缓存而是先确认环境。在终端依次执行node -v npm -v npm config get prefix npm root -gnpm config get prefix会输出 npm 安装全局包的根目录比如/usr/local或/opt/homebrew。npm root -g则直接给出全局 node_modules 的完整路径比如/opt/homebrew/lib/node_modules。记住这个路径后面清理残留目录时会用到。如果你是用 Homebrew 安装的 Node.js并且电脑是 Apple Silicon 芯片全局目录通常在/opt/homebrew/lib/node_modules如果是 Intel 芯片则一般在/usr/local/lib/node_modules。如果你用的是官方 pkg 安装包路径可能是/usr/local/lib/node_modules。这里没有标准答案一切以你本机npm root -g的输出为准。2.2 检查全局目录权限是不是被 sudo 污染过这一步非常关键mac 上 ENOTEMPTY 有很多次都是权限问题伪装成目录冲突。执行ls -ld $(npm root -g) ls -ld $(npm root -g)/openai 2/dev/null || echo 目录不存在如果看到目录 owner 是 root而你当前登录用户不是 root那么你普通用户执行 npm install 时对目录里面的文件没有写权限。npm 尝试清理旧文件时就会失败表现出来可能就是 ENOTEMPTY有时候也会变成 EACCES。最稳妥的解决思路是不要用sudo npm install -g而是用 nvm 这类 Node 版本管理器把 Node 安装到用户目录下全局包也自然落在用户目录从根上避开权限问题。# 如果还没有 nvm可以按 nvm 官方 README 安装 # 安装完成后node、npm 和全局 node_modules 都会在用户目录下 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash如果你不想切换 Node 版本管理器也可以简单地把全局目录授权给自己但这需要你明确知道当前目录的确切路径sudo chown -R $(whoami) $(npm root -g)这条命令的意思是把全局 node_modules 目录的所有权从 root 改成当前用户。执行之后npm 不需要 sudo 也能正常创建和删除目录。2.3 检查 npm 镜像源配置避免“源不对”带来的干扰在 mac 上安装 codex 时npm 默认从官方源下载但国内用户为了提速通常会配置镜像源。npm 镜像源配置本身没有问题但如果配置了老的淘宝源https://registry.npm.taobao.org在某些情况下会碰到证书过期错误CERT_HAS_EXPIRED表现和 ENOTEMPTY 不同但同样会中断安装。查看当前源npm config get registry如果输出的是https://registry.npmjs.org/那说明是官方源。如果输出的是老淘宝源建议切换到新的 npmmirror 源npm config set registry https://registry.npmmirror.com或者直接编辑~/.npmrc文件把 registry 那一行改成新地址。改完后重新检查一遍确认生效即可。提示npm 的 registry 配置是全局生效的改完后所有 npm install 都会走新源。如果之前做过某些包的私有源配置改动前先看一眼~/.npmrc里的完整内容。3. 解决 ENOTEMPTY 的完整实操从清理到重装3.1 第一步安全卸载可能存在的 codex 残留在清理之前先尝试用 npm 正常卸载一遍 codex。虽然 ENOTEMPTY 报错说明卸载可能也会遇到问题但值得先试一次因为如果卸载能成功后面会省很多事npm uninstall -g openai/codex如果卸载成功终端没有任何报错那么直接跳到 3.4 重新安装。如果卸载过程还是报 ENOTEMPTY或者提示目录不存在那么进入下面的手动清理流程。3.2 第二步确认并手动删除残留目录卸载失败时最直接的办法就是手动删除残留的 codex 目录。先定位目录位置npm root -g假设输出的全局 node_modules 路径是/opt/homebrew/lib/node_modules那么需要重点检查这几个位置/opt/homebrew/lib/node_modules/openai这是 codex 包的主目录如果存在且里面有残留文件直接删掉整个openai作用域目录。/opt/homebrew/lib/node_modules/codex有些情况下 npm 会生成不带 scope 的目录存在也一并删掉。/opt/homebrew/bin/codex这是 npm 为全局命令创建的软链接正常情况下指向../lib/node_modules/openai/codex/bin/codex.js。如果它指向的目标已经不存在或损坏删掉重装时会自动重建。删除之前可以先看看目录里到底有什么ls -la $(npm root -g)/openai 2/dev/null确认没有其他重要包后执行删除rm -rf $(npm root -g)/openai rm -f $(npm prefix -g)/bin/codex提醒rm -rf是危险操作务必确认路径正确再执行。建议先执行npm root -g复制输出的完整路径不要凭记忆手打路径。3.3 第三步清理 npm 缓存排除坏缓存干扰残留目录删干净后接下来要处理 npm 缓存。ENOTEMPTY 有不少情况是缓存中已经存在解压一半的临时文件导致后续验证和重命名环节出错。执行npm cache clean --force这条命令会把~/.npm/_cacache下的缓存内容清空。如果觉得--force太暴力也可以先执行npm cache verify让 npm 自己检查并清理损坏条目。实测下来ENOTEMPTY 场景直接clean --force更干脆省得反复验证浪费时间。清理完缓存后还有一层保险操作删除.staging临时目录。npm 安装中断时会在全局 node_modules 下留下.staging目录这个目录有时候不会被后续安装自动复用反而会干扰重命名操作。rm -rf $(npm root -g)/.staging3.4 第四步重新安装 codex 并验证结果清理完成后重新执行安装命令npm install -g openai/codex这次正常情况下应该能顺利装完。如果网络状态不太稳定可以加--fetch-retries5增加重试次数或者使用国内镜像源来提速npm install -g openai/codex --registry https://registry.npmmirror.com安装完成后验证一下是否真的装好了codex --version which codexcodex --version能输出版本号说明安装成功。which codex则告诉你可执行文件的实际路径正常情况下是在 npm 全局 bin 目录下比如/opt/homebrew/bin/codex。4. 安装成功之后Codex 初始化和运行时问题处理4.1 初始化登录codex login 的前置条件安装只是第一步codex 要真正跑起来还需要登录账号并完成初始化配置。执行codex login这里会打开浏览器引导你完成账号授权。如果你打算用 API Key 方式可以执行codex login --api-key并粘贴 Key。无论哪种方式登录完成后 codex 会把凭证写入~/.codex目录下的配置文件里。登录完成后执行codex init会在当前目录生成codex.md之类的配置文件告诉 codex 这个项目的上下文说明。我建议在项目根目录跑一下codex init把项目背景简单写进去后续 codex 在执行任务时对项目结构的理解会更准确。4.2 那些年 codex 跑不起来的“代理报错”到底是谁的锅codex 安装成功后有些用户会在运行时看到类似cc switch local proxy failed while handling codex endpoint /responses的报错。第一次看到这个信息确实容易被吓到以为 codex 本身出了问题。这里我单独解释一下。codex CLI 在运行时会读取当前终端环境中的本地代理相关变量比如HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些环境变量。如果你的终端里配置了这些变量但实际对应的本地代理进程没有启动或者端口号对不上codex 在切换本地代理连接时就会失败报错文案里就会出现switch local proxy failed。排查思路很简单env | grep -i proxy如果没有输出说明环境变量里没有设置代理这个报错不太可能是环境变量引起的。如果输出了类似HTTP_PROXYhttp://127.0.0.1:7890的内容那就是有代理配置。此时检查 7890 端口是否有对应进程在监听lsof -i :7890如果端口没有程序监听那说明代理进程没起要么启动对应代理工具要么在当前终端临时清掉这些环境变量再运行 codexunset HTTP_PROXY HTTPS_PROXY ALL_PROXY codex提示codex 的报错信息有时比较“虚”switch local proxy failed并不一定代表你的网络有问题更多时候是本地环境变量与代理端口不匹配。先查环境变量再查端口监听基本能定位九成问题。4.3 安装时出现的 node-domexception deprecated 警告需要处理吗安装 codex 的过程中很多人会注意到npm warn deprecated node-domexception1.0.0这类警告。这里明确说一下这是 npm 在提醒某个依赖包已经过时不再推荐使用但它并不是错误也不会导致安装失败。node-domexception 是较早用于在 Node.js 中模拟 DOMException 的小工具包随着 Node.js 自带实现逐渐完善这个包被标记为 deprecated。codex 的依赖链里某个老包可能还在引用它npm 只是顺便提醒一句。这种情况不需要做任何处理忽略即可。如果你有强迫症非要让安装过程完全干净那只能等上游依赖更新替换掉这个包普通用户层面没有可操作空间。5. 常见问题与排查技巧实录5.1 ENOTEMPTY 及其他相关报错速查表把我在 mac 上安装 codex 前后遇到过的各种报错整理成一张表方便后续遇到问题时直接对照报错信息可能原因解决办法npm error code ENOTEMPTY目标目录非空重命名失败手动删除openai残留目录清理.staging重装npm error code EACCES全局目录权限不足用 nvm 管理 Node或sudo chown -R $(whoami) $(npm root -g)npm error code CERT_HAS_EXPIRED老淘宝源证书过期切换 registry 到https://registry.npmmirror.comcodex: command not foundnpm 全局 bin 目录不在 PATH检查npm prefix -g把对应 bin 目录加入 PATHcc switch local proxy failed ...本地代理环境变量端口不匹配检查HTTP_PROXY、HTTPS_PROXY、ALL_PROXY确认代理进程已启动npm WARN deprecated node-domexception依赖包过时提醒忽略不影响安装和使用5.2 mac 上避免再踩 ENOTEMPTY 的 3 个习惯第一次解决 ENOTEMPTY 之后很长一段时间我都没再遇到过同类问题核心原因是养成了几个安装全局包的习惯。这里分享一下。第一个习惯尽量不用 sudo 安装全局包。mac 上很多权限类 npm 报错都是从一次sudo npm install开始的。sudo 装完的目录归 root 所有后续普通用户安装升级都会受限。推荐的做法是用 nvm 安装 Node.js全局包默认装在用户目录比如~/.nvm/versions/node/v22.x.x/lib/node_modules这样不会有权限冲突。第二个习惯安装过程中不随意中断。npm install 虽然看起来进度条走得很快但内部在解压、重命名时如果被 CtrlC 打断很容易留下一堆半成品目录。如果网速慢导致安装没反应宁可多等一会也别频繁中断重试。第三个习惯定期清理发霉的缓存。npm cache clean --force不是每天都要跑但在你发现某个包装不上去、报错又比较奇怪时先清一次缓存再重装能省掉很多排查时间。5.3 安装完成后 codex 使用中的几个小技巧codex 装好之后有几个小细节可以让使用过程顺畅很多。一是终端里配置好 PATH。如果你用的是 nvm那么 Node 的 bin 目录默认已经在 PATH 里。如果你用其他方式安装的 Node并且codex命令提示找不到执行echo $PATH看看是否包含npm prefix -g里输出的 bin 路径。如果不包含在~/.zshrc或~/.bash_profile里加上export PATH$(npm prefix -g)/bin:$PATH然后source ~/.zshrc让配置生效。二是如果 codex 启动后响应异常先看~/.codex目录下的日志。codex 会把运行日志写在~/.codex/log或类似位置具体路径可以执行codex --debug启动一次它会打印更详细的日志路径。排查实际问题时日志里的信息永远比终端报错有用。三是如果你不想每次都在项目目录重新配置上下文可以在~/.codex下维护一个全局配置把常用的工作习惯写进去这样 codex 每次运行时都能读到你的偏好设置减少重复沟通成本。写在最后ENOTEMPTY 这类报错mac 上之所以反复出现本质上就是「目录残留 权限混乱 npm 重命名机制」三件事凑在一起。遇到它别慌也不要一上来就重装 Node.js先定位残留目录再检查权限最后清一遍缓存重装九成情况都能解决。我个人在实际操作中的体会是mac 上跑 npm 全局安装尽量用 nvm 管理环境从源头避开权限问题能省掉后面一大堆奇奇怪怪的坑。codex 本身是个很好用的命令行编程工具装好之后的体验完全值得你在安装上多花几分钟。
mac上npm安装Codex CLI报ENOTEMPTY错误：原因与解决指南
mac 上跑npm install -g openai/codex装 Codex CLI 的时候不少朋友应该都撞过这个场景命令刚执行没几秒终端就蹦出一串红色报错里面最扎眼的那个是npm error code ENOTEMPTY。我头一回看到这个错误码也愣了一下ENOTEMPTY 平时真不常见网上一搜信息还特别零散有人说清缓存有人让删目录还有人干脆建议重装 Node.js——这显然不是最优解。这篇就围绕「mac npm codex ENOTEMPTY」这条报错链路把问题背后的安装机制拆开讲清楚再给一套从环境自检到彻底重装的完整操作流程。顺带把安装成功后 codex 运行时可能碰到的代理报错、deprecated 提示这类后遗症一起解决掉。适合初次在 mac 上安装 codex 的新手也适合想彻底搞懂 npm 这类诡异报错的开发者。1. 先把 ENOTEMPTY 的来龙去脉搞清楚1.1 报错信息拆解npm 到底在哪个环节翻了车很多人看到npm error code ENOTEMPTY的第一反应是“没看懂继续搜”但拆开看其实并不复杂。ENOTEMPTY 是系统层面的错误码英文全称是Directory not empty翻译过来就是“目录非空”。macOS 文件系统在执行某些操作时如果发现目标目录里面还有文件或子目录并且操作要求目标目录必须为空就会返回这个错误。npm 的安装过程并不是很多人以为的“把包解压到 node_modules 就完事”。npm 在安装一个全局包时大致会分这么几步把包下载到 npm 自己的缓存目录~/.npm/_cacache在目标 node_modules 下创建临时目录常见的是一级.staging目录把解压好的文件从缓存中写入.staging临时目录最后把临时目录重命名成正式的包目录比如node_modules/openai/codex。问题就出在第 4 步。这个“重命名”操作要求目标位置不能存在同名目录或者如果存在同名目录这个目录得是空的。当系统发现node_modules/openai/codex已经存在并且里面还有一堆残留文件时就会直接丢出 ENOTEMPTY。我实际遇到过的情况是之前一次安装因为网络抖动被中断npm 已经把 codex 的部分文件写进了openai/codex目录但后续步骤没有完成。第二次重装时npm 想重新创建这个目录结果发现它非空于是直接罢工。1.2 为什么 macOS 上这个错误尤其容易复现ENOTEMPTY 并不是 mac 专属Linux 上也会出现但 macOS 上有几个特有的“坑”会显著提高触发概率这里值得单独说一下。第一macOS 默认的 APFS 文件系统对大小写不敏感。这意味着OpenAI和openai在绝大多数情况下会被当成同一个目录。npm 在安装openai/codex时会同时操作node_modules/openai这个作用域目录如果之前曾经用某个包创建过同名但大小写不同的目录文件系统层面就可能产生冲突。第二macOS 的 Spotlight 索引、第三方安全软件实时扫描会在文件重命名瞬间短暂占用目录句柄。虽然这个概率不高但在包体积较大、目录层级较深时更容易触发。Codex 这个 CLI 工具本身依赖不少原生模块文件数量多重命名耗时相对长恰好就比普通包更容易踩中这个窗口期。第三也是最常见的原因全局 node_modules 目录的权限混乱。很多 mac 用户安装 Node.js 时用的是 Homebrew而 Homebrew 安装 Node 的目录要么是/usr/local要么是/opt/homebrew。如果你之前使用过sudo npm install安装过全局包那么某些目录的 owner 就变成了 root。后续再用普通用户身份执行 npm 安装时npm 无法删除或覆盖这些 root 属主的目录也会在“目录非空”这一步直接报错。1.3 从日志里找真正原因不要盲猜ENOTEMPTY 报错信息本身比较简短但 npm 通常会附上更详细的上下文。执行安装命令时如果报错不要急着关终端把完整输出多看几行重点找这几类线索npm error path ...报错的具体路径能直接告诉你到底是哪个目录出了问题npm error syscall rename说明卡在重命名阶段npm error errno -66-66 是 ENOTEMPTY 在 macOS 上的数字编号npm error dest ...重命名的目标目录。如果输出信息不够多还可以用npm install -g openai/codex --loglevel verbose重新跑一遍npm 会打印每一步操作的详细日志能看到它具体在哪一步、操作哪个路径时失败。注意macOS 上看到syscall rename和errno -66这两个信息基本可以锁定是 ENOTEMPTY不用再怀疑其他原因。2. 动手修复前先做一轮环境自检2.1 确认 Node.js 和 npm 的版本与全局目录我见过不少人装 codex 报错排查了半天最后发现是自己 Node.js 版本太老npm 的行为和现代版本不一样导致一系列诡异问题。所以第一步不是清理缓存而是先确认环境。在终端依次执行node -v npm -v npm config get prefix npm root -gnpm config get prefix会输出 npm 安装全局包的根目录比如/usr/local或/opt/homebrew。npm root -g则直接给出全局 node_modules 的完整路径比如/opt/homebrew/lib/node_modules。记住这个路径后面清理残留目录时会用到。如果你是用 Homebrew 安装的 Node.js并且电脑是 Apple Silicon 芯片全局目录通常在/opt/homebrew/lib/node_modules如果是 Intel 芯片则一般在/usr/local/lib/node_modules。如果你用的是官方 pkg 安装包路径可能是/usr/local/lib/node_modules。这里没有标准答案一切以你本机npm root -g的输出为准。2.2 检查全局目录权限是不是被 sudo 污染过这一步非常关键mac 上 ENOTEMPTY 有很多次都是权限问题伪装成目录冲突。执行ls -ld $(npm root -g) ls -ld $(npm root -g)/openai 2/dev/null || echo 目录不存在如果看到目录 owner 是 root而你当前登录用户不是 root那么你普通用户执行 npm install 时对目录里面的文件没有写权限。npm 尝试清理旧文件时就会失败表现出来可能就是 ENOTEMPTY有时候也会变成 EACCES。最稳妥的解决思路是不要用sudo npm install -g而是用 nvm 这类 Node 版本管理器把 Node 安装到用户目录下全局包也自然落在用户目录从根上避开权限问题。# 如果还没有 nvm可以按 nvm 官方 README 安装 # 安装完成后node、npm 和全局 node_modules 都会在用户目录下 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash如果你不想切换 Node 版本管理器也可以简单地把全局目录授权给自己但这需要你明确知道当前目录的确切路径sudo chown -R $(whoami) $(npm root -g)这条命令的意思是把全局 node_modules 目录的所有权从 root 改成当前用户。执行之后npm 不需要 sudo 也能正常创建和删除目录。2.3 检查 npm 镜像源配置避免“源不对”带来的干扰在 mac 上安装 codex 时npm 默认从官方源下载但国内用户为了提速通常会配置镜像源。npm 镜像源配置本身没有问题但如果配置了老的淘宝源https://registry.npm.taobao.org在某些情况下会碰到证书过期错误CERT_HAS_EXPIRED表现和 ENOTEMPTY 不同但同样会中断安装。查看当前源npm config get registry如果输出的是https://registry.npmjs.org/那说明是官方源。如果输出的是老淘宝源建议切换到新的 npmmirror 源npm config set registry https://registry.npmmirror.com或者直接编辑~/.npmrc文件把 registry 那一行改成新地址。改完后重新检查一遍确认生效即可。提示npm 的 registry 配置是全局生效的改完后所有 npm install 都会走新源。如果之前做过某些包的私有源配置改动前先看一眼~/.npmrc里的完整内容。3. 解决 ENOTEMPTY 的完整实操从清理到重装3.1 第一步安全卸载可能存在的 codex 残留在清理之前先尝试用 npm 正常卸载一遍 codex。虽然 ENOTEMPTY 报错说明卸载可能也会遇到问题但值得先试一次因为如果卸载能成功后面会省很多事npm uninstall -g openai/codex如果卸载成功终端没有任何报错那么直接跳到 3.4 重新安装。如果卸载过程还是报 ENOTEMPTY或者提示目录不存在那么进入下面的手动清理流程。3.2 第二步确认并手动删除残留目录卸载失败时最直接的办法就是手动删除残留的 codex 目录。先定位目录位置npm root -g假设输出的全局 node_modules 路径是/opt/homebrew/lib/node_modules那么需要重点检查这几个位置/opt/homebrew/lib/node_modules/openai这是 codex 包的主目录如果存在且里面有残留文件直接删掉整个openai作用域目录。/opt/homebrew/lib/node_modules/codex有些情况下 npm 会生成不带 scope 的目录存在也一并删掉。/opt/homebrew/bin/codex这是 npm 为全局命令创建的软链接正常情况下指向../lib/node_modules/openai/codex/bin/codex.js。如果它指向的目标已经不存在或损坏删掉重装时会自动重建。删除之前可以先看看目录里到底有什么ls -la $(npm root -g)/openai 2/dev/null确认没有其他重要包后执行删除rm -rf $(npm root -g)/openai rm -f $(npm prefix -g)/bin/codex提醒rm -rf是危险操作务必确认路径正确再执行。建议先执行npm root -g复制输出的完整路径不要凭记忆手打路径。3.3 第三步清理 npm 缓存排除坏缓存干扰残留目录删干净后接下来要处理 npm 缓存。ENOTEMPTY 有不少情况是缓存中已经存在解压一半的临时文件导致后续验证和重命名环节出错。执行npm cache clean --force这条命令会把~/.npm/_cacache下的缓存内容清空。如果觉得--force太暴力也可以先执行npm cache verify让 npm 自己检查并清理损坏条目。实测下来ENOTEMPTY 场景直接clean --force更干脆省得反复验证浪费时间。清理完缓存后还有一层保险操作删除.staging临时目录。npm 安装中断时会在全局 node_modules 下留下.staging目录这个目录有时候不会被后续安装自动复用反而会干扰重命名操作。rm -rf $(npm root -g)/.staging3.4 第四步重新安装 codex 并验证结果清理完成后重新执行安装命令npm install -g openai/codex这次正常情况下应该能顺利装完。如果网络状态不太稳定可以加--fetch-retries5增加重试次数或者使用国内镜像源来提速npm install -g openai/codex --registry https://registry.npmmirror.com安装完成后验证一下是否真的装好了codex --version which codexcodex --version能输出版本号说明安装成功。which codex则告诉你可执行文件的实际路径正常情况下是在 npm 全局 bin 目录下比如/opt/homebrew/bin/codex。4. 安装成功之后Codex 初始化和运行时问题处理4.1 初始化登录codex login 的前置条件安装只是第一步codex 要真正跑起来还需要登录账号并完成初始化配置。执行codex login这里会打开浏览器引导你完成账号授权。如果你打算用 API Key 方式可以执行codex login --api-key并粘贴 Key。无论哪种方式登录完成后 codex 会把凭证写入~/.codex目录下的配置文件里。登录完成后执行codex init会在当前目录生成codex.md之类的配置文件告诉 codex 这个项目的上下文说明。我建议在项目根目录跑一下codex init把项目背景简单写进去后续 codex 在执行任务时对项目结构的理解会更准确。4.2 那些年 codex 跑不起来的“代理报错”到底是谁的锅codex 安装成功后有些用户会在运行时看到类似cc switch local proxy failed while handling codex endpoint /responses的报错。第一次看到这个信息确实容易被吓到以为 codex 本身出了问题。这里我单独解释一下。codex CLI 在运行时会读取当前终端环境中的本地代理相关变量比如HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些环境变量。如果你的终端里配置了这些变量但实际对应的本地代理进程没有启动或者端口号对不上codex 在切换本地代理连接时就会失败报错文案里就会出现switch local proxy failed。排查思路很简单env | grep -i proxy如果没有输出说明环境变量里没有设置代理这个报错不太可能是环境变量引起的。如果输出了类似HTTP_PROXYhttp://127.0.0.1:7890的内容那就是有代理配置。此时检查 7890 端口是否有对应进程在监听lsof -i :7890如果端口没有程序监听那说明代理进程没起要么启动对应代理工具要么在当前终端临时清掉这些环境变量再运行 codexunset HTTP_PROXY HTTPS_PROXY ALL_PROXY codex提示codex 的报错信息有时比较“虚”switch local proxy failed并不一定代表你的网络有问题更多时候是本地环境变量与代理端口不匹配。先查环境变量再查端口监听基本能定位九成问题。4.3 安装时出现的 node-domexception deprecated 警告需要处理吗安装 codex 的过程中很多人会注意到npm warn deprecated node-domexception1.0.0这类警告。这里明确说一下这是 npm 在提醒某个依赖包已经过时不再推荐使用但它并不是错误也不会导致安装失败。node-domexception 是较早用于在 Node.js 中模拟 DOMException 的小工具包随着 Node.js 自带实现逐渐完善这个包被标记为 deprecated。codex 的依赖链里某个老包可能还在引用它npm 只是顺便提醒一句。这种情况不需要做任何处理忽略即可。如果你有强迫症非要让安装过程完全干净那只能等上游依赖更新替换掉这个包普通用户层面没有可操作空间。5. 常见问题与排查技巧实录5.1 ENOTEMPTY 及其他相关报错速查表把我在 mac 上安装 codex 前后遇到过的各种报错整理成一张表方便后续遇到问题时直接对照报错信息可能原因解决办法npm error code ENOTEMPTY目标目录非空重命名失败手动删除openai残留目录清理.staging重装npm error code EACCES全局目录权限不足用 nvm 管理 Node或sudo chown -R $(whoami) $(npm root -g)npm error code CERT_HAS_EXPIRED老淘宝源证书过期切换 registry 到https://registry.npmmirror.comcodex: command not foundnpm 全局 bin 目录不在 PATH检查npm prefix -g把对应 bin 目录加入 PATHcc switch local proxy failed ...本地代理环境变量端口不匹配检查HTTP_PROXY、HTTPS_PROXY、ALL_PROXY确认代理进程已启动npm WARN deprecated node-domexception依赖包过时提醒忽略不影响安装和使用5.2 mac 上避免再踩 ENOTEMPTY 的 3 个习惯第一次解决 ENOTEMPTY 之后很长一段时间我都没再遇到过同类问题核心原因是养成了几个安装全局包的习惯。这里分享一下。第一个习惯尽量不用 sudo 安装全局包。mac 上很多权限类 npm 报错都是从一次sudo npm install开始的。sudo 装完的目录归 root 所有后续普通用户安装升级都会受限。推荐的做法是用 nvm 安装 Node.js全局包默认装在用户目录比如~/.nvm/versions/node/v22.x.x/lib/node_modules这样不会有权限冲突。第二个习惯安装过程中不随意中断。npm install 虽然看起来进度条走得很快但内部在解压、重命名时如果被 CtrlC 打断很容易留下一堆半成品目录。如果网速慢导致安装没反应宁可多等一会也别频繁中断重试。第三个习惯定期清理发霉的缓存。npm cache clean --force不是每天都要跑但在你发现某个包装不上去、报错又比较奇怪时先清一次缓存再重装能省掉很多排查时间。5.3 安装完成后 codex 使用中的几个小技巧codex 装好之后有几个小细节可以让使用过程顺畅很多。一是终端里配置好 PATH。如果你用的是 nvm那么 Node 的 bin 目录默认已经在 PATH 里。如果你用其他方式安装的 Node并且codex命令提示找不到执行echo $PATH看看是否包含npm prefix -g里输出的 bin 路径。如果不包含在~/.zshrc或~/.bash_profile里加上export PATH$(npm prefix -g)/bin:$PATH然后source ~/.zshrc让配置生效。二是如果 codex 启动后响应异常先看~/.codex目录下的日志。codex 会把运行日志写在~/.codex/log或类似位置具体路径可以执行codex --debug启动一次它会打印更详细的日志路径。排查实际问题时日志里的信息永远比终端报错有用。三是如果你不想每次都在项目目录重新配置上下文可以在~/.codex下维护一个全局配置把常用的工作习惯写进去这样 codex 每次运行时都能读到你的偏好设置减少重复沟通成本。写在最后ENOTEMPTY 这类报错mac 上之所以反复出现本质上就是「目录残留 权限混乱 npm 重命名机制」三件事凑在一起。遇到它别慌也不要一上来就重装 Node.js先定位残留目录再检查权限最后清一遍缓存重装九成情况都能解决。我个人在实际操作中的体会是mac 上跑 npm 全局安装尽量用 nvm 管理环境从源头避开权限问题能省掉后面一大堆奇奇怪怪的坑。codex 本身是个很好用的命令行编程工具装好之后的体验完全值得你在安装上多花几分钟。
