环境准备

3.1 系统与依赖要求

根据 CSDN「Codex CLI 教程」专栏整理的要求矩阵:

依赖项	最低要求	推荐配置
操作系统	Windows 10/11、macOS 12+、主流 Linux 发行版	Windows 11(推荐 WSL2)、macOS 14+、Ubuntu 22.04+
Node.js	v20.0.0+	v22.0.0+(LTS 长期支持版)
npm	v10.0.0+	最新稳定版

⚠️ Codex CLI 依赖 Node.js 22+。版本过低会直接安装失败或运行异常。

3.2 安装前环境预检

执行以下两条命令确认环境符合要求:

# 检查 Node.js 版本,需 v20.0.0 及以上
node --version

# 检查 npm 版本,需 v10.0.0 及以上
npm --version

3.3 安装 Node.js 22+

方式一:nvm 多版本管理(推荐)

适合需要在不同 Node 版本间切换的开发者:

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node 22
nvm install 22

# 切换到 Node 22
nvm use 22

# 验证
node -v  # 应输出 v22.x.x

方式二:macOS 用 Homebrew

brew install node@22

方式三:Ubuntu/Debian 用 NodeSource

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

方式四:Windows

从 Node.js 官网下载安装包,或用 winget:

winget install OpenJS.NodeJS.LTS

3.4 npm 权限治理(避免 sudo)

全局安装 npm 包时常见的 EACCES 权限错误,根因是默认全局目录需要 root 权限。不推荐用 sudo 安装 npm 包,推荐配置自定义全局目录:

# 创建自定义全局目录
mkdir ~/.npm-global

# 设置 npm 全局 prefix
npm config set prefix '~/.npm-global'

# 写入环境变量(bash 用户)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# zsh 用户
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

配置完成后,后续 npm install -g 不再需要 sudo。

3.5 网络环境准备(国内用户)

npm 国内镜像

# 临时使用镜像
npm install -g @openai/codex --registry=https://registry.npmmirror.com

# 永久设置镜像
npm config set registry https://registry.npmmirror.com

系统代理(用于访问 OpenAI 服务)

Codex CLI 调用 OpenAI API 时需要网络可达。国内用户通常配置 HTTP 代理:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

可写入 ~/.zshrc 或 ~/.bashrc 持久化。验证代理生效:

curl -I https://api.openai.com

3.6 Git 安装与基础配置

Codex 与 Git 深度集成(代码审查、worktree、PR 生成都依赖 Git),建议提前装好:

# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install -y git

# Windows:从 git-scm.com 下载,或
winget install Git.Git

# 基础配置
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

3.7 WSL2 安装(Windows 用户专属)

Codex CLI 的某些功能依赖 Unix 环境,Windows 用户推荐使用 WSL2。在 PowerShell 管理员模式下运行:

# 安装 WSL2
wsl --install

# 重启后进入 WSL
wsl

WSL2 配置要点

确保 Windows 版本在 19041 或更高
启用“虚拟机平台”功能
下载并安装 WSL2 Linux 内核更新包
将 WSL2 设置为默认版本:wsl --set-default-version 2
从 Microsoft Store 安装 Ubuntu 发行版

进入 WSL 后,按上面 3.3 ~ 3.5 的 Linux 步骤安装 Node.js 和配置 npm 即可。

💡 CSDN 教程明确指出:Windows 用户若计划长期使用 Codex CLI,强烈推荐配置 WSL2 环境,兼容性和稳定性远优于原生 Windows 环境。

资料来源

CSDN《Codex CLI 教程(一)安装指南》系统要求矩阵与 WSL 提示
FastGPTPlus《OpenAI Codex CLI 完整教程》macOS/Linux 安装步骤
编程指北 csguide.cn 国内网络代理配置
编程指北:Homebrew 已同步最新版 brew install codex