夜雨聆风
2025年4月，OpenAI开源了一款终端编程Agent——Codex CLI。不到两年，GitHub Star数突破7.7万。这不是一个聊天机器人。它能直接读你的代码、改你的文件、跑你的命令，像一个坐在你旁边的工程师。
但很多人在安装这一步就卡住了。包名写错装了无关的旧包、npm全局路径没配好导致命令找不到、Windows用户不知道该用WSL2还是原生PowerShell……这些问题，其实几分钟就能解决。
今天这篇文章，我把Codex CLI的安装过程从头到尾讲清楚。多平台、多方式、常见坑，一篇搞定。
一、先搞清楚：Codex CLI 是什么
OpenAI的产品线里叫"Codex"的东西有好几个，容易搞混。先做一个区分：
- Codex CLI
——终端编程Agent，开源，本地运行，本文的主角。 - Codex Web
——云端Agent，在 chatgpt.com/codex 上使用。 - Codex IDE 扩展
——VS Code / Cursor / Windsurf 的编辑器插件。 - Codex App
——桌面端图形界面应用。
Codex CLI 用 Rust 编写，Apache 2.0 协议开源，GitHub 仓库地址是 github.com/openai/codex。它的核心定位是：在你本地终端里运行的编程Agent，能读写文件、执行shell命令、理解代码上下文，然后直接动手干活。
和 ChatGPT 的本质区别在于：ChatGPT 是"对话"，Codex CLI 是"行动"。你跟它说"给这个项目的所有函数加上类型注解"，它不是告诉你怎么做——它直接就做了。
二、安装前的准备：先对齐系统要求
在动手安装之前，先确认你的机器满足以下条件：
一个关键提醒：如果你选择 npm 安装方式，Node.js 版本必须 22 以上。可以用 node -v 检查当前版本。版本不够的话，先升级 Node.js。
另外，强烈建议提前装好 Git。Codex 在 full-auto 模式下会自主修改代码，Git 是你的安全网——随时可以 diff 查看、checkout 回滚。没有 Git 的 Codex，就像没有保险绳的高空作业。
三、安装方式详解：选最适合你的那一条路
Codex CLI 提供了多种安装方式。下面逐一讲解，你可以根据自己的平台和偏好选择。
方式一：npm 全局安装（跨平台，最常用）
这是官方推荐的安装方式，macOS、Linux、Windows 均适用。一条命令搞定：
npm install -g @openai/codex注意：包名是 @openai/codex，带 @openai/ 作用域前缀。npm 上还有一个叫 codex 的包，那是2012年的一个文档生成工具，跟 OpenAI 没有任何关系。装错了会报莫名其妙的错误。
安装完成后验证：
codex --version看到版本号输出，说明安装成功。如果提示 command not found，别慌，后面"常见问题"部分有解决方案。
方式二：独立安装脚本（macOS / Linux，免 Node.js）
如果你不想装 Node.js，或者你的环境里没有 Node.js，可以用官方提供的独立安装脚本。它直接下载预编译的 Rust 二进制文件，零依赖：
curl -fsSL https://chatgpt.com/codex/install.sh | sh同一个命令也用于更新。以后想升级到最新版，再跑一遍这行命令就行。
方式三：Homebrew（macOS 用户首选）
macOS 用户如果已经用了 Homebrew 管理软件包，这是最省心的方式：
brew install --cask codex注意 --cask 参数不能省。它告诉 Homebrew 安装预编译的应用包，而不是从源码编译。不加 --cask 的 brew install codex 不是官方支持的路径。
后续更新通过 brew upgrade --cask codex 完成。
方式四：GitHub Releases 二进制直接下载
适用于所有平台，不需要 Node.js，不需要 Homebrew。直接从 GitHub 下载预编译二进制文件。
访问 github.com/openai/codex/releases/latest，根据你的平台选择对应的压缩包：
下载后解压并放到 PATH 中：
tar -xzf codex-aarch64-apple-darwin.tar.gz
mv codex-aarch64-apple-darwin /usr/local/bin/codex
chmod +x /usr/local/bin/codexLinux 的 musl 二进制是静态链接的，在任何 Linux 发行版上都能直接跑，不需要额外安装运行时依赖。
Windows 用户特别指南
Windows 用户有两条路可以走。
路线 A：原生 PowerShell + npm
在 PowerShell 中直接用 npm 安装：
npm install -g @openai/codex
codex --version如果遇到 "Missing optional dependency @openai/codex-win32-x64" 的错误，这是 Windows 平台特定子包解析问题。一个社区验证过的解决方案是在 PowerShell 中固定版本安装：
$v = npm view @openai/codex version
npm install -g "@openai/codex@$v" "@openai/codex-win32-x64@npm:@openai/codex@$v-win32-x64"也可以用 winget 安装（社区维护）：
winget install OpenAI.Codex路线 B：WSL2（推荐 Windows 用户使用）
如果你需要更强的沙箱隔离，或者你的项目本身就在 Linux 环境中跑，WSL2 是更好的选择。OpenAI 也官方推荐 Windows 用户通过 WSL2 使用 Codex CLI。
步骤如下：
# 1. 在 PowerShell（管理员）中安装 WSL2 + Ubuntu
wsl --install -d Ubuntu-24.04
# 2. 重启后进入 WSL2
wsl
# 3. 在 WSL2 中安装 Codex CLI
npm install -g @openai/codex
# 4. 验证
codex --version
# 5. 访问 Windows 磁盘上的项目
cd /mnt/d/projects/my-app
codex通过 /mnt/磁盘号/ 路径可以访问 Windows 文件系统，比如 /mnt/c/、/mnt/d/。体验和原生 Linux 一致。
一个重要提醒：不要从 PowerShell 直接运行 WSL2 里安装的 codex 二进制。请在 WSL 终端内调用它。
四、首次启动与认证：两种登录方式
安装完成后，进入你的项目目录，运行 codex。第一次运行时，它会引导你完成认证。有两个选择。
选择一：用 ChatGPT 账号登录（推荐）
选择 "Sign in with ChatGPT"，浏览器会打开 OAuth 授权页面。授权后，你的 ChatGPT 订阅（Plus、Pro、Business、Edu 或 Enterprise）就和 CLI 绑定了。
这种方式解锁全部功能，包括云端会话（Cloud Threads）。如果你有 ChatGPT 订阅，这是首选。
你也可以随时手动触发登录流程：
codex login选择二：用 API Key 认证
适用于没有 ChatGPT 订阅的用户，或者 CI/CD 等自动化场景。设置环境变量即可：
# macOS / Linux
export OPENAI_API_KEY="sk-your-api-key-here"
# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-api-key-here"API Key 方式按用量计费，不受 ChatGPT 订阅计划限制。适合需要精确控制调用成本的开发者。但部分功能（如 Cloud Threads）在 API Key 模式下不可用。
认证完成后，你就进入了 Codex 的交互界面。界面上方会显示当前使用的模型和工作目录。你可以直接输入任务描述，开始干活。
五、三档审批模式：你的控制权你做主
Codex CLI 最核心的设计理念是"可控"。它用三档审批模式来决定 AI 自主的边界：
| Suggest | ||
| Auto Edit | ||
| Full Auto |
切换方式有两种。启动时用命令行参数：
# 启动交互模式（默认 Suggest）
codex
# 一句话任务模式
codex "给 auth.py 的所有函数写单元测试"
# 指定 Auto Edit 模式
codex --approval-mode auto-edit "重构 utils 目录"
# 指定 Full Auto 模式（简写 -a）
codex -a full-auto "add type hints to all functions"或者在会话中用快捷命令 /mode 切换。
一个重要的安全提示：Codex 在进入 Auto Edit 或 Full Auto 模式前，如果当前目录不在 Git 版本控制下，会发出警告。这不是多管闲事——没有 Git 的 Full Auto，就是没有刹车的高速公路。
六、常用命令速查
安装完成后，这些是你最常用的命令：
七、常见问题排查
安装过程中，这几个问题出现频率最高。
问题1：安装后运行 codex 提示 "command not found"
这不是安装失败，而是 npm 全局安装目录不在你的 PATH 里。找到全局 bin 目录：
npm prefix -g输出的路径加上 /bin 就是 codex 所在目录。把它加到你的 PATH 中。
macOS / Linux 用户可以在 ~/.bashrc 或 ~/.zshrc 中添加：
export PATH="$(npm prefix -g)/bin:$PATH"然后重新打开终端。
Windows 用户在系统设置——环境变量中，将 %APPDATA%\npm 添加到用户 PATH。
问题2：npm 权限报错
macOS / Linux 上，如果 npm 全局安装报 EACCEN 权限错误，最干净的做法是配置 npm 使用用户目录：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codexWindows 上以管理员身份运行 PowerShell，或者执行：
npm config set prefix "$env:APPDATA\npm"问题3：macOS 提示 "无法打开，因为无法验证开发者"
这是 macOS Gatekeeper 安全机制。两种解决方式：
方式一：命令行解除隔离属性：
xattr -d com.apple.quarantine /usr/local/bin/codex方式二：系统设置——隐私与安全性，在首次阻止后点击"仍要打开"。
问题4：更新后版本号没变
Shell 会缓存命令路径。更新后打开一个新终端窗口，或者手动清除缓存：
# bash
hash -r
# zsh
rehash如果还不对，可能是你混用了多种安装方式，系统里有多份 codex 二进制。用 which -a codex 找出所有副本，保留一个，删掉其他的。
一个原则：每台机器只用一种安装方式。混用 npm、Homebrew 和二进制下载，是出问题的根源。
问题5：浏览器登录窗口打不开
如果 OAuth 浏览器流程没有自动打开，改用 API Key 方式认证。设置 OPENAI_API_KEY 环境变量后直接运行 codex 即可。
八、最佳实践：让 Codex 更好地为你工作
安装只是第一步。用好 Codex，有几个关键习惯。
第一，善用 AGENTS.md。
在项目根目录创建 AGENTS.md 文件，写入项目规范、代码风格约定、禁止修改的目录。Codex 启动时会自动加载这个文件，把它当作持久化的系统指令。你可以在 ~/.codex/codex.md 放全局规则，在各子目录的 AGENTS.md 放局部规则。子目录的规则优先级高于父目录。
第二，养成 Git 习惯。
每次让 Codex 干活之前，先 git commit 创建一个检查点。任务完成后，用 git diff 审查改动，不满意就 git checkout 回滚。这是 Full Auto 模式的核心安全机制。
第三，循序渐进。
新手最合理的上手路径是三步走：Suggest 模式入门，熟悉工作流后切 Auto Edit，最后在隔离的测试环境中尝试 Full Auto。不要一上来就 Full Auto——你还没建立对它的信任模型。
第四，定期更新。
Codex 更新频率很高。用内置命令自更新最简单：
codex update或者根据你的安装渠道更新：
# npm
npm install -g @openai/codex@latest
# Homebrew
brew upgrade --cask codex
# 独立脚本（macOS / Linux）
curl -fsSL https://chatgpt.com/codex/install.sh | sh九、写在最后
Codex CLI 的核心价值在于三个字：可控制。三档审批模式让你自己决定 AI 自主的边界，AGENTS.md 让你用文件定义权限，Git 给你兜底。它不是黑盒自动化工具，而是一个透明度很高、可以逐步建立信任的编程 Agent。
从安装到上手，整个流程其实就几步：选一种安装方式，装好，登录，跑起来。难点不在操作本身，而在于选择——选对包名、选对平台路径、选对审批模式。
希望这篇教程帮你跳过那些常见的坑，把时间花在真正重要的事情上：让 AI 帮你写好代码。
参考来源：OpenAI 官方文档、GitHub 仓库及社区实践指南。文中信息截至2026年8月。
