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

解决报错 Error: Missing optional dependency openai/codex-linux-arm64一图看懂问题复现uname-aLinux hostname-2pbfv.foreman.pxe5.10.0-282.0.0.184.oe2203sp3.aarch64#1 SMP Wed Sep 17 13:32:56 CST 2025 aarch64 aarch64 aarch64 GNU/Linunode-pprocess.platformlinuxnode-pprocess.archarm64# npm install -g openai/codexlatest --registryhttps://registry.npmmirror.com 用国内 NPM 镜像可选npminstall-gopenai/codexlatestsource~/.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 安装如果配置了omitoptional或使用了同步不及时的镜像源也会出现完全相同的报错。因此问题大概率是openai/codex的 JS 启动器已安装但 Linux ARM64 所需的原生二进制包openai/codex-linux-arm64没有落地。推荐方案继续使用 npm如果希望继续通过 npm 管理请先确认系统与 npm 配置uname-mnode-pprocess.platformnode-pprocess.arch正常应显示类似aarch64 linux arm64然后检查npm是否禁用了可选依赖npmconfig get omitnpmconfig get optionalnpmconfig get registry重点关注是否存在omit optional或optional false如有执行npmconfig delete omitnpmconfig delete optional建议暂时切换到 npm 官方源避免镜像同步延迟npmconfigsetregistry https://registry.npmjs.org/重新干净安装npmuninstall-gopenai/codexnpmcache clean--force# npm install -g openai/codexlatest --includeoptional --registryhttps://registry.npmmirror.com 用国内 NPM 镜像可选npminstall-gopenai/codexlatest--includeoptional 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/ total12drwxr-xr-x.3root root4096Sep505:16.drwxr-xr-x.3root root4096Sep505:10..drwxr-xr-x.3root root4096Sep505:16 codex-linux-arm64正常情况下可以看到目录中除了codex还应包含类似codex-linux-arm64的包。如果问题依旧请执行以下诊断命令echo OS uname-auname-mecho Node node-vnode-pprocess.platformnode-pprocess.archecho npm npm-vnpmconfig get registrynpmconfig get omitnpmconfig get optionalecho Codex package npmlist-gopenai/codex--depth1||trueecho OpenAI global modules ls-lah/root/.local/npm-global/lib/node_modules/openai/||true其他方案使用官方安装脚本Codex 官方为 Linux 提供了独立安装脚本可以绕过 npm 的 optional dependency 问题。# 1. 移除 npm 安装的 Codex避免 PATH 冲突npmuninstall-gopenai/codex# 2. 清除 shell 命令缓存hash-r# 3. 使用官方安装脚本curl-fsSLhttps://chatgpt.com/codex/install.sh|sh# 4. 验证command-vcodex codex--version官方安装器会根据系统架构下载对应二进制Linux ARM64 对应aarch64-unknown-linux-musl。这是最直接的解决方式。Node.js v22.23.1 无需降级Codex 对 Node 版本的要求低于此。问题核心不是 Node 版本而是 ARM64 optional dependency 缺失。如果希望尽快解决可以直接执行这三条命令即可npmuninstall-gopenai/codexhash-rcurl-fsSLhttps://chatgpt.com/codex/install.sh|sh然后运行codex --version确认是否成功了。