第二课：安装与首次运行
欢迎来到 OpenAI Codex CLI 的世界！Codex 是 OpenAI 推出的一个开源编程智能体，它可以在你的终端中运行，理解你的代码仓库，并帮助你完成编程任务——从修复 Bug、重构代码，到实现新功能，全部通过自然语言指令完成。
本课将手把手教你完成 Codex 的安装和首次运行，让你快速上手这个强大的 AI 编程工具。
一、系统要求
在开始安装之前，请确保你的系统满足以下基本要求：
1.1 操作系统支持
| 操作系统 | 最低版本要求 | 架构支持 |
|---|---|---|
| macOS | macOS 12 (Monterey) 或更高 | Apple Silicon (M1/M2/M3/M4)、Intel x86_64 |
| Linux | 主流发行版（Ubuntu 20.04+、Debian 10+、Fedora 35+ 等） | x86_64、aarch64 |
| Windows | Windows 10 或更高 | x86_64（通过 WSL2 使用） |
⚠️ Windows 用户注意：Codex CLI 目前不支持原生 Windows 命令行，需要通过 WSL2（Windows Subsystem for Linux） 运行。请先安装 WSL2，然后在 Linux 子系统中按照 Linux 的安装方式操作。
1.2 必要依赖
-
Node.js 22 或更高版本：Codex CLI 基于 Node.js 运行。你可以通过以下命令检查版本：
node --version # 应输出 v22.x.x 或更高 -
OpenAI API Key：你需要一个有效的 OpenAI API Key，并且账户需要有访问以下模型的权限：
o3（推荐，默认模型）o4-minicodex-mini-latestgpt-4.1gpt-4.1-mini
-
Git：建议安装 Git，以便 Codex 能更好地理解你的代码仓库。
-
终端模拟器：任何支持 ANSI 转义序列的终端（macOS Terminal、iTerm2、Windows Terminal、Alacritty、Kitty 等）。
1.3 硬件建议
- 内存：建议至少 4GB 可用内存
- 磁盘空间：至少 500MB 可用空间（用于安装 Codex 和依赖）
- 网络：需要稳定的互联网连接（Codex 需要调用 OpenAI API）
二、安装方式一：curl 脚本（推荐）
这是最简单、最推荐的安装方式。一条命令即可完成安装。
2.1 macOS / Linux
打开终端，运行以下命令：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
这条命令会：
- 从 OpenAI 官方服务器下载安装脚本
- 检测你的操作系统和架构
- 下载对应平台的预编译二进制文件
- 将
codex可执行文件安装到系统路径中
💡 安全提示：如果你对直接执行远程脚本有安全顾虑，可以先下载脚本检查内容：
curl -fsSL https://chatgpt.com/codex/install.sh -o codex-install.sh cat codex-install.sh # 检查脚本内容 sh codex-install.sh # 确认无误后执行
2.2 Windows（通过 PowerShell）
在 PowerShell 中运行以下命令：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
参数说明：
-ExecutionPolicy ByPass：临时绕过 PowerShell 的执行策略限制irm：Invoke-RestMethod的别名，用于下载安装脚本iex：Invoke-Expression的别名，用于执行下载的脚本
⚠️ 如果你在 WSL2 中操作，请使用 macOS/Linux 的 curl 命令。
三、安装方式二：npm
如果你已经安装了 Node.js 和 npm，可以通过 npm 全局安装 Codex CLI。
3.1 安装命令
npm install -g @openai/codex
3.2 权限问题处理
如果你在 macOS 或 Linux 上遇到权限错误（EACCES），有以下几种解决方案：
方案 A：使用 sudo（简单但不推荐）
sudo npm install -g @openai/codex
方案 B：修改 npm 全局目录（推荐）
# 创建全局 npm 目录
mkdir -p ~/.npm-global
# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'
# 将新目录添加到 PATH
export PATH=~/.npm-global/bin:$PATH
# 使配置永久生效（以 bash/zsh 为例）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# 或 zsh 用户：
# echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
方案 C：使用 nvm（推荐用于开发环境）
# 如果还没有安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
# 安装最新 LTS 版本的 Node.js
nvm install --lts
# 然后安装 codex
npm install -g @openai/codex
3.3 更新 Codex
通过 npm 安装的 Codex 可以方便地更新：
npm update -g @openai/codex
四、安装方式三：Homebrew（macOS）
如果你是 macOS 用户，并且已经安装了 Homebrew 包管理器，这是最便捷的方式。
4.1 安装命令
brew install --cask codex
4.2 更新
brew upgrade --cask codex
4.3 卸载
brew uninstall --cask codex
💡 Homebrew 会自动管理依赖和路径，非常适合 macOS 用户。
五、安装方式四：GitHub Release 手动下载
如果你不想使用包管理器，或者网络环境受限，可以从 GitHub Release 页面手动下载预编译的二进制文件。
5.1 下载地址
前往 OpenAI Codex GitHub Releases 页面，下载对应平台的压缩包。
5.2 各平台文件名
| 平台 | 架构 | 文件名 |
|---|---|---|
| macOS | Apple Silicon (M1/M2/M3/M4) | codex-aarch64-apple-darwin.tar.gz |
| macOS | Intel | codex-x86_64-apple-darwin.tar.gz |
| Linux | x86_64 | codex-x86_64-unknown-linux-musl.tar.gz |
| Linux | ARM64 | codex-aarch64-unknown-linux-musl.tar.gz |
5.3 安装步骤（以 macOS Apple Silicon 为例）
# 1. 下载压缩包
curl -LO https://github.com/openai/codex/releases/latest/download/codex-aarch64-apple-darwin.tar.gz
# 2. 解压
tar -xzf codex-aarch64-apple-darwin.tar.gz
# 3. 移动到系统路径
sudo mv codex /usr/local/bin/
# 4. 添加执行权限
sudo chmod +x /usr/local/bin/codex
# 5. 清理压缩包
rm codex-aarch64-apple-darwin.tar.gz
5.4 安装步骤（以 Linux x86_64 为例）
# 1. 下载压缩包
curl -LO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
# 2. 解压
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
# 3. 移动到系统路径
sudo mv codex /usr/local/bin/
# 4. 添加执行权限
sudo chmod +x /usr/local/bin/codex
# 5. 清理压缩包
rm codex-x86_64-unknown-linux-musl.tar.gz
六、验证安装
安装完成后，通过以下命令验证 Codex 是否正确安装。
6.1 检查版本
codex --version
你应该看到类似以下的输出：
codex 0.1.x
6.2 运行诊断工具
Codex 内置了一个诊断命令，可以检查你的环境是否满足所有要求：
codex doctor
这个命令会检查：
- ✅ Codex 二进制文件是否正确安装
- ✅ Node.js 版本是否满足要求
- ✅ OpenAI API Key 是否已配置
- ✅ 网络连接是否正常
- ✅ API 端点是否可达
6.3 配置 API Key
如果 codex doctor 提示 API Key 未配置，你需要设置环境变量：
临时设置（当前终端会话有效）：
export OPENAI_API_KEY="sk-your-api-key-here"
永久设置：
将以下行添加到你的 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.bash_profile）：
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
或者创建一个 .env 文件放在项目目录中：
echo 'OPENAI_API_KEY=sk-your-api-key-here' > ~/.codex/.env
⚠️ 安全提示：永远不要将 API Key 提交到版本控制系统中！确保
.gitignore中包含相关的环境变量文件。
七、首次运行体验
恭喜！安装和配置都已完成。让我们来体验你的第一次 Codex 交互。
7.1 启动 Codex
在终端中运行：
codex
你将看到 Codex 的欢迎界面和交互式提示符。
7.2 基本交互
Codex 启动后，你可以直接用自然语言与它对话。以下是一些入门示例：
示例 1：询问项目信息
> 这个项目是做什么的？请帮我分析一下代码结构。
Codex 会自动扫描当前目录的文件，分析项目结构，并给出详细的说明。
示例 2：创建简单文件
> 创建一个 Python 脚本，实现一个简单的 HTTP 服务器，监听 8080 端口。
Codex 会生成代码并询问你是否同意执行。
示例 3：修复代码问题
> 运行测试，如果有失败的测试，请帮我修复。
7.3 界面介绍
Codex 的交互界面包含以下关键元素：
┌─────────────────────────────────────────────┐
│ Codex CLI │
│ ───────────────────────────────────────── │
│ Working directory: /path/to/your/project │
│ Model: o3 │
│ Approval mode: suggest │
│ ───────────────────────────────────────── │
│ │
│ > 你的输入在这里 │
│ │
│ [Codex 的思考和输出] │
│ │
│ ┌─ Tool Call ─────────────────────────┐ │
│ │ $ command here │ │
│ │ [output] │ │
│ └─────────────────────────────────────┘ │
│ │
│ [Approve] [Reject] [Edit] │
└─────────────────────────────────────────────┘
界面元素说明：
- 输入区域：在
>提示符后输入自然语言指令 - 模型信息：显示当前使用的 AI 模型
- 审批模式：显示当前的安全审批模式
- 工具调用区域：显示 Codex 执行的命令和输出
- 操作按钮：批准（Approve）、拒绝（Reject）或编辑（Edit）Codex 的操作建议
7.4 交互模式
Codex 支持多种交互模式，首次运行时默认使用 suggest 模式：
| 模式 | 说明 | 安全等级 |
|---|---|---|
suggest | 仅建议，不自动执行任何操作 | 🟢 最安全 |
auto-edit | 自动编辑文件，但需要批准命令执行 | 🟡 中等 |
full-auto | 自动执行所有操作（包括命令） | 🔴 请谨慎使用 |
💡 建议：初次使用时保持默认的
suggest模式，熟悉后再考虑切换到更自动化的模式。
7.5 常用快捷键
在 Codex 交互界面中，你可以使用以下快捷键：
Ctrl + C：中断当前操作Ctrl + D：退出 Codex↑ / ↓：浏览历史输入Tab：自动补全
八、常见安装问题排查
问题 1：command not found: codex
原因：Codex 的可执行文件路径没有添加到系统 PATH 中。
解决方案：
# 检查 codex 安装位置
which codex
# 或
npm list -g @openai/codex
# 如果使用 npm 安装，确认 npm 全局 bin 目录在 PATH 中
npm config get prefix
# 将输出的路径/bin 添加到 PATH
export PATH=$(npm config get prefix)/bin:$PATH
问题 2：Error: EACCES: permission denied
原因：npm 全局安装目录权限不足。
解决方案：参考前面「安装方式二」中的权限问题处理方案。
问题 3：OPENAI_API_KEY is not set
原因：未配置 API Key。
解决方案：
# 检查是否已设置
echo $OPENAI_API_KEY
# 如果为空，设置它
export OPENAI_API_KEY="sk-your-key-here"
问题 4：Error: Unable to connect to OpenAI API
原因：网络问题或代理配置。
解决方案：
# 测试网络连接
curl -I https://api.openai.com
# 如果使用代理，设置代理环境变量
export HTTPS_PROXY="http://your-proxy:port"
# 对于中国大陆用户，可能需要设置代理
export ALL_PROXY="socks5://127.0.0.1:7890"
问题 5：macOS 提示「无法打开，因为无法验证开发者」
解决方案：
# 方法一：在系统设置中允许
# 系统设置 → 隐私与安全性 → 仍然允许
# 方法二：移除隔离属性
xattr -d com.apple.quarantine /usr/local/bin/codex
问题 6：Node.js 版本过低
解决方案：
# 检查当前版本
node --version
# 使用 nvm 安装新版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
# 或使用 n（macOS/Linux）
npm install -g n
n 22
问题 7：WSL2 中无法使用
解决方案：
# 确保在 WSL2 中（不是 WSL1）
wsl --version
# 如果是 WSL1，升级到 WSL2
wsl --set-version <distro-name> 2
# 在 WSL2 中安装 Node.js 和 Codex
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -fsSL https://chatgpt.com/codex/install.sh | sh
九、本课小结
恭喜你完成了 OpenAI Codex CLI 的安装和首次运行！在本课中，你学到了：
- ✅ Codex CLI 的系统要求和环境准备
- ✅ 四种不同的安装方式（curl 脚本、npm、Homebrew、手动下载）
- ✅ 如何验证安装是否成功
- ✅ 如何配置 OpenAI API Key
- ✅ 首次运行 Codex 并了解交互界面
- ✅ 常见安装问题的排查方法
下一步
在下一课中，我们将深入学习 Codex 的配置选项和工作模式，让你能够根据自己的需求定制 Codex 的行为。
🚀 快速实践：现在就打开终端，运行
codex，试着让它帮你完成一个小任务吧！比如：「创建一个 README.md 文件，描述这个项目的用途」。