"codex: command not found":npm install -g 装完 7 个修复套路(2026)
现在就遇到 “codex: command not found”?30 秒诊断
按顺序跑这三条命令。哪一条结果不对,就去对应的 Fix。
node --version # 期望 v16.x 或更高(推荐 LTS)
which codex # 期望真实路径,例如 /Users/you/.npm-global/bin/codex
npm prefix -g # 期望返回的 prefix 下的 /bin 应该包含 codex
| 结果 | 含义 | 跳到 |
|---|---|---|
node 找不到 | Node.js 根本没装,或者 NVM 没加载 | Fix 2(NVM)或 Fix 6(Node 版本) |
node 低于 v16 | Codex CLI 0.137.0 装不上——engines.node: ">=16" | Fix 6 |
which codex 空 | 二进制在但不在 PATH 上 | Fix 1(PATH) |
npm prefix -g 返回的路径你写不进去 | npm 在往 sudo 拥有的目录写 | Fix 5(sudo / EACCES) |
三条都对,但 codex 还是跑不起来 | 你在 Codex Desktop、Volta,或非交互 shell 里 | Fix 4(Volta)、Fix 7(Codex Desktop) |
最常见的就是 Fix 1——PATH 里没有 npm 全局 bin 目录。其余 6 个 fix 处理长尾。每一个都在 Codex CLI 0.137.0(2026-06-04 发布)上验过,环境包括 macOS 14、Ubuntu 24.04、Windows 11 + WSL2。
安装本身的事——npm、Homebrew、二进制版怎么选,或者怎么把 Codex 指向 OpenAI 兼容的网关——看 Codex CLI 怎么用?5 分钟从安装到跑通。本文假设你安装步骤跑过没报错,卡在了后面的 command not found 这一步。
为什么会撞这个错:Codex CLI 的安装路径表面
Codex CLI 本质是个 Rust 二进制,外面包了一层 npm 包。安装时这层 wrapper 做三件事:
- 把平台对应的二进制下载到
node_modules/@openai/codex/ - 在
<npm-prefix>/bin/codex建一个细 shim,exec 到那个二进制 - 校验
engines.node >= 16,不满足就拒绝安装(npm 包的engines字段公开声明)
这三步可以全部成功,但 codex 在 shell 里还是解析不到:
- 第 2 步成功但 PATH 不对 → 即使 shim 在硬盘上,shell 也说 command not found
- NVM 这类版本管理器把
<npm-prefix>按 Node 版本隔离 → codex shim 只在你装那次的 Node 版本下存在 - Codex Desktop 集成的 shell 是非交互的 → 它不 source
~/.zshrc,所以 NVM 不加载,所以 prefix 不对,所以 PATH 不对(issue #13566、#14016) sudo npm install -g写出 root owner 的文件 → 之后不带 sudo 的安装直接 EACCES,部分写入还会留下半成品的旧 shim 指向失效路径
下面 7 个 fix 把这些路径一一处理掉。
Fix 1:PATH 里缺 npm 全局 bin 目录
最常见的一种。两条命令诊断:
npm prefix -g
echo $PATH | tr ':' '\n' | grep "$(npm prefix -g)/bin" || echo "NOT ON PATH"
如果第二条打印 NOT ON PATH,就是这个 bug。shim 在 <prefix>/bin/codex 上躺着,但你的 shell 不往那看。
先把 prefix 抓出来——不要 把 $(npm prefix -g) 直接写进 PATH export。那段子 shell 每次开终端都跑一遍,启动延迟会多 60~200 ms,没意义。现在抓一次成字面字符串,再把那个字面值写进 rc 文件。
PREFIX=$(npm prefix -g)
echo "$PREFIX" # 把这条字面路径复制下来,下面要粘贴
zsh 写法(macOS 自 Catalina 起默认 shell)
# 把 /Users/you/.npm-global 换成你刚才打出来的字面路径
echo 'export PATH="/Users/you/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
which codex # 应该能打出真实路径了
codex --version # 确认
bash 写法(大部分 Linux 发行版)
echo 'export PATH="/home/you/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
which codex
fish 写法
fish_add_path /Users/you/.npm-global/bin
which codex
为什么 npm bin -g 不再能用
如果你抄的是 2023 年那批 Stack Overflow 答案,大概率让你跑 export PATH=$PATH:$(npm bin -g)。这条命令在 npm 9 已经被删了,跑出来啥也没有。npm prefix -g 返回的是上层目录,你自己手动拼 /bin。
修完应该看到
$ which codex
/Users/you/.npm-global/bin/codex
$ codex --version
codex-cli 0.137.0
如果 which codex 能解析,但跑 codex 还是 command not found,那你这是个老 shell 会话——开个新终端就好。PATH 变更不会传播到已开的 shell。
Fix 2:NVM 把 Codex 装到了错的 Node 版本下
NVM 是按 Node 版本隔离 npm 全局 prefix 的。在 Node 20 下装了 @openai/codex,切到 Node 18 去搞别的项目,codex 就没了。
确认是不是这个隔离问题:
nvm current # 现在用哪个 Node?
ls "$(npm prefix -g)/bin/codex" # 当前 Node 下存在吗?
nvm use 22 && which codex # 这里能跑吗?
nvm use 20 && which codex # 这里跑不动?
最后两行如果证明确实是版本隔离,就永久修一下:
# 钉一个默认 Node 版本(推荐 LTS)
nvm alias default 20
# 在那个版本下重装 Codex
nvm use default
npm install -g @openai/codex
如果你必须频繁切 Node 版本,就在 ~/.zshrc 顶上加 nvm use default,每个新 shell 都从默认 Node 开始:
# 在 ~/.zshrc 顶上,source 完 nvm.sh 之后
nvm use default --silent
一个更阴的坑:nvm install-latest-npm
装完 Codex 之后再跑 nvm install-latest-npm 会把 shim 搞坏——新版 npm 会重写全局 prefix,把现有 shim 孤立掉。每次 npm 升级后都重装一遍 Codex。
Fix 3:把 npm prefix 设到自己家目录,避开 EACCES 和 PATH 漂移
macOS 和 Linux 上最干净的姿势是把 npm 指到自己拥有的目录。这一招同时解决 sudo、PATH 权限报警、Node 版本一切就稳的 prefix(不用 NVM 的前提下)。
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# 重装(这次不带 sudo,装到新 prefix)
npm install -g @openai/codex
which codex # /Users/you/.npm-global/bin/codex
为什么比 sudo npm install -g 好
sudo 把东西写到 /usr/local/lib/node_modules,owner 是 root。后续两种失败模式:
- 之后不带 sudo 的
npm install -g直接报EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai' - 更新 Codex 会产生部分 root-owned 文件混在你自己的文件里,最后 codex 指向一个写到一半的二进制
用户 prefix 这条路把两个坑都绕了。npm 官方文档自 2019 起就推这个 pattern。
从 sudo 装的状态迁回来
如果你以前用 sudo 装过全局包,先清干净再切:
sudo npm uninstall -g @openai/codex # 卸掉 root-owned 的那个
npm config set prefix ~/.npm-global # 重新指 prefix
npm install -g @openai/codex # 不带 sudo 重装
Fix 4:Volta 或 asdf 劫持了 codex shim
Volta 和 asdf 是另一种 Node 版本管理器,它们会拦截 codex 命令,走自己的 shim 层。当 shim 层没对齐——比如 Volta 没给当前项目钉 Node 版本——即使 node_modules 里有二进制,codex 也会 command not found。
Volta
volta which node # Volta 在这里挑哪个 Node?
volta install node@20 # 全局钉 Node 20 LTS
volta install @openai/codex # 让 Volta 管这个 shim
which codex # 应该在 ~/.volta/bin 下解析到
Volta 激活时,加全局工具的官方姿势是 volta install <package>,不是 npm install -g。如果你两边混用,行为会很不一致;一台机器只走一条路。
asdf
asdf 装完新全局 npm 包后必须 asdf reshim nodejs。漏了 reshim,即使安装成功,codex 也不在 PATH 上:
asdf install nodejs 22.12.0
asdf global nodejs 22.12.0
npm install -g @openai/codex
asdf reshim nodejs # 大部分人忘的就是这一步
which codex
Fix 5:macOS EACCES——不用 sudo 修 npm 权限
如果你的安装报错里有这几行任意一段:
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai'
npm ERR! errno EACCES
operation rejected by your operating system
……你就是踩了 sudo 那个坑。正确修法不是再带 sudo 重试。正确修法是切到 Fix 3 那条用户 prefix 路线;或者——如果你非要保住 /usr/local 作为全局 prefix——把所有权拿回来:
sudo chown -R $(whoami) $(npm prefix -g)/lib/node_modules
sudo chown -R $(whoami) $(npm prefix -g)/bin
sudo chown -R $(whoami) $(npm prefix -g)/share
这一次性 chown 之后,当前用户跑 npm install -g 就不再需要 sudo 了。重试安装:
npm install -g @openai/codex
which codex
macOS Gatekeeper 拦了二进制
macOS 14+ 上还有一个独立故障模式:Gatekeeper 拦住未签名的 Codex 二进制第一次启动,你看到的是 “cannot be opened because it is from an unidentified developer” 而不是 command not found。去 系统设置 → 隐私与安全性 → “仍要打开”,之后 codex --version 就能跑了。
Fix 6:Node.js 版本低于 engines floor
Codex CLI 0.137.0 公开的 engines.node 是 ">=16"(在 npm 上确认过)。这是正式 floor——Node 14 及以下安装时就被拒。Node 16 本身已于 2023 年 9 月上游 EOL,实操推荐直接 Node 20 LTS 或更新;Node 22 LTS 也行,不强制。
$ node --version
v14.21.3
$ npm install -g @openai/codex
npm warn EBADENGINE Unsupported engine {
package: '@openai/[email protected]',
required: { node: '>=16' },
current: { node: 'v14.21.3', npm: '6.14.18' }
}
# 加 --force 会"成功",但 shim 不一定能干净启动
正确升级 Node
具体走哪条路看 Node 当初怎么装的。下面建议都以 Node 20 LTS 为基准,要 node@22 或任何 >=16 的 LTS 线都可以替。
- macOS(Homebrew): link 之前先显式装目标版本——
brew link node@20在 keg 没装过的情况下会报No such keg。brew install node@20 && brew link --overwrite --force node@20。 - macOS(官方安装器): 从
nodejs.org下 Node 20 LTS(或 22 LTS),跑.pkg,重启终端。 - Linux(NodeSource):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - && sudo apt install -y nodejs - NVM(任何系统):
nvm install 20 && nvm alias default 20 && nvm use default - Windows: 从
nodejs.org下官方.msi重装
升完 Node 之后,要在新 Node 版本下重装 Codex CLI——shim 是按版本走的,老的已经死了:
npm install -g @openai/codex
codex --version
Fix 7:Codex Desktop 非交互 shell bug(issue #13566、#14016)
这条坑的是命令行里 Codex CLI 没事,但在 Codex Desktop 应用或 VS Code Codex 扩展里跑就挂的人。集成 shell 里报的错就是:
zsh: command not found: node
zsh: command not found: codex
……同样的命令在普通终端窗口里没事。
根因
Codex Desktop 是通过非 login、非交互 shell 启子进程的。这种 shell 不会 source ~/.zshrc 或 ~/.bashrc。NVM、fnm、Volta 全都依赖那些文件里的初始化代码,所以 PATH 根本没被填。
两个 issue 截至 2026-06-04 都还 open:
- openai/codex#13566:WSL 里的 NVM → “zsh: command not found: node”
- openai/codex#14016:Windows 上 fnm → “npm isn’t available in this shell path”
绕路 A:用官方安装器装 Node,别用版本管理器(推荐)
跑 Codex Desktop 的那台机器上,最干净的修法是绕开版本管理器。从 nodejs.org 装 Node 20 LTS(或 22 LTS),它会写到 /usr/local/bin(macOS/Linux)或 C:\Program Files\nodejs(Windows)。这些路径在每种 shell 下都在系统 PATH 上——不管是 login 还是非 login、交互还是非交互。用官方 Node 重装 Codex,Codex Desktop 立刻就找到。
OpenAI 维护者目前给 #13566 和 #14016 的解决方向就是这个。
绕路 B:留着 NVM,但按 NVM 的设计方式配
NVM 项目的 README 明确列了四个被支持的初始化文件:~/.zshrc、~/.bashrc、~/.bash_profile、~/.profile。不要把 NVM 加载脚本搬到 ~/.zshenv——虽然这样确实能”修好” Codex Desktop,但 ~/.zshenv 每个 Zsh 进程都会 source,包括 cron 任务、git 钩子、别的应用启的脚本、Spotlight 索引器。所有这些场景里加载 NVM 会让每次调用慢 60~200 ms,还可能在某个脚本期望系统 Node、结果拿到 NVM shim 的 Node 时出莫名其妙的故障。
如果你必须留在 NVM 上,更安全的姿势是让 Codex Desktop 本身从 login shell 启动——比如做一个 launcher 跑 zsh -l -c "open -a 'Codex'",而不是直接点应用图标。login shell 会 source ~/.zprofile(可以串到 ~/.zshrc 加载 NVM),子进程继承填好的 PATH。
绕路 C:WSL 原生 shell
Windows + WSL 这边,把 Codex Desktop 的终端偏好设置成直接启 wsl.exe -d Ubuntu,而不是 Windows 上那个 Codex shell。WSL 的 bash 会从自己的 ~/.bashrc 继承 PATH,那里 NVM 是会加载的。
我们观察到的常见故障模式(近期 Codex issue)
近 60 天 openai/codex 仓库里反复出现的 command not found 类报告快照:
| Issue | 症状 | 根因 | 修复 |
|---|---|---|---|
| #13566 | Codex Desktop 里 zsh: command not found: node,命令行里没事 | 非交互 shell 不 source .zshrc → NVM 不加载 | Fix 7 绕路 A(官方 Node 安装器) |
| #14016 | Windows + fnm npm isn't available in this shell path | fnm shim 不在系统 PATH 上 | Fix 7 绕路 A(官方 Node 安装器) |
| #10342 | npm install -g @openai/codex → “operation rejected by your operating system” | macOS 上 sudo 权限冲突 | Fix 5(用户 prefix) |
| #1480(已关) | 全局安装 EACCESS permission issue | npm 全局 prefix owner 是 root | Fix 3 + Fix 5 |
| #9356(已关) | codex 自己提示 npm install -g codex(包名错) | 老文档缓存;正确名是 @openai/codex | 核对包名;用 scoped 名重装 |
| #18485 | 全新系统上全局安装失败 | Node < 16(engines floor),或者根本没装 Node | Fix 6 |
| #20206 | Windows 上 failed to start codex app-server (os error 3) | Desktop 应用解析不到 WindowsApps 路径下的 CLI 二进制 | 走官方安装器重装;删掉 Microsoft Store 版本 |
如果你的症状对得上,直接跳到上面对应的 fix。
7 个 fix 都试过还是不行:能立刻继续干活的替代路径
如果你把 7 个 fix 都走过一遍 codex 还是解析不到,有三个能撤的逃生口。
跑 GitHub Releases 上的二进制(不需要 Node)
Codex 仓库在 github.com/openai/codex/releases 发平台二进制。下载、解压、扔到一个已经在 PATH 上的目录:
# macOS arm64 示例
curl -L -o codex.tar.gz https://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz
tar -xzf codex.tar.gz
sudo mv codex /usr/local/bin/codex
chmod +x /usr/local/bin/codex
codex --version
这条路完全绕开 npm。如果 command not found 卡着一场客户演示,这就是 5 分钟的逃生口。
用 npx 顶着,回头再修 PATH
npx -y @openai/codex --version
npx -y @openai/codex
npx 直接从 node_modules 解析包,根本不依赖 PATH。它会慢(每次调用都重新检查包),但能确认安装本身是好的,把问题隔离到 PATH 上。
通过 OpenAI 兼容网关接 Codex,方便随时换客户端
如果你正好在拿 Codex 跟其他终端编程 Agent 横评,把所有客户端都指向同一个 OpenAI 兼容端点最方便对比。OfoxAI 暴露一个 https://api.ofox.ai/v1 base URL,Codex CLI、Cursor、Cline、OpenClaw 都吃;如果你这台机器上 Codex 装总是失败,可以用同一把 key 拿 Claude Code 或 OpenClaw 跑同一批模型,先把活干了再回来排 PATH。
⚠️ Codex 0.137.0 只接受
wire_api = "responses"。 老的wire_api = "chat"值已经被砍,现在传进去会在配置加载时就触发CHAT_WIRE_API_REMOVED_ERROR,连一个请求都发不出去。这让网关的选择变得很重要:只实现/v1/chat/completions的网关跟当前 Codex 不兼容,配置写得再漂亮都没用。挑网关前先看它公开文档里有没有明确支持 Responses API——OfoxAI 文档里写了 OpenAI Responses 协议——再用真 key 验一次再上生产。
# ~/.codex/config.toml —— Codex 终于能跑起来之后
# 说明:下面 ("ofoxai-codex") 是你给*这个 Codex 安装*起的本地标签,
# 不是 OfoxAI 的产品名。随便起,只要 `model_provider` 跟
# `[model_providers.<标签>]` 的标题对上就行。
model_provider = "ofoxai-codex"
[model_providers.ofoxai-codex]
name = "Ofox AI"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"
wire_api = "responses" # Codex 0.137.0 唯一接受的值
二进制上 PATH 之后的完整配置看 Codex CLI 切换模型 / 接入第三方 API 完全指南。
Windows 原生(非 WSL):几个特殊情况
Codex CLI 在原生 Windows 上能跑,但安装表面比 macOS/Linux 乱。Windows 上的 command not found 报告大部分是下面三种。
%APPDATA%\npm 不在 User PATH
Windows 上 npm install -g 会把 shim 写到 %APPDATA%\npm\codex.cmd(.cmd shim 加一个同级 shell 脚本)。PowerShell 和 cmd.exe 只有 %APPDATA%\npm 在 User PATH 环境变量上才找得到它,光当前会话的 PATH 没用。
# 看 User PATH 上有没有 npm 全局路径
[Environment]::GetEnvironmentVariable("Path", "User") -split ';' | Where-Object { $_ -like '*\npm*' }
# 没有就加进去:
$current = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$current;$env:APPDATA\npm", "User")
加完关掉所有终端——PATH 变更只对新进程生效。
Microsoft Store Node.js vs 官方安装器
如果你 Node 是从 Microsoft Store 装的,npm 全局 prefix 会落在 %LOCALAPPDATA%\Packages\<store-id>\ 下,不是 %APPDATA%\npm。这个 packaged 路径对大部分进程只读,默认也不在 PATH 上。症状:npm install -g @openai/codex 说成功了,where.exe codex 却啥也没返回。
修法:卸掉 Store 版,从 nodejs.org 装官方 .msi,再重装 Codex。Store 版的 Node 还会破坏 Codex Desktop 的 app-server 解析(issue #20206)。
WSL Node 和 Windows Node 混用
同时在 WSL 跑 node 又在 Windows 跑 node.exe,会出现 PATH 冲突,某个 shell 找到的是错的 Codex。一个项目只走一边。项目在 /home/<你>/projects/(WSL 文件系统)下,就在 WSL 里装 Codex。项目在 C:\Users\<你>\projects\,就在 Windows 上装。跨文件系统调用是慢路径,还会让文件 watcher 漏事件,PATH 模糊只是雪上加霜。
团队 / 多开发者配置
单人开发可以用一次性 PATH 编辑糊弄过去 command not found。团队不行——每个新人撞同一堵墙,CI 容器每次重建也撞。两种姿势能扩。
姿势 1:把 Codex 钉在 Dev Container 里
把安装写到 Dockerfile,让团队 check 进仓库。每位贡献者、每个 CI job 都从同一个镜像起:
FROM node:22-bookworm
# 把 Codex CLI 钉到已知能跑的版本
RUN npm install -g @openai/[email protected]
# 镜像构建时就跑健康检查——装完没产出二进制就大声报错
RUN codex --version
# 团队默认工作目录
WORKDIR /workspace
配上 .devcontainer/devcontainer.json,每个团队成员都能直接拿到能跑的 codex,不用各自去考古每台机的 PATH。
姿势 2:共享 bootstrap 脚本
不想用容器的团队,仓库里放一份 bootstrap-codex.sh 能省 7 个 Slack 帖:
#!/usr/bin/env bash
set -euo pipefail
# 验 Node 16+(Codex 0.137.0 floor;团队标准是 20 LTS)
if ! node -e "process.exit(process.versions.node.split('.')[0] >= 16 ? 0 : 1)"; then
echo "ERROR: Codex CLI requires Node 16+. Install via nvm: nvm install 20"
exit 1
fi
# 验 npm prefix 是用户拥有的(不用 sudo)
PREFIX=$(npm prefix -g)
if [[ ! -w "$PREFIX/bin" ]]; then
echo "ERROR: npm prefix $PREFIX is not writable. Run: npm config set prefix ~/.npm-global"
exit 1
fi
# 验 prefix 在 PATH 上
if ! echo "$PATH" | tr ':' '\n' | grep -q "^$PREFIX/bin$"; then
echo "WARN: $PREFIX/bin is not on PATH. Add: export PATH=\"$PREFIX/bin:\$PATH\""
fi
npm install -g @openai/[email protected]
codex --version
这脚本把每种失败模式在安装前就甩到脸上,而不是装完了再说。
越搞越糟时:清理重来
多次混着 sudo / nvm / Volta 装下来,机器会进到一种 shim 和 node_modules 互相矛盾的状态,再怎么 fix 也无效。干净重置:
# 把所有 Codex 安装变种都干掉
npm uninstall -g @openai/codex 2>/dev/null || true
sudo npm uninstall -g @openai/codex 2>/dev/null || true
volta uninstall @openai/codex 2>/dev/null || true
# 抹掉残留 shim(路径按你机器上的 prefix 调)
rm -f "$(npm prefix -g)/bin/codex" 2>/dev/null || true
rm -f /usr/local/bin/codex 2>/dev/null || true
rm -f ~/.npm-global/bin/codex 2>/dev/null || true
# 抹掉 Codex 配置(这会清掉登录状态;要留就先备份)
mv ~/.codex ~/.codex.bak 2>/dev/null || true
# 从头装一次
npm install -g @openai/[email protected]
codex --version
清理之后再按 Fix 1 到 Fix 7 顺序走一遍。全新状态下,每条诊断命令打出来才有意义。
如果你装完 codex 跑起来报的是 401、429、Sandbox 那一类的错——属于安装没问题、运行时出问题——直接看 Codex CLI 常见错误排查手册:401、429、Sandbox、网络全套修复。本文专管装完直接 command not found 的 PATH 类问题。
怎么监控你的 Codex 安装(顺便跟上版本)
Codex 大概一周一发——0.137.0 是 2026-06-04 发的。几个习惯能让 command not found 不再回潮。
在 Brewfile 或 Dockerfile 里钉版本
团队场景里把安装锁死,别让 npm install -g 漂:
# Dev container 用的 Dockerfile 片段
FROM node:22-bookworm
RUN npm install -g @openai/[email protected]
ENV PATH="/usr/local/bin:${PATH}"
CMD ["codex"]
容器里钉死版本,团队每个开发者拿到的都是同一个 Codex,不用再各自考古 PATH。
盯 changelog
官方 changelog 列每个发布。安装相关的修复落在 install.sh / install.ps1 行——最近例子:0.136.0 加了 CODEX_NON_INTERACTIVE=1 给无头安装用。
健康检查脚本
存成 ~/bin/codex-health.sh,PATH 不对劲的时候就跑一下:
#!/usr/bin/env bash
set -e
echo "Node: $(node --version 2>/dev/null || echo MISSING)"
echo "npm: $(npm --version 2>/dev/null || echo MISSING)"
echo "npm prefix: $(npm prefix -g 2>/dev/null || echo MISSING)"
echo "codex on \$PATH? $(which codex 2>/dev/null || echo NO)"
echo "codex version: $(codex --version 2>/dev/null || echo NOT RUNNING)"
三行哪行失败,就直接告诉你该用上面哪个 fix。
FAQ
frontmatter 里的 faq 是规范答案;那里的问题对齐了 Google “codex command not found” 及相关查询的 People Also Ask。扫一眼就行——覆盖了 npm prefix、sudo、NVM 隔离、Codex Desktop bug、Node 版本要求、Homebrew、Windows %APPDATA%\npm、npx 对二进制这几个面。
本次刷新核对的来源
- npm registry ——
@openai/[email protected]—— 核对engines.node: ">=16"和optionalDependencies平台二进制(2026-06-04 核对) - Codex CLI changelog —— 0.136.0 / 0.137.0 版本,install.sh 和 install.ps1 变更(2026-06-04 核对)
- openai/codex 源码
model-provider-info—— 0.137.0 里WireApi::Responses是唯一被接受的变体,反序列化器把"chat"映射到CHAT_WIRE_API_REMOVED_ERROR - openai/codex#13566 —— NVM 非交互 shell bug,2026-03-05 开,仍 open
- openai/codex#14016 —— Windows 上 fnm,2026-04 开,仍 open
- openai/codex#10342 —— “operation rejected by your operating system” macOS sudo 冲突
- openai/codex#20206 —— Windows Codex Desktop app-server 解析
- npm 文档 —— Resolving EACCES permissions(用户 prefix 方案,截至 npm 10 仍现行)
- NVM README —— 支持的 shell rc 文件 + default alias(NVM 文档里的初始化文件是
~/.zshrc、~/.bashrc、~/.bash_profile、~/.profile,不是~/.zshenv) - zsh 手册 —— 启动文件(
~/.zshenv每个 Zsh 进程都会被 source,包括非交互 shell,这就是 NVM 不该住那的原因) - ofox 文档:Codex CLI 集成 和 OpenClaw provider 配置(后者记录了
ofoxai-openaiprovider 的openai-responses协议)


