Codex 安装教程：Mac、Windows、Linux 安装 Codex CLI，验证、登录、更新

这篇教程解决一个问题：把 Codex 的命令行版（Codex CLI）装到自己的电脑上，确认它装好了，并完成第一次登录。

先说结论：

Mac 和 Linux 用官方安装脚本，Windows 用官方的 PowerShell 命令。 已经装了 Node.js 的，用 npm 装也一样。
装完跑两条命令：codex --version 看版本，codex doctor 做一次体检。 体检会逐项告诉你安装、配置、登录和网络哪里不对，比自己猜快得多。
登录有两种方式。 用 ChatGPT 账号登录，用的是 Plus、Pro 等套餐的额度；用 API key 登录，按 API 价格计费。在国内接中转站的，不用登录，见Codex 接入中转站。

Codex 除了命令行，还有编辑器扩展和桌面应用（现在并进了 ChatGPT 桌面应用）。这篇只讲命令行，编辑器扩展在文末简单说。

实测环境
日期	2026-11-01
系统	Ubuntu 24.04（64 位），本站的测试服务器，普通用户，不用 sudo
装法	npm（Node.js 22.23.2、npm 10.9.8），装到用户自己的目录
版本	codex-cli 0.166.0（当天的最新版）
跑过的	安装、`codex --version`、`codex --help`、`codex login status`、`codex doctor`、`codex update --help`；故意写错配置看 `codex doctor` 怎么报
没有实测的	官方安装脚本和 Homebrew、Windows 和 Mac 上的安装、用 ChatGPT 账号登录；服务器不在国内，国内网络下的下载速度也没有测

官方安装脚本没有在服务器上运行，下文写它装到哪里、怎么改 PATH，是读脚本内容得到的。

先选一种装法

装法	适合谁	命令
官方安装脚本	Mac、Linux，官方推荐	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`
PowerShell	Windows	`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"`
npm	已经装了 Node.js，任何系统	`npm install -g @openai/codex`
Homebrew	Mac，习惯用 brew 管软件的	`brew install --cask codex`

四种装法装上的是同一个程序，任选一种，不要混着装，否则电脑上会有两个 codex，更新了一个、运行的是另一个。

Mac 和 Linux：官方安装脚本

打开终端，运行：

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

这个脚本做三件事：

下载对应系统的程序。默认从 releases.openai.com 下载，下不了时自动改从 GitHub Releases 下载。
把 codex 放到 ~/.local/bin。想换目录，运行前设环境变量 CODEX_INSTALL_DIR。
~/.local/bin 不在 PATH 里的话，把一行 export PATH=... 写进你的 shell 配置文件（~/.zshrc、~/.bashrc 等）。

装完重新打开终端，让 PATH 生效。

想强制从 GitHub 下载（比如 releases.openai.com 连不上），官方给的写法是：

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

Windows

在 PowerShell 里运行：

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

同样想强制从 GitHub 下载的话：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

Windows 上有两条路：

直接在 Windows 里用。 Codex 有原生的 Windows 沙箱，用来限制它执行的命令能读写哪些文件、能不能联网。新版默认优先用不需要管理员授权的那一种（官方叫 MXC），设备不支持时退回旧的实现。
在 WSL2 里用。 你的仓库和开发工具本来就在 WSL 里的，选这条。在 WSL 的终端里按上一节 Linux 的方法装。注意：WSL1 从 0.115 版起不再支持，要用 WSL2；仓库放在 Linux 的家目录（例如 ~/code/）下，不要放在 /mnt/c/ 下，后者慢得多。

用 npm 装

已经装了 Node.js 的，一条命令：

npm install -g @openai/codex

npm 的全局目录在系统目录、要 sudo 才能写的话，可以装到自己的目录下，不用 sudo。本站实测用的就是这种写法：

npm install -g --prefix ~/.npm-global @openai/codex
export PATH="$HOME/.npm-global/bin:$PATH"

第二行加进 ~/.zshrc 或 ~/.bashrc 才能长期生效。实测这一步用了 20 秒，npm 的输出是：

added 2 packages in 20s

npm 装的也是官方编译好的程序，不是 JavaScript 版本，后面的 codex doctor 会显示它实际的位置。

装完先验证

第一步，看版本：

codex --version

实测输出：

codex-cli 0.166.0

提示 command not found 的，是 PATH 没设好，见文末的常见问题。

第二步，做一次体检：

codex doctor

它会逐项检查安装方式、磁盘、配置文件、登录、网络、沙箱等。刚装好、还没登录时，开头的摘要是这样的（实测，版本 0.166.0）：

Codex Doctor v0.166.0 · linux-x86_64

Notes
   ✗ auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   ⚠ websocket    Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.

标记	意思	要不要管
`✗ auth`	还没有登录凭据	正常，下一节登录
`⚠ websocket`	连 OpenAI 的 WebSocket 没连上，会退回普通的 HTTPS	能用 HTTPS 就不影响使用；网络环境特殊的，按提示查代理和防火墙

后面的详细部分里，install 一项应该是 consistent（安装是完整的），runtime 一项写着你是用什么装的，用 npm 装的会写 npm。体检显示 ✓ install consistent，就说明装好了。

第一次登录

方式	命令	用的是什么额度
ChatGPT 账号	`codex login`，在弹出的浏览器里登录	ChatGPT 套餐（Plus、Pro、Business、Edu、Enterprise）的额度
API key	`printenv OPENAI_API_KEY \| codex login --with-api-key`	按 OpenAI API 的标准价格计费

直接运行 codex，没有登录时也会引导你选登录方式。

用 API key 时，官方的写法是把 key 从标准输入传给 codex login，不要把 key 直接写在命令行里，免得留在 shell 的历史记录里。另外，用 API key 时有些依赖 ChatGPT 账号的功能用不了，比如 Codex Cloud（云端任务）只支持 ChatGPT 账号登录。

查当前的登录状态：

codex login status

还没登录时，实测输出是 Not logged in，退出码是 1，可以在脚本里拿来判断。退出登录是 codex logout。

登录信息存在哪： 默认在 ~/.codex/auth.json，这是一个明文文件，里面有访问令牌。官方提醒把它当密码看待：不要提交进仓库，不要贴到工单和聊天里。想改存到系统的钥匙串，在 ~/.codex/config.toml 里写：

cli_auth_credentials_store = "keyring"

在国内接中转站的，跳过这一节，按Codex 接入中转站写好配置文件就行。实测接好之后，codex doctor 的登录一项会变成 ✓ auth auth is provided by the active model provider，意思是登录由中转站的配置提供，不需要 codex login。

跑起来

进入一个项目的目录，运行：

cd 你的项目
codex

启动画面会显示当前的模型和目录，不改配置的话默认模型是 GPT-6.1 Sol。官方建议第一句话先让它介绍一下这个项目，例如“介绍一下这个项目的结构”。动手改代码之前，先用 Git 提交一次，改坏了可以退回。

接下来怎么用，见Codex 使用教程。

更新

Codex 更新很频繁：0.158 是 9 月 28 日发布的，到 10 月 29 日已经是 0.166。更新的办法和装法对应：

装法	更新命令
官方安装脚本	再运行一次安装命令
npm	`npm install -g @openai/codex@latest`
Homebrew	`brew upgrade --cask codex`
任意	`codex update`

codex update 是 0.166 里自带的子命令，作用是“把 Codex 更新到最新版”。

升级前留意一项旧设置： 官方已经不再支持 approval_policy = "untrusted"，配置里还留着这一行的话，Codex 可能启动不了。升级后起不来，先检查 ~/.codex/config.toml 里有没有它，删掉或者改成 "on-request"。

在编辑器里用

VS Code、Cursor、Windsurf 装 Codex 扩展，Xcode 和 JetBrains 系列的 IDE 有自带的集成。装好后点侧边栏的 Codex 图标；看不到的话，在命令面板里运行 Codex: Open Codex Sidebar。

编辑器扩展和命令行共用同一份登录：在一边退出登录，另一边下次也要重新登录。

常见问题

现象	原因和办法
`codex: command not found`	安装目录不在 PATH 里。官方脚本装在 `~/.local/bin`，npm 装在 `npm config get prefix` 显示的目录下的 `bin`。把对应目录加进 PATH，重开终端
装完版本号还是旧的	电脑上有两个 `codex`。用 `which -a codex`（Windows 用 `where codex`）列出来，删掉不用的那个
`codex doctor` 显示 `✗ config config could not be loaded`	配置文件写错了。实测把供应商的 id 写成保留的 `openai` 就会这样，详细部分写着 `error invalid data`。按提示改好再跑一遍 `codex doctor`
`codex doctor` 显示 `⚠ websocket`	WebSocket 连不上，Codex 会退回普通的 HTTPS，一般不影响使用
WSL 里用不了	确认是 WSL2（`wsl -l -v` 看版本），WSL1 从 0.115 起不再支持
下载很慢或者失败	官方脚本下不了会自动改从 GitHub 下载，也可以用上面的变量强制改；用 npm 装的，可以用你平常用的 npm 镜像。国内网络下的情况本站没有实测
升级后起不来	检查配置里有没有已经废弃的 `approval_policy = "untrusted"`

下一步

Codex 使用教程：第一次上手：权限和沙箱、常用命令、让它改代码和审代码。
Codex 接入中转站：在国内不用 ChatGPT 账号也能用。
Codex 该选哪个模型：GPT-6.1 Sol、GPT-6 Astra、Luna 怎么选。