官方原文索引： CLI Setup / System Requirements / Windows Setup Guide
1. 核心架构与原理解析
Codex CLI 是一个基于 Node.js 的 npm 全局包，但其底层核心 Harness 使用 Rust 编写，通过 Node.js 封装暴露给终端。这种混合架构兼顾了 Rust 的性能（文件系统监控、沙盒执行）和 Node.js 的生态（npm 分发、配置管理）。
安装流程拓扑：
系统要求矩阵：
| 操作系统 | 支持状态 | 推荐安装方式 | 特殊要求 |
|---|---|---|---|
| macOS 12+ | ✅ 完全支持 | npm / Homebrew | Apple Silicon 选 arm64 包 |
| Linux (Ubuntu 20.04+) | ✅ 完全支持 | npm / 二进制 | musl 静态链接包兼容性最佳 |
| Windows 11 | ⚠️ 实验性支持 | Microsoft Store (App) | PowerShell 需注意执行策略 |
| WSL2 | ✅ 推荐方案 | npm | 项目必须放在 Linux 文件系统 (~/projects) |
2. 工程落地与代码示例
环境检查脚本（一键诊断）
#!/bin/bash
# check-codex-env.sh - 环境预检脚本
echo "=== Codex 环境检查 ==="
# Node.js 版本检查
NODE_VERSION=$(node -v 2>/dev/null | sed 's/v//')
REQUIRED_NODE="22.0.0"
if [ -z "$NODE_VERSION" ]; then
echo "❌ Node.js 未安装"
echo " 安装方式: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -"
exit 1
fi
# 版本比较函数
version_ge() {
[ "$(printf '%s\n' "$1" "$2" | sort -V | head -n1)" = "$2" ]
}
if version_ge "$NODE_VERSION" "$REQUIRED_NODE"; then
echo "✅ Node.js $NODE_VERSION (>= $REQUIRED_NODE)"
else
echo "❌ Node.js $NODE_VERSION (需要 >= $REQUIRED_NODE)"
exit 1
fi
# npm 检查
NPM_VERSION=$(npm -v 2>/dev/null)
if [ -n "$NPM_VERSION" ]; then
echo "✅ npm $NPM_VERSION"
else
echo "❌ npm 不可用"
exit 1
fi
# Git 检查（Codex 依赖 Git 做 diff/回滚）
GIT_VERSION=$(git --version 2>/dev/null | awk '{print $3}')
if [ -n "$GIT_VERSION" ]; then
echo "✅ Git $GIT_VERSION"
else
echo "⚠️ Git 未安装（建议安装用于版本控制）"
fi
# 网络连通性检查
curl -sI https://api.openai.com/v1/models >/dev/null 2>&1
if [ $? -eq 0 ]; then
echo "✅ 可访问 OpenAI API"
else
echo "⚠️ 无法直接访问 OpenAI API（可能需要代理或配置 OPENAI_BASE_URL）"
fi
echo "=== 检查完成 ==="macOS / Linux 标准安装
# 前置检查：Node.js >= 22
node -v # 应输出 v22.x.x 或更高
# 方式 A：npm 全局安装（推荐）
npm install -g @openai/codex
# 方式 B：Homebrew（仅 macOS，安装桌面 App）
brew install --cask codex
# 验证安装
codex --version
# 输出示例：codex 0.132.0Windows 安装策略
# 策略 1：桌面 App（推荐普通用户）
# Microsoft Store 搜索 "Codex" 安装
# 策略 2：WSL2（推荐开发者）
wsl --install # 安装 WSL2 + Ubuntu
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @openai/codex
# 策略 3：原生 PowerShell（实验性）
npm.cmd install -g @openai/codex
# ⚠️ 注意：使用 .cmd 后缀避开 PowerShell 执行策略限制
codex.cmd --version企业内网 / 国内环境配置
# 配置兼容 API 端点（以私有网关为例）
export OPENAI_API_KEY="***"
export OPENAI_BASE_URL="https://api.enterprise-proxy.com/v1"
# 或者写入 shell 配置永久生效
echo 'export OPENAI_API_KEY="***"' >> ~/.zshrc
echo 'export OPENAI_BASE_URL="https://api.enterprise-proxy.com/v1"' >> ~/.zshrc
source ~/.zshrc国内镜像加速安装
# 使用淘宝 npm 镜像加速下载
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex --registry=https://registry.npmmirror.com
# 安装完成后恢复官方源（避免其他包受影响）
npm config set registry https://registry.npmjs.org诊断工具（v0.131.0+）
# 一键诊断环境、认证、网络连通性
codex doctor
# 预期输出：
# ✅ Runtime environment
# ✅ Authentication
# ✅ Network connectivity
# ✅ Config file validity
# ✅ Sandbox configuration多版本共存管理
# 使用 nvm 管理 Node.js 版本，确保 Codex 运行环境隔离
nvm install 22
nvm use 22
nvm alias default 22
# 如果需要在多个 Codex 版本间切换
npm install -g @openai/[email protected] # 稳定旧版
npm install -g @openai/codex@latest # 最新版
codex --version3. 场景深入：复杂环境下的安装实践
场景：企业内网无外网访问
场景：Docker 容器内运行 Codex
# Dockerfile.codex
FROM node:22-alpine
# 安装必要依赖
RUN apk add --no-cache git curl
# 安装 Codex
RUN npm install -g @openai/codex
# 创建工作目录
WORKDIR /workspace
# 挂载项目卷和配置文件
VOLUME ["/workspace", "/root/.codex"]
ENTRYPOINT ["codex"]# 构建并运行
docker build -f Dockerfile.codex -t codex-cli .
docker run -it -v $(pwd):/workspace -v ~/.codex:/root/.codex codex-cli4. 💡 核心避坑与最佳实践 (Takeaways)
- Windows 项目路径陷阱：WSL2 中访问
/mnt/c/（Windows 盘符）会导致 IO 性能暴跌 10 倍以上，项目必须放在 Linux 文件系统（~/projects） - npm EACCES 权限错误：不要第一反应
sudo，改用 nvm 管理 Node.js 或修正 npm 全局目录权限：mkdir ~/.npm-global && npm config set prefix '~/.npm-global' - PowerShell .ps1 vs .cmd：遇到 "无法加载脚本" 错误时，使用
npm.cmd和codex.cmd绕过执行策略，或在管理员 PowerShell 执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - 定期更新：Codex 迭代极快，建议每周运行
npm install -g @openai/codex@latest保持最新 - 安装前跑预检脚本：把上面的
check-codex-env.sh纳入团队 onboarding，避免"安装好了却跑不起来"的返工