OpenAI Codex CLI 安装失败通常属于五类问题之一：npm 全局权限错误（EACCES）、Intel Mac 架构不匹配（arm64 二进制跑在 x86_64 上）、Windows 沙盒启动失败、Linux GLIBC 版本过低，以及国内网络导致的下载超时。每类都有明确的解决路径，最后的保底方案是直接从 GitHub Releases 下载对应平台的预编译二进制文件。

 

安装方式速览

Codex CLI 提供四种安装途径：

方式

命令

适合场景

npm 全局安装

npm install -g @openai/codex

已有 Node.js 环境

Homebrew

brew install --cask codex

macOS 用户

Cargo（Rust）

cargo install --locked codex

已有 Rust 工具链

直接下载二进制

GitHub Releases 手动下载

网络受限 / 其他方式失败时

以下按报错类型逐一处理。

 

错误一：npm EACCES 权限错误（最常见）

报错特征

npm warn checkPermissions Missing write access to /usr/local/lib/node_modules
npm error code EACCES
npm error syscall access
npm error path /usr/local/lib/node_modules/@openai

原因

系统 Node.js 安装在 /usr/local，全局 npm 目录属于 root，普通用户没有写权限。

解法一（推荐）：用 nvm 管理 Node.js

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
# 重新加载 shell
source ~/.zshrc  # 或 ~/.bashrc
 
# 安装最新 LTS 版 Node.js
nvm install --lts
nvm use --lts
 
# 此时 npm 全局目录在用户目录下，无需 sudo
npm install -g @openai/codex

解法二：重定向 npm 全局目录

# 修改 npm prefix（不适用于 Windows）
npm config set prefix ~/.local
 
# 加入 PATH（zsh 用户）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# 重新安装
npm install -g @openai/codex

❌ 不要用 sudo

# 不要这样做！
sudo npm install -g @openai/codex

官方 npm 文档明确指出：以 root 权限运行安装脚本存在安全风险，且治标不治本。

错误二：Intel Mac 架构不匹配（arm64 装到 x86_64）

报错特征

Error: codex: App codex cannot be installed on this machine
# 或运行时报错：
Error: Illegal instruction: 4
# 或 Homebrew 报错：
Error: codex: macOS version too old

原因

brew install --cask codex 或 codex app 命令在 Intel Mac 上下载了 arm64 版本的 DMG（GitHub Issue #17461、#23115）。

验证当前架构

uname -m
# 输出 x86_64 → Intel Mac
# 输出 arm64  → Apple Silicon (M1/M2/M3/M4)

解法：手动下载 Intel 版二进制

从 GitHub Releases 直接下载 x86_64 版本：

# 下载 Intel Mac 版本
curl -L https://github.com/openai/codex/releases/download/rust-v0.130.0/codex-x86_64-apple-darwin.tar.gz \
  -o codex-mac-intel.tar.gz
 
# 解压
tar -xzf codex-mac-intel.tar.gz
 
# 移动到 PATH
sudo mv codex /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex
 
# 验证
codex --version

官方 Issue #10410（Intel Mac 支持）已于 2026 年 4 月标记完成，最新版 v0.130.0 应已修复，但 Homebrew tap 更新可能滞后，建议直接下载二进制。

错误三：Windows 安装问题

Windows 版 Codex CLI 有多个已知问题，按严重程度处理：

问题 A：sandbox-setup.exe 未找到

Error: failed to spawn codex-windows-sandbox-setup.exe: program not found

临时解法：在 ~/.codex/config.toml 里关闭沙盒：

sandbox_mode = "danger-full-access" 注意：danger-full-access 模式下 Codex 可以读写系统任意目录，仅在本地开发机器上使用。

问题 B：启动约 40 秒卡顿（Issue #23207）

已知问题，官方正在修复。临时解法：等待（不是卡死），或改用 WSL2 版本。

问题 C：Windows ARM64 暂不支持（Issue #23170）

官方尚未发布 Windows ARM64 版本。解法：在 WSL2 里安装 Linux 版本：

# 开启 WSL2（管理员 PowerShell）
wsl --install
 
# 进入 WSL2，按 Linux 步骤安装
wsl

问题 D：中文路径/文件名导致历史记录乱码（Issue #23126）

解法：将项目路径改为纯英文目录，或在 WSL2 中操作。

错误四：Linux GLIBC 版本过低

报错特征

/lib/x86_64-linux-gnu/libc.so.6: version 'GLIBC_2.32' not found
# 或
version `GLIBC_2.34' not found

原因

Codex CLI 的动态链接版本依赖较新的 glibc，CentOS 7、Ubuntu 18.04 等老系统 glibc 版本（2.17~2.27）不满足要求。官方正在推进修复（PR #21812），但截至 v0.130.0 尚未完全解决。

解法：使用 musl 静态链接版本

GitHub Releases 同时提供 musl 编译版本，不依赖系统 glibc：

# x86_64 Linux（推荐 CentOS/老版 Ubuntu 用户）
curl -L https://github.com/openai/codex/releases/download/rust-v0.130.0/codex-x86_64-unknown-linux-musl.tar.gz \
  -o codex-linux-musl.tar.gz
 
tar -xzf codex-linux-musl.tar.gz
sudo mv codex /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex
codex --version

版本

文件名

适用系统

动态链接

codex-x86_64-unknown-linux-gnu.tar.gz

Ubuntu 22.04+、Debian 11+

静态链接（musl）

codex-x86_64-unknown-linux-musl.tar.gz

所有 Linux（推荐）

arm64 musl

codex-aarch64-unknown-linux-musl.tar.gz

树莓派、ARM 服务器

 

错误五：国内网络下载超时

报错特征

npm error network timeout at: https://registry.npmjs.org/@openai/codex
npm error network This is a problem related to network connectivity

解法一：切换 npm 镜像源

# 临时使用淘宝镜像
npm install -g @openai/codex --registry https://registry.npmmirror.com
 
# 永久切换
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

解法二：手动下载二进制（最稳）

直接从 GitHub Releases 页面下载对应平台的 tar.gz，或通过国内 GitHub 镜像：

# 使用 GitHub 镜像加速（以 macOS Apple Silicon 为例）
curl -L https://mirror.ghproxy.com/https://github.com/openai/codex/releases/download/rust-v0.130.0/codex-aarch64-apple-darwin.tar.gz \
  -o codex.tar.gz
 
tar -xzf codex.tar.gz
sudo mv codex /usr/local/bin/

保底方案：直接下载预编译二进制

无论什么原因安装失败，以下步骤总是可行的：

1. 打开 https://github.com/openai/codex/releases/tag/rust-v0.130.0

2. 根据平台选择对应文件：

平台

文件名

macOS Apple Silicon

codex-aarch64-apple-darwin.tar.gz

macOS Intel

codex-x86_64-apple-darwin.tar.gz

Linux x86_64（推荐 musl）

codex-x86_64-unknown-linux-musl.tar.gz

Linux arm64

codex-aarch64-unknown-linux-musl.tar.gz

3. 解压并移动到 PATH：

tar -xzf codex-*.tar.gz
sudo mv codex /usr/local/bin/
sudo chmod +x /usr/local/bin/codex
codex --version

安装成功后：国内用户如何使用？

Codex 安装成功后，默认连接 OpenAI API，国内无法直连。配置 ~/.codex/config.toml 改用国内兼容 API：

# 七牛云兼容 OpenAI 协议，国内手机号注册即可使用 openai_base_url = "https://api.qnaigc.com/v1" model = "deepseek-v4-pro" sandbox_mode = "workspace-write" web_search = "disabled" 同时设置环境变量：

export OPENAI_API_KEY="你的七牛云API Key"

七牛云 API Key 申请

FAQ

Q：brew install --cask codex 提示 “cask codex is not in the main tap”，怎么办？

A：说明 Homebrew 官方 tap 里暂无 codex cask，或名称有变。先尝试 brew install codex（无 --cask），若依然找不到，改用 npm 方式或手动下载二进制。

Q：安装完运行 codex 报 “command not found”？

A：说明可执行文件不在 $PATH 里。运行 npm bin -g 查看 npm 全局 bin 目录，确认该路径在 $PATH 中；或检查 /usr/local/bin/codex 是否存在。

Q：运行时报 Error: GLIBC_2.34 not found，但我用 npm 而不是二进制安装的？

A：npm 包内部捆绑了 Rust 编译的二进制文件，同样有 glibc 依赖。解法是改用 GitHub Releases 的 musl 版本手动安装，npm 包不适合旧版 Linux。Q：Windows 上 codex 启动一直转圈超过 1 分钟？

A：已知问题（Issue #23207），与 Windows Sandbox 初始化有关。临时绕过方式：在 config.toml 设置 sandbox_mode = "danger-full-access"，或改在 WSL2 内运行。

 

总结

Codex CLI 安装失败 90% 集中在四个场景：npm 权限（用 nvm 解决）、Intel Mac 架构错误（手动下载 x86_64 二进制）、Windows sandbox 问题（关闭沙盒或改用 WSL2）、Linux 老系统 glibc（用 musl 版本）。国内网络超时用淘宝镜像或 ghproxy 加速。所有方式都失败时，从 GitHub Releases 直接下载预编译二进制是可靠的最终手段。

Codex CLI v0.130.0 发布于 2026-05-08，本文信息基于官方 GitHub Issues (#17461、#23115、#23194、#23207、#23170、#21812) 和 npm 官方文档。

 

参考资源

● Codex CLI GitHub：https://github.com/openai/codex

● Codex Releases：https://github.com/openai/codex/releases/tag/rust-v0.130.0

● npm EACCES 修复文档：https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

● 七牛云 AI API Key