Codex CLI 安装失败排查指南：五类报错一次解决

适用版本：Codex CLI v0.130.0+。如果你在安装 OpenAI Codex CLI 时遇到权限、架构、Windows 沙盒、Linux glibc 或网络超时问题，可以按本文顺序排查。

Codex CLI 是终端里的 AI 编程 Agent，安装方式看似简单，但真实环境差异很大：macOS 有 Intel 与 Apple Silicon，Linux 有 glibc 版本差异，Windows 还涉及沙盒组件，国内网络还可能在 npm 或 GitHub 下载阶段超时。

排查时不要一上来反复重装，先判断报错属于哪一类，再选对应方案。

先确认你采用的是哪种安装方式

常见安装路径有四种：

建议优先用 npm 或 Homebrew；如果遇到架构、glibc 或网络问题，直接下载对应平台的预编译二进制通常更稳。

一、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  # 或 source ~/.bashrc

# 安装 LTS Node.js
nvm install --lts
nvm use --lts

# 再安装 Codex CLI
npm install -g @openai/codex

nvm 会把 Node.js 和 npm 全局包放在用户目录下，避免 root 权限问题，也方便之后切换 Node 版本。

备选解法：修改 npm prefix

npm config set prefix ~/.local

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

npm install -g @openai/codex

不建议使用：

sudo npm install -g @openai/codex

sudo npm install -g 可能让安装脚本以 root 权限执行，既有安全风险，也容易留下后续权限混乱。

二、Intel Mac：下载到了 arm64 版本

典型报错

Error: codex: App codex cannot be installed on this machine
Error: Illegal instruction: 4
Error: codex: macOS version too old

先确认机器架构

uname -m
# x86_64 代表 Intel Mac
# arm64  代表 Apple Silicon

如果你是 Intel Mac，却通过 Homebrew 或 App 包下载到了 arm64 构建，就可能出现安装失败或运行时报非法指令。

处理方式：手动下载 x86_64 二进制

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
sudo mv codex /usr/local/bin/codex
sudo chmod +x /usr/local/bin/codex

codex --version

Apple Silicon 用户则应选择 codex-aarch64-apple-darwin.tar.gz。

三、Windows：优先考虑 WSL2

Windows 版 Codex CLI 可能遇到沙盒组件、启动卡顿、ARM64 支持不足、中文路径乱码等问题。

sandbox-setup.exe 找不到

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

临时绕过方式是在 ~/.codex/config.toml 中关闭受限沙盒：

sandbox_mode = "danger-full-access"

这个模式允许 Codex 读写更大范围的系统路径，只适合本地可控开发机，不建议在共享环境中使用。

启动长时间卡住

如果 Windows 上启动后约几十秒没有响应，不一定是完全卡死，可能是沙盒初始化慢。可先等待一次；如果长期影响体验，建议改用 WSL2。

Windows ARM64

如果暂时没有可用的 Windows ARM64 构建，可以在 WSL2 中使用 Linux 版本：

wsl --install

进入 WSL2 后再按 Linux 步骤安装 Codex CLI。

中文路径乱码

如果历史记录或文件名出现乱码，优先把项目移动到纯英文路径，例如：

~/projects/my-app

或者在 WSL2 内操作项目。

四、Linux：glibc 版本过低

典型报错

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

为什么会出现

CentOS 7、Ubuntu 18.04 等老系统自带 glibc 较旧，而部分 Codex CLI 二进制依赖较新的 glibc。即使用 npm 安装，包内也可能包含 Rust 编译产物，仍然会触发同类问题。

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

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

选择文件时可按平台判断：

五、国内网络：npm 或 GitHub 下载超时

npm 下载超时

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

可临时使用镜像源：

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 下载慢

如果 npm 不稳定，可以直接下载预编译二进制。下载完成后只需解压、移动到 PATH、赋予可执行权限。

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

安装完成后：国内使用还要改 API 端点

安装成功只代表命令可运行。Codex CLI 默认连接 OpenAI API，国内环境通常还需要在 ~/.codex/config.toml 中配置兼容端点：

openai_base_url = "https://code.ai80.vip/v1"
model = "deepseek-v4-pro"
sandbox_mode = "workspace-write"
web_search = "disabled"

再设置环境变量：

export OPENAI_API_KEY="你的 API Key"

如果需要在国内稳定接入 OpenAI 兼容模型，可使用 Code80 这类支持统一 API 入口的服务，把安装问题和网络接入问题分开处理。

FAQ

安装后提示 command not found 怎么办？

说明可执行文件不在 PATH 中。先检查：

which codex
npm bin -g

如果是手动安装，确认 /usr/local/bin/codex 存在且有执行权限。

npm 安装成功但运行时报 glibc 错误怎么办？

npm 包内部也可能包含原生二进制。老 Linux 系统建议放弃 npm 安装，直接换 musl 静态链接版本。

Windows 上应该原生安装还是用 WSL2？

如果只是轻量体验，可以先原生安装；如果要长期在项目中使用，WSL2 更接近 Linux 开发环境，也更容易复用文档里的命令。

总结

Codex CLI 安装失败大多集中在五类问题：npm 权限、Mac 架构不匹配、Windows 沙盒、Linux glibc、国内网络超时。排查顺序建议是：先看报错类型，再确认系统架构和安装方式；如果常规安装反复失败，直接下载对应平台的预编译二进制，通常是最快的解决路径。