如果 Claude Code 是 Anthropic 的终端 AI 代理，那 Codex CLI 就是 OpenAI 的回答。
它们解决的是同一个问题：让 AI 在你的终端里自主工作——读文件、写代码、跑命令、修 bug。
但 Codex CLI 有一些独特的设计理念值得了解。这篇教程带你从安装到实战，再到用 MCP + Agent SDK 搭建多代理工作流。
Codex CLI 是什么？
一句话：一个运行在终端里的 AI 编程代理，可以理解你的代码库并自主执行任务。
| 特性 | 说明 |
|---|---|
| 开发者 | OpenAI（官方产品） |
| 模型 | codex-mini（默认），可切换 o4-mini、GPT-4o 等 |
| 平台 | macOS / Linux / Windows |
| 安全 | OS 级沙盒（网络隔离 + 目录隔离） |
| 认证 | ChatGPT 账号登录 或 API Key |
| 开源 | 是（GitHub: openai/codex） |
| 价格 | ChatGPT Plus/Pro 用户直接用，或按 API 计费 |
核心区别在于沙盒：Codex CLI 默认在一个隔离的沙盒环境中执行命令——AI 不能访问你的网络，也不能跳出项目目录。这比 Claude Code 的权限模型更保守，更安全。
步骤 1：安装（2 分钟）
方法 A：npm（推荐）
npm install -g @openai/codex
方法 B：Homebrew（macOS）
brew install --cask codex
验证安装：
codex --version
步骤 2：认证（1 分钟）
首次运行 codex，会弹出认证选项：
? How would you like to authenticate?
> Sign in with ChatGPT (recommended)
Use API key
方式一：ChatGPT 账号（推荐）
选择 “Sign in with ChatGPT” → 浏览器弹出登录页 → 授权 → 完成。
ChatGPT Plus/Pro 用户可以直接用，无需额外付费。
方式二：API Key
export OPENAI_API_KEY="sk-proj-xxxxxxxx"
codex
适合 CI/CD 环境或需要精确控制费用的场景。
步骤 3：第一次使用（即刻开始）
在你的项目目录下运行：
cd ~/my-project
codex
你会看到一个交互式终端界面。直接输入你的需求：
> 帮我看看这个项目的整体结构，然后找出所有 TODO 注释
Codex 会：
- 扫描项目文件结构
- 搜索所有含
TODO的文件 - 汇总结果给你
三种运行模式
Codex CLI 有三种权限模式，适合不同场景：
模式一：Suggest（只建议）
codex --suggest "优化这个函数的性能"
AI 只建议修改，不会实际执行。你可以逐条审查后决定是否采纳。
最安全的模式。适合学习或不熟悉的代码库。
模式二：Auto（默认，自动执行安全操作）
codex "添加一个用户登录功能"
AI 可以自动读文件和写文件，但运行命令前会请求你确认。
日常开发的最佳平衡点。
模式三：Full Auto（全自动）
codex --full-auto "运行测试并修复所有失败的用例"
AI 全自动执行所有操作——读、写、运行命令，不需要你确认。
使用前建议先
git commit，这样随时可以git reset回退。
实战场景
场景 1：理解陌生代码库
cd ~/unfamiliar-project
codex "这个项目是做什么的？帮我画一个架构图，列出主要模块和它们的关系"
Codex 会阅读关键文件（README、package.json、主入口文件），然后给你一份结构化的项目概述。
场景 2：修 Bug
codex "用户报告登录时偶尔报 500 错误。请检查 auth 相关的代码，找到可能的 bug 并修复"
Codex 会搜索 auth 相关文件、分析代码逻辑、定位问题、修复并运行测试。
场景 3：写测试
codex "给 src/utils/validate.ts 写单元测试，覆盖所有边界情况"
场景 4：重构
codex "把所有 class 组件改成函数组件，保持功能不变，然后运行测试确保没有破坏"
场景 5：部署
codex "帮我把这个项目部署到 Vercel，如果需要我输入什么告诉我"
场景 6：安装和配置工具
codex "帮我安装 OpenClaw 并配置 Telegram Bot，Token 是 xxx，API Key 是 xxx"
没错——你可以用 Codex 来安装和配置其他 AI 工具。AI 帮 AI 装软件，这就是 2026。
Codex CLI vs Claude Code：怎么选？
| 维度 | Codex CLI | Claude Code |
|---|---|---|
| 背后模型 | OpenAI codex-mini / o4-mini | Claude Opus / Sonnet |
| 沙盒 | OS 级沙盒（默认隔离） | 权限提示 + 用户确认 |
| 代码质量 | 好（GPT-4o 水平） | 极好（Claude 长文理解更强） |
| 上下文窗口 | 大 | 极大（200K token） |
| MCP 支持 | 原生支持 | 原生支持 |
| Agent SDK | 有（TypeScript SDK） | 有（Agent SDK） |
| 价格 | ChatGPT Plus 含 / API 计费 | Max 计划含 / API 计费 |
| 最强场景 | 快速原型、安全敏感环境 | 大型项目、复杂重构 |
结论：
- 如果你主要用 OpenAI 生态 → Codex CLI
- 如果你主要用 Anthropic 生态 → Claude Code
- 如果你两个都用 → 都装上，按任务选择
进阶：MCP 集成
MCP（Model Context Protocol）让 Codex 可以调用外部工具和数据源。
配置 MCP 服务器
创建 ~/.codex/config.json：
{
"mcpServers": {
"my-database": {
"command": "npx",
"args": ["my-mcp-database-server"],
"env": {
"DATABASE_URL": "postgresql://localhost/mydb"
}
},
"remote-api": {
"type": "http",
"url": "https://my-mcp-server.example.com/mcp"
}
}
}
使用场景
配置好 MCP 后，你可以说：
查询数据库中上个月注册的用户数量，然后生成一份图表
Codex 会通过 MCP 调用数据库查询工具，获取数据，然后生成可视化。
进阶：Agent SDK（多代理编排）
这是 Codex 最硬核的功能：把 Codex CLI 暴露为 MCP 服务器，然后用 Agent SDK 编排多个 AI 代理。
架构
Agent SDK (编排层)
├── Agent 1: Codex CLI (写前端代码)
├── Agent 2: Codex CLI (写后端代码)
└── Agent 3: Codex CLI (写测试)
示例：自动化代码审查流水线
import { Agent, Runner } from "@openai/agents";
const reviewer = new Agent({
name: "code-reviewer",
instructions: "审查 PR 中的代码质量、安全性和性能问题",
tools: [codexTool],
});
const tester = new Agent({
name: "test-writer",
instructions: "为变更的代码编写单元测试",
tools: [codexTool],
});
// 编排：先审查，再写测试
const result = await Runner.run(reviewer, "审查 PR #42");
await Runner.run(tester, `基于审查结果写测试: ${result}`);
这意味着你可以构建一个完整的 CI/CD 流水线，其中每个环节都由独立的 AI 代理执行。
安全注意事项
沙盒保护
Codex CLI 的沙盒在操作系统层面隔离：
- 网络隔离：AI 不能访问互联网（除非你明确允许）
- 目录隔离：AI 只能访问当前项目目录
- 命令审查：危险命令需要用户确认
最佳实践
- 先 commit 再用：每次让 Codex 做大改动前，先
git commit - 用 Auto 模式：除非你完全信任 AI，否则不要用 Full Auto
- 检查 diff：完成后用
git diff检查所有变更 - 不要暴露 API Key：使用环境变量，不要在命令行中明文传递
快速上手命令速查
# 安装
npm install -g @openai/codex
# 基本使用
codex "你的需求"
# 只建议不执行
codex --suggest "优化性能"
# 全自动模式
codex --full-auto "运行测试并修复"
# 指定模型
codex --model o4-mini "写一个 API 端点"
# 安静模式（CI/CD）
codex --quiet --full-auto "lint and fix"
# 查看帮助
codex --help
写在最后
Codex CLI 和 Claude Code 代表了同一个趋势：AI 从"对话工具"变成了"执行工具"。
你不再需要把代码粘贴到聊天窗口、等待回复、再复制回去。AI 直接在你的电脑上工作——读你的文件、写你的代码、跑你的测试。
区别只在于：Codex 更保守（沙盒优先），Claude Code 更自由（权限更大）。选哪个取决于你的安全偏好和模型偏好。
或者——两个都装上。 在需要安全沙盒的时候用 Codex，在需要深度理解代码的时候用 Claude Code。2026 年的开发者不需要选边站。
安装：
npm install -g @openai/codex