安装 Codex CLI，最重要的不是把一条命令粘进终端，而是三件事：确认命令来自官方，安装后系统能找到 codex，并且版本和帮助信息都能正常输出。只要这三项都通过，后面的登录、配置 API Key 和使用就都有了可靠的起点。
这篇教程按操作系统拆开写，每个系统都给出安装命令、验证方法和常见问题。所有安装命令都来自 OpenAI Codex CLI 官方文档和 AI Code With 的 Codex 终端文档。如果你看到这里的命令和官方页面不一致，请以官方页面为准，因为安装方式会随着版本更新调整。
还没下载安装包？官方下载地址见《Codex 下载》。装好之后怎么用，看《Codex 怎么用》。
安装前先选一条路线
OpenAI 目前提供四种安装入口：macOS/Linux 独立安装脚本、Windows 独立安装脚本、npm 和 Homebrew。它们装出来的都是同一个 Codex CLI，区别只在于依赖什么、以后怎么升级。
| 安装方式 | 适合谁 | 需要的前置条件 | 升级方式 |
|---|---|---|---|
| 官方安装脚本（macOS/Linux） | 不想装 Node.js 的用户 | curl 和能访问官方地址的网络 | 重新运行同一条安装命令 |
| 官方安装脚本（Windows） | Windows 用户首选 | PowerShell | 重新运行同一条安装命令 |
| npm | 已经在用 Node.js 的开发者 | Node.js 18+ 和 npm | npm install -g @openai/codex |
| Homebrew | macOS 上习惯用 brew 的用户 | Homebrew | brew upgrade --cask codex |
如果你在国内网络环境下，官方安装脚本有时下载不稳定，这时 npm 加国内镜像通常更顺。AI Code With 文档里给出的就是 npm 路线，要求 Node.js 版本为 18 及以上。
macOS 安装步骤
方式一：官方安装脚本
打开「终端」，执行官方给出的独立安装命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
以后需要升级时，再运行一次同一条命令即可。
方式二：Homebrew
如果你已经装了 Homebrew，可以用官方提供的 cask 安装：
brew install --cask codex
升级命令是：
brew upgrade --cask codex
方式三：npm
先确认 Node.js 已经安装，并且版本在 18 以上：
node --version
npm --version
如果还没有 Node.js，可以按 AI Code With 文档的做法，用 Homebrew 安装：
brew install node
然后安装 Codex CLI。国内用户可以加上镜像参数：
npm install -g @openai/codex
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
两条命令选一条执行就行，第二条走的是国内镜像。
macOS 验证安装
安装完成后，重新打开一个终端窗口，然后依次检查：
command -v codex
codex --version
codex --help
第一条能输出 codex 的路径，第二条能输出版本号，第三条能打印帮助信息，就说明安装成功了。成功的标准不是"安装器没有报错"，而是这三条都能正常输出。
Windows 安装步骤
方式一：官方 PowerShell 安装脚本
OpenAI 官方文档建议从新开的 PowerShell 窗口里执行下面这条命令：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
不要长期照搬旧博客里的 PowerShell 命令。官方安装入口会更新，执行前最好打开官方页面确认一下当前命令。
方式二：npm
先去 Node.js 官网下载并安装 LTS 版本，然后按 Win + R，输入 powershell 打开 PowerShell，检查版本：
node --version
npm --version
确认 Node.js 版本在 18 以上之后，安装 Codex CLI：
npm install -g @openai/codex
国内用户可以改用镜像：
npm install -g @openai/codex --registry=https://npmreg.proxy.ustclug.org
如果 PowerShell 提示"在此系统上禁止运行脚本"，AI Code With 文档给出的处理方式是：用管理员权限打开 PowerShell，执行 Set-ExecutionPolicy Unrestricted。这一步会放宽当前系统的脚本执行策略，请确认你理解它的影响后再操作。
Windows 验证安装
关闭当前 PowerShell，重新打开一个，然后检查：
Get-Command codex
codex --version
codex --help
如果 Get-Command codex 找不到命令，先不要重装，往下看"安装完却找不到 codex"一节。
Linux 安装步骤
方式一：官方安装脚本
Linux 和 macOS 用的是同一条独立安装命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
方式二：npm
如果系统里还没有 Node.js，AI Code With 文档给出的 Debian/Ubuntu 安装方式是（需要 root 权限）：
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs
确认版本后安装 Codex CLI：
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
其他发行版请用自己的包管理器安装 Node.js LTS，然后执行同样的 npm 命令。
Linux 验证安装
command -v codex
codex --version
codex --help
如果你是在没有图形界面的服务器上安装，下一步登录时浏览器流程可能走不通，这种情况的处理方法写在后面的常见问题里。
为什么每次都要重新打开终端
很多"装好了却找不到命令"的问题，其实只是终端没有重新打开。终端在启动时会读取一次环境变量，安装程序往 PATH 里加的新目录，只对之后新开的终端窗口生效。已经开着的窗口还在用旧的 PATH，自然找不到刚装好的 codex。
所以本文每个系统的验证步骤，都要求先关掉当前窗口、重新打开一个再检查。如果你在 VS Code 等编辑器的内置终端里安装，同样需要关闭整个编辑器再打开，只新建一个终端标签页有时不够。
另外，Windows 上如果你一会儿用 PowerShell、一会儿用命令提示符或 Git Bash，它们读取的环境变量可能不一样。建议安装和使用都固定在 PowerShell 里，排查问题时会简单很多。
安装完却找不到 codex
这是安装阶段最常见的问题。原因通常不是"没装上"，而是系统 PATH 里没有 Codex 所在的目录，或者当前终端还在用旧的环境变量。
先排查 PATH，macOS / Linux：
command -v codex
printf '%s\n' "$PATH"
Windows：
Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'
处理顺序建议是：先重新打开终端；还不行，再确认可执行文件实际装在哪个目录（npm 路线可以用 npm prefix -g 查看全局安装位置）；最后只把这一个目录加进 PATH。不要把一个来源不明的目录整个加入系统 PATH。
安装后会多出哪些文件
装好并登录之后，Codex 会在你的用户目录下使用一个配置目录，默认是 ~/.codex（可以通过环境变量 CODEX_HOME 改到别的位置）。新手最需要知道的是两个文件：
config.toml：Codex 的配置文件，模型、Provider、权限等设置都写在这里；auth.json：登录缓存。官方文档说明，Codex 会把登录信息缓存在这个明文文件里，或者存进系统的凭据库。
如果你更希望把凭据放进系统凭据库，而不是明文文件，官方提供了 cli_auth_credentials_store 这个配置项，可选值有 file、keyring、auto 和 ephemeral：file 存在 auth.json 里；keyring 存进系统凭据库，凭据库不可用时会报错；auto 优先用凭据库，不可用时退回 auth.json；ephemeral 只在当前进程的内存里保存。个人电脑上用默认设置就够了；如果是多人共用的机器，建议考虑 keyring。
不管用哪种方式，都要记住：auth.json 里有访问令牌，等同于密码。不要把它提交到 Git 仓库，不要贴进工单，也不要发到群里。分享配置给同事时，只发 config.toml，并且先确认里面没有直接写入密钥。
公司网络和代理环境下安装
很多公司网络会经过 TLS 代理，或者使用私有根证书。这种环境下，安装脚本能下载成功，但第一次登录时可能报证书错误。官方给出的做法是：在登录之前，把环境变量 CODEX_CA_CERTIFICATE 设置为公司提供的 PEM 证书文件路径，然后再运行登录命令：
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
如果没有设置 CODEX_CA_CERTIFICATE，Codex 会退回使用 SSL_CERT_FILE。这个证书设置同时作用于登录、普通 HTTPS 请求和 WebSocket 连接，所以设置一次就能覆盖后续的调用。证书文件请向公司 IT 部门索取，不要从网上随便下载。
另外，如果你需要通过代理才能访问外网，npm 路线可以先配置 npm 自己的代理，或者直接改用国内镜像，这通常比折腾系统代理更省事。
换一种安装方式之前，先卸载旧的
如果你一开始用 npm 装了，后来又想换成官方脚本或 Homebrew，最好先把旧的卸载掉，否则 PATH 里可能先找到旧版本，出现"明明升级了，版本号却没变"的情况。
npm 安装的，用 npm 卸载：
npm uninstall -g @openai/codex
Homebrew 安装的，用 Homebrew 卸载：
brew uninstall --cask codex
卸载后重新打开终端，用 command -v codex（Windows 用 Get-Command codex）确认已经找不到旧命令，再用新的方式安装。卸载 CLI 不会自动删除 ~/.codex 目录，你的配置和登录缓存还在，重新安装后可以直接继续使用。
第一次启动和登录
进入一个测试项目，再启动 Codex：
cd /你的/测试项目
codex
第一次运行时，官方文档说明你可以选择 Sign in with ChatGPT 或其他可用的登录方式。常见的两种是：
- ChatGPT 账号登录：运行
codex login，在弹出的浏览器里完成登录，用的是订阅额度。 - API Key 登录：官方给出的写法是
printenv OPENAI_API_KEY | codex login --with-api-key，按 API 标准价格计费。
登录后可以用 codex login status 查看当前使用的认证方式。登录信息会缓存在本地的 ~/.codex/auth.json 或系统凭据库里，这个文件相当于密码，不要提交到 Git，也不要发给别人。
用 AICodeWith 的 API Key 接入 Codex
装好 Codex 后，想用 AICodeWith 的 Key 调模型，按接入教程配置即可，本文不重复配置步骤：
常见报错对照表
| 报错或现象 | 常见原因 | 解决方法 |
|---|---|---|
| command not found: codex / Get-Command 找不到 | 安装目录不在 PATH 里，或终端没有重新打开 | 重开终端；用 npm prefix -g 找到安装位置，只把这一个目录加进 PATH |
| npm: command not found | 没装 Node.js，或 Node.js 没加入 PATH | 先装 Node.js LTS，确认 node --version 和 npm --version 都能输出 |
| npm 安装后启动报错，Node 版本过低 | AI Code With 文档要求 Node.js 18+ | 升级 Node.js 到 LTS 版本后重装 |
| PowerShell 提示"在此系统上禁止运行脚本" | Windows 脚本执行策略限制 | 管理员 PowerShell 执行 Set-ExecutionPolicy Unrestricted（了解影响后再改） |
| npm 下载很慢或超时 | 访问 npm 官方源不稳定 | 加上 --registry=https://registry.npmmirror.com/ 等国内镜像 |
| 服务器上 codex login 打不开浏览器 | 无图形界面，或本地回调端口 localhost:1455 被拦截 | 用 codex login --device-auth 设备码登录，或用 SSH 转发 1455 端口 |
| 公司网络下登录报证书错误 | 企业 TLS 代理或私有根证书 | 登录前设置 CODEX_CA_CERTIFICATE 指向 PEM 证书文件 |
| 首次启动提示 "this folder is not version controlled" | 当前目录不是 Git 仓库，Codex 在确认权限 | 在测试目录可以按提示选择；正式项目建议先 git init 再用 |
如果装好之后调用时遇到 401 或 429，那就不是安装问题了，分别看《Codex 401 Unauthorized 怎么解决》和《Codex 429 Too Many Requests 怎么解决》。
常见问题
Codex CLI 安装需要 Node.js 吗？
不一定。官方独立安装脚本（macOS/Linux 的 install.sh、Windows 的 install.ps1）不依赖 Node.js；只有走 npm 路线时才需要，AI Code With 文档要求 Node.js 18 及以上。
Windows 上应该用哪种方式安装？
优先用官方 PowerShell 安装脚本。如果你已经在用 Node.js，或者官方脚本下载不稳定，可以改用 npm 加国内镜像。两种方式装出来的是同一个 Codex CLI。
怎么升级 Codex CLI？
用什么方式装的，就用什么方式升级：安装脚本重新运行一次；npm 再执行一次 npm install -g @openai/codex；Homebrew 用 brew upgrade --cask codex。升级后用 codex --version 确认版本号变了。
安装成功了，但启动后要求登录，该选哪个？
有 ChatGPT 订阅就选 ChatGPT 登录，用的是订阅额度；想按用量付费或在 CI 里用，就用 API Key。如果你想用 AI Code With 的 Key，先注册账号，再按 Codex 配置文档写入 Provider 配置。
没有图形界面的 Linux 服务器怎么登录？
官方推荐设备码登录：运行 codex login --device-auth，在另一台有浏览器的设备上打开链接并输入一次性代码。也可以在本机登录后，把 ~/.codex/auth.json 复制到服务器上的同一位置。
可以同时装多个版本吗？
不建议。npm、Homebrew 和安装脚本混装，很容易出现 PATH 里先找到旧版本的情况。选定一种方式，另一种卸载掉，再用 command -v codex 确认实际调用的是哪一个。
下一步
装好之后，建议按这个顺序继续：
- 《Codex 怎么用：从启动到完成第一个可验收任务》：跑通第一个小任务；
- 《Codex API Key 怎么配置》：接入 API Key 和第三方 Provider；
- 《Codex config.toml 配置指南》：弄清配置文件位置和优先级。
