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

前两篇讲清楚了 Codex 是什么、和 Claude Code / Cursor 怎么选。这篇直接装机------macOS、Linux 原生安装 + Windows WSL2 全流程，三种安装方式全覆盖，一个步骤不省。

前置依赖：Node.js 22+

Codex CLI 对 Node.js 的版本要求比 Claude Code 更严格------需要 Node.js 22 或更高版本。装之前先确认：

bash 复制代码

node -v

如果版本低于 22，用 nvm 升级：

bash 复制代码

# 安装 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 全局安装（推荐）

bash 复制代码

npm install -g @openai/codex

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

bash 复制代码

codex --version

输出类似 codex x.x.x 表示成功。

方式二：Homebrew（仅 macOS）

bash 复制代码

brew install openai/codex/codex

如果你已经是 Homebrew 用户且习惯用它管理 CLI 工具，这种方式更统一。Homebrew 会自动处理 Node.js 依赖。

方式三：独立二进制文件

从 GitHub Releases 页面下载对应系统的二进制文件，放到 PATH 路径下即可。不需要安装 Node.js，适合只想用 Codex、不想装 Node 环境的用户。macOS 和 Linux 都能用。Windows 用户需要走 WSL2 + Linux 二进制。

macOS 安装

npm 方式最快：

bash 复制代码

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 安装

bash 复制代码

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（管理员）：

bash 复制代码

# 安装 WSL
wsl --install

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

重启电脑后进入 Ubuntu 终端。

第二步：在 WSL 中装 Node.js 22+

bash 复制代码

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

第三步：安装 Codex

bash 复制代码

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，通过环境变量或配置文件使用：

bash 复制代码

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 在项目级别设置不同的认证方式。

首次验证：确保一切就绪

装完别急着关终端，跑两个验证确认正常：

验证一：版本检查

bash 复制代码

codex --version

验证二：基础交互

在你的一个项目目录下启动 Codex：

bash 复制代码

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。

总结

三条命令搞定：

bash 复制代码

# 前置
nvm install 22

# 安装
npm install -g @openai/codex

# 验证
codex --version

Windows 用户多一步 WSL2 环境准备，安装命令相同。

装好后，下一篇带你深入 Codex 的三种审批模式------理解 read-only、auto-edit、full-auto 的区别和适用场景，这是用好 Codex 的关键。

如果这篇安装指南帮你顺利装好了 Codex，欢迎分享给也在装机器的朋友。你用哪种方式装的？有没有遇到什么奇怪的问题？评论区聊聊~