前两篇讲清楚了 Codex 是什么、和 Claude Code / Cursor 怎么选。这篇直接装机——macOS、Linux 原生安装 + Windows WSL2 全流程，三种安装方式全覆盖，一个步骤不省。
前置依赖：Node.js 22+
Codex CLI 对 Node.js 的版本要求比 Claude Code 更严格——需要 Node.js 22 或更高版本。装之前先确认：
node -v
如果版本低于 22，用 nvm 升级：
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# 安装 Node 22 LTS
nvm install 22
nvm alias default 22
# 验证
node -v # 输出 v22.x.x
npm -v
三种安装方式
Codex CLI 提供三种安装途径，按推荐优先级排列：
方式一：npm 全局安装（推荐）
npm install -g @openai/codex
一条命令，跨平台通用，更新方便。安装完成后验证：
codex --version
输出类似 codex x.x.x 表示成功。
方式二：Homebrew（仅 macOS）
brew install openai/codex/codex
如果你已经是 Homebrew 用户且习惯用它管理 CLI 工具，这种方式更统一。Homebrew 会自动处理 Node.js 依赖。
方式三：独立二进制文件
从 GitHub Releases 页面下载对应系统的二进制文件，放到 PATH 路径下即可。不需要安装 Node.js，适合只想用 Codex、不想装 Node 环境的用户。macOS 和 Linux 都能用。Windows 用户需要走 WSL2 + Linux 二进制。
macOS 安装
npm 方式最快：
npm install -g @openai/codex
codex --version
首次运行时 Codex 会引导你完成认证。对于 macOS 用户，Codex 会打开浏览器让你登录 ChatGPT 账号（如果你有 ChatGPT Plus 订阅，Codex 的基本额度已包含在订阅内）。OAuth 认证后 Codex 会自动保存凭证，后续启动不再需要重新登录。
macOS 常见坑：如果终端提示 codex: command not found，但 npm list -g @openai/codex 显示已安装——这是 PATH 没包含 npm 全局 bin 目录。确认 nvm 的 PATH 配置正确即可。
Linux 安装
npm install -g @openai/codex
codex --version
Linux 特有注意事项：
- EACCES 权限报错 → 不要加 sudo，用 nvm 管理 Node 或手动配 npm 全局路径
- 无图形界面（如 SSH 登录的服务器）→ OAuth 认证会失败，使用 API Key 方式登录（见下文”账号认证”部分）
- 字体兼容 → 安装 Nerd Font，推荐 MesloLGS NF
Windows 安装（WSL2）
Codex CLI 没有 Windows 原生版本，Windows 用户通过 WSL2 运行。WSL2 是硬要求——WSL1 的 I/O 性能不够，Codex 操作文件时的延迟会很高。
第一步：确认或安装 WSL2
PowerShell（管理员）：
# 安装 WSL
wsl --install
# 如果已安装 WSL1，升级到 WSL2
wsl --set-default-version 2
重启电脑后进入 Ubuntu 终端。
第二步：在 WSL 中装 Node.js 22+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
node -v # 确认 >= 22
第三步：安装 Codex
npm install -g @openai/codex
codex --version
第四步：关键——项目路径
Codex 在 WSL 中操作的文件必须放在 WSL 文件系统内（/home/用户名/projects/），不能放在 /mnt/c/ 下。WSL 访问 Windows 文件系统有 10 倍以上的 I/O 损耗，Codex 执行读写操作容易超时。
推荐用 VS Code Remote-WSL 插件在 Windows 端编辑 WSL 内的代码，体验无缝。
第五步：OAuth 认证
首次运行 codex，WSL 自动调用 Windows 端浏览器完成 OAuth 登录。如果浏览器没自动打开，终端会显示一个手动链接，复制到浏览器打开完成授权。
账号认证：ChatGPT 登录 vs API Key
Codex 支持两种认证方式：
ChatGPT 账号登录（OAuth）：你是 ChatGPT Plus/Pro 用户，首次运行 codex 时浏览器弹窗授权。好处是额度已包含在 ChatGPT 订阅里，不用额外付费。且认证一次后凭证自动保存，后续启动无缝。
API Key 登录：你在 platform.openai.com 生成一个 API Key，通过环境变量或配置文件使用：
export OPENAI_API_KEY=sk-your-key-here
# 或
codex config set apiKey sk-your-key-here
API Key 方式适合：无图形界面的服务器环境、需要按量精确控制成本的团队、ChatGPT 订阅之外的独立使用场景。
两种方式可以共存：如果你既有 ChatGPT 订阅又想在某些任务上用 API Key（比如工作项目和个人项目分开计费），Codex 支持通过 codex config 在项目级别设置不同的认证方式。
首次验证：确保一切就绪
装完别急着关终端，跑两个验证确认正常：
验证一：版本检查
codex --version
验证二：基础交互
在你的一个项目目录下启动 Codex：
cd ~/your-project
codex
输入第一个指令：
请列出当前目录下有哪些文件和文件夹，按修改时间排序。
Codex 应该能正确列出文件。这表明：Node 环境正常、Codex 安装正确、认证通过、文件访问权限正常。
**如果它说”无法访问当前目录”**：检查 pwd 确认路径、检查目录权限、确认项目在 WSL 文件系统内（Windows 用户）。
常见安装问题速查
Q：npm install 时报 node-gyp 编译失败？
安装 C++ 编译工具：Ubuntu 用 sudo apt install build-essential python3，macOS 用 xcode-select --install。装完后重新 npm install。
Q：codex –version 输出正常但 codex 启动后认证失败？
检查你用的是哪种认证方式。OAuth 需要浏览器支持，无图形界面用 API Key。API Key 方式确认环境变量或 config 里 Key 是有效的、在 platform.openai.com 没有过期。
Q：Windows 上 WSL2 已装，但 codex 频繁超时？
检查项目路径——如果在 /mnt/c/ 下，挪到 /home/用户名/ 下。WSL2 访问 Windows 文件系统 I/O 慢是最大的超时根因。
Q：提示”Codex requires Node.js >= 22”？
你的 Node.js 版本低于 22。用 nvm install 22 升级，然后重新 npm install -g @openai/codex。
总结
三条命令搞定：
# 前置
nvm install 22
# 安装
npm install -g @openai/codex
# 验证
codex --version
Windows 用户多一步 WSL2 环境准备，安装命令相同。
装好后，下一篇带你深入 Codex 的三种审批模式——理解 read-only、auto-edit、full-auto 的区别和适用场景，这是用好 Codex 的关键。
如果这篇安装指南帮你顺利装好了 Codex，欢迎分享给也在装机器的朋友。你用哪种方式装的？有没有遇到什么奇怪的问题？评论区聊聊~
