前置依赖：Node.js 22+

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

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

三种安装方式

Codex CLI 提供三种安装途径，按推荐优先级排列：

方式一：npm 全局安装（推荐）

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

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

方式二：Homebrew（仅 macOS）

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

方式三：独立二进制文件

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

macOS 安装

npm 方式最快：

首次运行时 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 安装

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

重启电脑后进入 Ubuntu 终端。

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

第三步：安装 Codex

第四步：关键——项目路径

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

API Key 方式适合：无图形界面的服务器环境、需要按量精确控制成本的团队、ChatGPT 订阅之外的独立使用场景。

两种方式可以共存：如果你既有 ChatGPT 订阅又想在某些任务上用 API Key（比如工作项目和个人项目分开计费），Codex 支持通过 codex config 在项目级别设置不同的认证方式。

首次验证：确保一切就绪

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

验证一：版本检查

验证二：基础交互

在你的一个项目目录下启动 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。

总结

三条命令搞定：

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

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

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