---

解决报错 Error: Missing optional dependency @openai/codex-linux-arm64

一图看懂：

问题复现：

uname -a
Linux hostname-2pbfv.foreman.pxe 5.10.0-282.0.0.184.oe2203sp3.aarch64 #1 SMP Wed Sep 17 13:32:56 CST 2025 aarch64 aarch64 aarch64 GNU/Linu
node -p "process.platform"
linux
node -p "process.arch"
arm64

# npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com （用国内 NPM 镜像，可选）
npm install -g @openai/codex@latest
source ~/.bashrc
codex --version

这个报错的核心通常不是 Node.js 本身，而是 Codex 主包已经安装，但 Linux ARM64 平台对应的原生可执行依赖 @openai/codex-linux-arm64 没有被 npm 一起装上。常见原因包括 npm 配置、镜像源同步、架构识别以及残留安装，下面逐项排查。

Codex 的 Linux ARM64 二进制是通过 optionalDependencies 发布的。如果主包与平台包发布存在短暂时间差，npm install 可能正常退出，但实际缺少平台二进制，运行时会提示 Missing optional dependency。OpenAI 的 Issue 中已经记录了类似情况。另外，我是全局 npm 安装，如果配置了 omit=optional，或使用了同步不及时的镜像源，也会出现完全相同的报错。

因此，问题大概率是：@openai/codex 的 JS 启动器已安装，但 Linux ARM64 所需的原生二进制包 @openai/codex-linux-arm64 没有落地。

推荐方案：继续使用 npm

如果希望继续通过 npm 管理，请先确认系统与 npm 配置：

uname -m
node -p "process.platform"
node -p "process.arch"

正常应显示类似：

aarch64
linux
arm64

然后检查 npm 是否禁用了可选依赖：

npm config get omit
npm config get optional
npm config get registry

重点关注是否存在：

omit = optional

或

optional = false

如有，执行：

npm config delete omit
npm config delete optional

建议暂时切换到 npm 官方源，避免镜像同步延迟：

npm config set registry https://registry.npmjs.org/

重新干净安装：

npm uninstall -g @openai/codex
npm cache clean --force
# npm install -g @openai/codex@latest --include=optional --registry=https://registry.npmmirror.com （用国内 NPM 镜像，可选）
npm install -g @openai/codex@latest --include=optional

codex --version

最终解决了问题，2026 年 9 月 5 日 @openai/codex 的最新版本是 0.153.4：

验证并确认 ARM64 包是否落盘：

ls -la /root/.local/npm-global/lib/node_modules/@openai/codex/node_modules/@openai/
total 12
drwxr-xr-x. 3 root root 4096 Sep  5 05:16 .
drwxr-xr-x. 3 root root 4096 Sep  5 05:10 ..
drwxr-xr-x. 3 root root 4096 Sep  5 05:16 codex-linux-arm64

正常情况下，可以看到目录中除了 codex，还应包含类似 codex-linux-arm64 的包。

如果问题依旧，请执行以下诊断命令：

echo "=== OS ==="
uname -a
uname -m

echo "=== Node ==="
node -v
node -p "process.platform"
node -p "process.arch"

echo "=== npm ==="
npm -v
npm config get registry
npm config get omit
npm config get optional

echo "=== Codex package ==="
npm list -g @openai/codex --depth=1 || true

echo "=== OpenAI global modules ==="
ls -lah /root/.local/npm-global/lib/node_modules/@openai/ || true

其他方案：使用官方安装脚本

Codex 官方为 Linux 提供了独立安装脚本，可以绕过 npm 的 optional dependency 问题。

# 1. 移除 npm 安装的 Codex，避免 PATH 冲突
npm uninstall -g @openai/codex

# 2. 清除 shell 命令缓存
hash -r

# 3. 使用官方安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 4. 验证
command -v codex
codex --version

官方安装器会根据系统架构下载对应二进制，Linux ARM64 对应 aarch64-unknown-linux-musl。这是最直接的解决方式。

Node.js v22.23.1 无需降级，Codex 对 Node 版本的要求低于此。问题核心不是 Node 版本，而是 ARM64 optional dependency 缺失。

如果希望尽快解决，可以直接执行这三条命令即可：

npm uninstall -g @openai/codex
hash -r
curl -fsSL https://chatgpt.com/codex/install.sh | sh

然后运行 codex --version 确认是否成功了。