OpenAI Codex CLI 下载与使用指南

---

一、Codex 是什么

Codex CLI 是 OpenAI 推出的本地终端 AI 编程智能体。它运行在你自己的电脑上，能够直接读取、编辑项目文件，执行终端命令，帮你完成编码任务。

三种使用方式：

方式	说明
Codex CLI（终端）	本地终端运行，直接操作文件系统和终端
Codex Web	云端版本，访问 chatgpt.com/codex
IDE 插件	VS Code / Cursor / Windsurf 中安装使用

本文档聚焦 Codex CLI（终端版） 的安装与使用。

---

二、系统要求

项目	要求
操作系统	macOS / Linux / Windows（推荐 WSL2）
Node.js	>= 18.0（推荐 v20+ LTS）
网络	需要访问 api.openai.com（或配置代理）
账号	OpenAI API Key 或 ChatGPT Plus/Pro/Team/Enterprise 订阅

---

三、安装

方式一：npm 安装（推荐）

# 全局安装
npm install -g @openai/codex

# 验证安装
codex --version

方式二：Homebrew 安装（macOS）

brew install --cask codex

方式三：下载二进制文件

前往 GitHub Releases 下载对应平台的压缩包：

平台	文件名
macOS Apple Silicon	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

解压后将二进制文件重命名为 codex，放入 PATH 目录：

tar -xzf codex-aarch64-apple-darwin.tar.gz
mv codex-aarch64-apple-darwin codex
sudo mv codex /usr/local/bin/

Node.js 安装（前置步骤）

如果还没有 Node.js：

# macOS
brew install node

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证
node -v   # 应显示 v18+ 或 v20+
npm -v

---

四、认证配置

方式一：ChatGPT 账号登录（推荐）

直接运行 codex，选择 Sign in with ChatGPT，浏览器会弹出登录页面。

适用人群：ChatGPT Plus / Pro / Team / Edu / Enterprise 订阅用户。

方式二：API Key

# 设置环境变量（当前终端会话生效）
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 永久生效：写入 shell 配置文件
echo 'export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

方式三：配置文件

配置文件路径：~/.codex/config.toml

[api]
key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
base = "https://api.openai.com/v1"
model = "codex-mini"  # 可选：codex-mini / codex-max

---

五、基本使用

5.1 启动交互模式

# 在项目目录下启动
cd /path/to/your/project
codex

启动后进入交互式对话界面，直接用自然语言描述需求即可。

5.2 带提示词启动

# 直接传入任务描述
codex "帮我重构这个项目的目录结构"

# 查看帮助
codex --help

5.3 常用斜杠命令

在交互模式中可使用以下命令：

命令	说明
/help	查看帮助
/clear	清空对话历史
/compact	压缩对话上下文
/quit	退出
/cost	查看当前会话 token 消耗

5.4 非交互模式（codex exec）

# 一次性执行任务，不进入交互界面
codex exec "检查项目中所有的 TODO 注释"

---

六、核心功能

6.1 文件操作

Codex 可以直接读取和编辑你项目中的文件：

你：读取 src/app.ts 的内容，帮我找出所有的 async 函数
你：在 src/utils/helper.ts 中添加一个 formatDate 函数
你：将 config.json 中的 timeout 从 30 改为 60

6.2 终端命令执行

Codex 可以在沙箱中执行终端命令：

你：运行 npm test 并告诉我哪些测试失败了
你：安装 lodash 依赖
你：查看当前 git status

6.3 项目理解与分析

你：分析这个项目的整体架构
你：找出代码中可能的性能瓶颈
你：检查是否有安全漏洞

6.4 AGENTS.md（项目记忆）

在项目根目录创建 AGENTS.md 文件，写入项目相关的上下文信息，Codex 每次启动时会自动读取：

# AGENTS.md

## 项目概述
这是一个基于 Next.js 的电商后台管理系统。

## 技术栈
- 前端：Next.js 14 + TypeScript + Tailwind CSS
- 后端：Node.js + Prisma + PostgreSQL
- 部署：Vercel

## 编码规范
- 使用 TypeScript strict 模式
- 组件命名使用 PascalCase
- API 路由放在 src/app/api/ 目录下
- 不要修改 prisma/schema.prisma，除非明确要求

---

七、沙箱与安全

Codex 在沙箱环境中执行命令，有以下安全机制：

• 审批机制：执行可能产生副作用的操作（如写入文件、运行命令）前会请求你确认
• 权限控制：可配置允许/禁止的操作类型
• Zero Data Retention (ZDR)：可开启零数据保留模式，OpenAI 不会存储你的代码和对话

配置文件中控制审批行为：

[sandbox]
# 是否自动批准文件读取
auto_approve_reads = true
# 是否自动批准文件写入
auto_approve_writes = false
# 是否自动批准终端命令执行
auto_approve_exec = false

---

八、进阶配置

8.1 模型选择

[api]
model = "codex-mini"   # 轻量快速
# model = "codex-max"  # 更强能力

8.2 MCP 服务器（Model Context Protocol）

Codex 支持连接 MCP 服务器，扩展工具能力（如数据库查询、API 调用等）：

[mcp]
[[mcp.servers]]
name = "my-server"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

8.3 代理配置

如果需要通过代理访问 OpenAI API：

export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"

8.4 自定义提示词

在 ~/.codex/config.toml 中配置自定义提示词模板：

[prompts]
my_review = "请对以下代码进行 Code Review，关注安全性、性能和可读性："

使用：

codex --prompt my_review

---

九、常见问题

Q: 安装后运行 codex 提示命令找不到？

# 确认 npm 全局 bin 目录在 PATH 中
npm config get prefix
# 将输出路径的 bin 目录加入 PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Q: 如何升级到最新版本？

npm update -g @openai/codex
# 或
brew upgrade codex

Q: 如何卸载？

npm uninstall -g @openai/codex
# 或
brew uninstall --cask codex

Q: Windows 上如何使用？

推荐通过 WSL2（Windows Subsystem for Linux）使用：

# PowerShell 中启动 WSL
wsl
# 然后在 WSL 中按 Linux 方式安装

Q: 免费用户能用吗？

Codex CLI 需要 ChatGPT Plus/Pro/Team/Enterprise 订阅，或使用 API Key 按量付费。免费版 ChatGPT 账号不支持。

---

十、实用技巧

1. 先写 AGENTS.md：在项目根目录放一个 AGENTS.md，描述项目结构、技术栈、编码规范，Codex 的输出质量会显著提升。
2. 任务拆分：复杂任务拆成小步骤，逐步让 Codex 执行，每步确认后再继续。
3. 利用 /compact：对话过长时使用 /compact 压缩上下文，节省 token 消耗。
4. 善用 git：让 Codex 操作前先提交当前代码，出问题可以随时 git checkout . 回退。
5. 审查变更：不要盲目接受所有修改，使用 git diff 查看每次变更内容。