Codex CLI 安装全攻略：macOS / Linux / Windows（WSL2）三端实战指南

前两篇聊清楚了 Codex 到底是什么、跟 Claude Code / Cursor 怎么选。这篇直接上干货——macOS、Linux 原生安装 + Windows WSL2 全流程，三种安装方式一步不落，挨个拆解清楚。

前置依赖：Node.js 22+

Codex CLI 对 Node.js 版本的要求比 Claude Code 更严——必须 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 install -g @openai/codex

一条命令，跨平台通用，后续更新也方便。装完验证一下：

codex --version

输出类似 codex x.x.x 就说明成了。

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 用户直接打开浏览器登录 ChatGPT 账号就行——如果你有 ChatGPT Plus 订阅，Codex 的基本额度已经包含在订阅里了，不用额外付费。OAuth 认证完，Codex 会自动保存凭证，后续启动不用再反复登录。

：如果终端提示 codex: command not found，但 npm list -g @openai/codex 显示已经装上了——这通常是 PATH 没包含 npm 全局 bin 目录。确认一下 nvm 的 PATH 配置是否正确，问题就解决了。

Linux 安装

npm install -g @openai/codex
codex --version

：

• 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 操作文件时延迟会高到让人崩溃。

PowerShell（管理员模式）：

# 安装 WSL
wsl --install
# 如果已经装了 WSL1，升级到 WSL2
wsl --set-default-version 2

重启电脑后进入 Ubuntu 终端。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
node -v  # 确认 >= 22

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 内的代码，体验几乎无缝。

首次运行 codex，WSL 会自动调用 Windows 端浏览器完成 OAuth 登录。如果浏览器没自动弹出来，终端会显示一个手动链接，复制到浏览器打开完成授权就行。

账号认证：ChatGPT 登录 vs API Key

Codex 支持两种认证方式：

：如果你是 ChatGPT Plus/Pro 用户，首次运行 codex 时浏览器弹窗授权。好处是额度已经包含在 ChatGPT 订阅里，不用额外掏钱。而且认证一次后凭证自动保存，后续启动无缝衔接。

：在 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 用户特别留意）。

常见安装问题速查

安装 C++ 编译工具：Ubuntu 用 sudo apt install build-essential python3，macOS 用 xcode-select --install。装完重新 npm install。

检查你用的是哪种认证方式。OAuth 需要浏览器支持，无图形界面请用 API Key。API Key 方式确认环境变量或 config 里的 Key 是有效的、在 platform.openai.com 没有过期。

检查项目路径——如果在 /mnt/c/ 下，挪到 /home/用户名/ 下。WSL2 访问 Windows 文件系统 I/O 慢是最大的超时根因，没有之一。

你的 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 的关键所在。