3. 安装 Codex CLI

本节目标：把 Codex CLI 装到你机器上，学会三种安装方式、验证安装是否成功、知道怎么升级。

装之前的系统要求

别急着敲命令，先确认你的环境能不能跑。

Codex CLI 的系统要求：

操作系统：macOS、Windows、Linux 三大平台全支持
Windows 版本：推荐 Windows 11，Windows 10 需要 1809 或更新
Linux 沙箱：需要先装 bubblewrap，沙箱才正常工作
网络：能稳定访问 OpenAI 的服务器（chatgpt.com 等域名）

Warning

国内网络访问 chatgpt.com 等域名多数情况下需要代理。装的时候、登录的时候、平时跑任务的时候都得挂着，否则极易卡在「下载超时」上。这是国内用户踩坑的第一大来源。

三种安装方式

Codex CLI 有三种安装方式，先给结论：所有平台都优先用官方独立安装脚本。它不依赖 Node.js，下个独立二进制就能跑，最干净。

安装方式	命令	需要前置	建议
官方脚本	`curl ... \| sh`（Win 用 `irm`）	无	首选，独立二进制最干净
Homebrew	`brew install --cask codex`	Homebrew	已重度用 brew 管软件的人
npm	`npm install -g @openai/codex`	Node.js	习惯 npm 全局装工具的人

方式一：官方独立安装脚本（推荐）

官方脚本就像应用商店的「一键安装」—点一下，自己下载、自己放到位，不挖你系统其它东西。

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Note

Windows 那条命令里，-ExecutionPolicy ByPass 是临时放行一次脚本执行，不会永久改系统策略。irm（Invoke-RestMethod）拉下脚本，iex（Invoke-Expression）执行它。看到 irm is not recognized 说明你跑在 CMD 里了，去开一个 PowerShell 窗口。

如果是写自动化脚本、CI 里无人值守安装，加一个环境变量跳过交互提示：

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

# Windows
$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

方式二：Homebrew（macOS）

已经用 Homebrew 管软件的 Mac 用户，一行命令搞定：

brew install --cask codex

注意是 --cask 不是普通 formula，别漏掉。Homebrew 的更新比官方晚一两天，因为需要 Cask 维护团队审核；好处是版本经过一轮检验，对不爱追最新版的人反而稳。

方式三：npm（任意平台）

习惯用 npm 全局装工具的人，先确保装了 Node.js，然后：

npm install -g @openai/codex

Warning

npm 那条要不要加 sudo，看你的 Node 环境。很多老教程直接写 sudo npm install -g，但 sudo 全局装 npm 包是出了名地容易留下权限烂摊子。建议用 nvm / Volta 把 Node 装在用户目录下，全程不碰 sudo。真撞上权限报错，不如直接换官方脚本那条路。

验证安装

CLI 装完别急着用，花十秒确认一下。打开一个新终端窗口，敲：

codex --version

预期输出是一行版本号：

codex-cli 0.145.0

看到版本号就说明装成功了。

Tip

如果报 command not found: codex（Windows 上是 'codex' is not recognized），先别重装。大概率是 PATH 没配好—安装目录没进系统搜索路径。解决方法见下方常见问题。

升级到最新版

Codex 更新比较频繁，建议定期升级。升级方式和安装方式一致：

# 官方脚本方式：重新跑一遍安装脚本即可升级
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Homebrew 方式
brew upgrade --cask codex

# npm 方式
npm install -g @openai/codex@latest

你也可以在 config.toml 里设置启动时检查更新：

check_for_update_on_startup = true

Note

具体的版本检查参数以 codex --help 输出为准。这块官方在持续调整，别迷信老教程里写死的命令。

Windows 用户的特殊说明

Windows 是 Codex 三平台里讲究最多的一个。官方给了三种实际跑法：

跑法	需要什么	什么时候用
原生 + elevated 沙箱	管理员批准的沙箱配置	默认首选，性能最好、安全性最高
原生 + unelevated 沙箱	无需管理员级配置	公司策略卡住 elevated 时的退路
WSL2	启用 WSL2	需要 Linux 工具链，或仓库已在 WSL2

几条硬提醒：

Windows 版本：推荐 Windows 11，Win10 需要 1809 或更新
WSL1 已经不支持了：从 Codex 0.115 起 Linux 沙箱换成了 bubblewrap，WSL1 在 0.114 之后就被砍了，要用就上 WSL2
走 WSL2 的话，先在管理员 PowerShell 里装好子系统，再进 WSL shell 跑安装脚本

wsl --install
wsl

进到 WSL 之后：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Warning

WSL 性能坑：别把代码仓库放在 /mnt/c/... 这种 Windows 挂载路径下，I/O 会明显慢。放在 Linux 主目录（如 ~/code/my-app）下最快。

常见安装问题速查

报错 / 现象	真正的原因	怎么修
`command not found: codex`	安装目录没进 PATH	把安装目录加进 PATH
`'codex' is not recognized`（Windows）	PATH 没配 / 没重启终端	配好 PATH 后重启终端
`irm is not recognized`	在 CMD 里跑了 PowerShell 命令	打开 PowerShell 再跑
下载脚本卡住 / 超时	国内网络没走代理	挂上代理重试，或换 Homebrew
Windows 报错 `1385`	Windows 策略不给沙箱用户登录权限	找 IT；急用先切 `unelevated` 沙箱
卸载后还能跑	装了好几个 codex 在打架	`which -a codex` 揪出来删多余的

最常见问题：command not found

跑 codex 说找不到命令，不是没装上，是装好的目录没进系统搜索路径（PATH）。

PATH 就是系统的「门牌号清单」。程序装好好比房子盖好了，但系统只会去清单上登记过的地址挨个找。codex 的房子盖好了，地址却没登记进清单，自然喊它不应。

修法（macOS 默认是 Zsh）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux 大多默认 Bash，把 ~/.zshrc 换成 ~/.bashrc。Windows 则把对应安装目录加进用户 PATH 环境变量，然后重启终端。

揪出打架的多个安装

如果先 npm 装过、又官方脚本装一遍，可能同时存在好几个 codex，版本对不上、行为诡异。先看看 PATH 上有几个：

which -a codex

列出来不止一个，只留你想用的那个，其余删掉。比如卸掉 npm 全局安装：

npm uninstall -g @openai/codex

小结

这一章把 Codex CLI 的安装讲透了：

三种安装方式：官方独立脚本首选（不依赖 Node.js），Homebrew 和 npm 是备选
验证安装：codex --version 出版本号就成功
升级：重新跑安装脚本，或 brew upgrade、npm install -g @latest
Windows 用户：首选原生 + elevated 沙箱，被策略卡住退到 unelevated，要 Linux 环境才上 WSL2
报错先查表对因：找不到命令查 PATH，行为诡异查多重安装

装好后它还是个「不认识你」的空壳，下一章讲怎么登录绑上账号。