#1 易错点：不要运行 npm i -g codex——那是一个 2012 年的无关老项目。正确命令是 npm install -g @openai/codex，必须带 @openai/ 命名空间。
安装前提：Node.js 18+
Codex CLI 基于 Node.js 运行，要求 Node.js 18 或更高版本（截至 2026）。先确认当前版本：
$ node -v
# 应该输出 v18.x.x 或更高，如 v22.4.0如果版本太低或未安装 Node，推荐用 nvm（Node 版本管理器）来安装，这样以后升降版本都方便，也能避免 npm 全局安装的权限问题：
# 安装 nvm
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重开终端后安装并使用 Node 22
$ nvm install 22
$ nvm use 22
$ node -v # v22.x.xWindows 用户可以从 nodejs.org 下载 LTS 安装包，或用 winget install OpenJS.NodeJS.LTS。
方法一：npm 全局安装（推荐）
最通用的方式，三个平台均适用：
$ npm install -g @openai/codex安装完成后验证：
$ codex --version
# 输出版本号即说明安装成功如果看到版本号（如 0.1.x），说明安装成功。下一步是运行 codex 并完成登录，见「验证与首次运行」。
方法二：官方安装脚本（macOS / Linux）
OpenAI 提供了一个官方一键脚本，适合不想手动管理 npm 全局包的用户。同一条命令也可用来升级：
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh脚本会自动检测平台并安装合适的版本。升级时重新运行同一条命令即可，无需额外参数。
方法三：Homebrew（macOS）
macOS 用户如果已经在用 Homebrew，可以用 brew 安装，并通过 brew upgrade 保持最新：
# 安装
$ brew install codex
# 升级
$ brew upgrade codexWindows 上安装
Codex CLI 在 Windows 上有两种使用方式（截至 2026）：
方式 A：PowerShell（原生 + Windows 沙盒）
在 PowerShell 中运行 npm install -g @openai/codex 安装后即可直接使用。Codex 会利用 Windows 沙盒来执行需要隔离的操作。
方式 B：WSL2（Linux 原生环境，问题最少）
在 WSL2 的 Linux 发行版里按 Linux 方式安装 Node 和 Codex，通常遇到的兼容性问题最少。如果你经常在 WSL2 里开发，推荐这种方式。
WSL2 里运行 Codex 需要额外配置代理（WSL2 不自动继承 Windows 的系统代理），详见 Reconnecting 排查中的 WSL2 章节。
验证与首次运行
安装后，运行以下命令验证并完成首次登录：
- 确认版本：
$ codex --version - 启动 Codex（首次会提示登录）：
$ codex # 首次运行会引导你登录 ChatGPT 账号或输入 OpenAI API Key - 根据提示选择登录方式：使用 ChatGPT 账号（需要 Plus / Pro / Business / Edu / Enterprise 订阅）或 OpenAI API Key（按用量计费）。CLI 本身免费开源。
登录成功后看到 ● connected 提示，就可以开始使用了。发一句简单的指令测试一下，例如：列出当前目录的文件。
升级与卸载
升级
# npm 方式
$ npm install -g @openai/codex@latest
# 官方脚本（重新运行即可升级）
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Homebrew
$ brew upgrade codex卸载
# npm 方式卸载
$ npm uninstall -g @openai/codex
# 可选：同时清掉配置与认证（会清除登录信息）
$ rm -rf ~/.codex常见安装报错
报错：装了之后运行没有反应 / 功能完全不对
原因：装的是不带命名空间的 codex（无关老项目），不是 @openai/codex。
# 先卸载错误的包
$ npm uninstall -g codex
# 安装正确的包
$ npm install -g @openai/codex报错：引擎版本不兼容 / syntax error
原因：Node.js 版本低于 18。用 node -v 确认版本，然后用 nvm 升级：
$ nvm install 22 && nvm use 22
$ npm install -g @openai/codex报错：npm EACCES permission denied
原因：npm 全局目录没有写入权限。不要用 sudo npm install（有安全风险且容易导致后续权限混乱）。最干净的解法是通过 nvm 管理 Node，nvm 管理的 npm 全局目录在用户家目录下，无需 sudo：
# 先安装 nvm（如未安装）
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重开终端，安装 Node
$ nvm install 22 && nvm use 22
# 此时 npm 全局安装不再需要 sudo
$ npm install -g @openai/codex国内 npm 安装超时 / 速度很慢
切换到国内镜像加速下载：
# 临时换成淘宝/npmmirror 镜像
$ npm config set registry https://registry.npmmirror.com
$ npm install -g @openai/codex
# 安装完后恢复官方源（可选）
$ npm config set registry https://registry.npmjs.org安装完成后，运行 codex 本身也需要代理才能连上 OpenAI——npm 镜像只解决了安装速度，不解决运行时的网络问题。代理配置见 国内使用与代理配置 和 Reconnecting 排查。
常见问题
包名到底是哪个，@openai/codex 还是 codex？
必须用 @openai/codex（带命名空间）。不加 @openai/ 直接 npm i -g codex 装的是一个 2012 年的无关老项目，运行后完全不是 Codex CLI。这是新手最常犯的 #1 错误。
必须用 Node 18 吗？旧版能装吗？
必须 Node.js 18 或更高版本（截至 2026）。可以用 node -v 查看当前版本；建议通过 nvm 管理 Node，方便随时切换。Node 16 及以下会报兼容性错误无法运行。
安装太慢怎么办（国内网络）？
临时换国内镜像：npm config set registry https://registry.npmmirror.com，安装完再用 npm config set registry https://registry.npmjs.org 恢复。注意安装后运行 codex 仍需代理才能连上 OpenAI，参见 国内使用指南。
装好运行就一直 Reconnecting？
这是网络问题，不是安装问题。Codex 需要连接 OpenAI，在没有代理的网络下会一直重连。配置 HTTPS_PROXY 指向本地代理即可解决，详见 Reconnecting 完整排查清单。