OpenAI Codex CLI 配置 — 与 Claude Code 和 Cursor 的对比
OpenAI 官方编码代理 CLI。安装、认证、自主模式，以及与 Claude Code 的对比 — 30 分钟内完成。
OpenAI 现已推出自家的编码代理 CLI。Codex CLI 是 OpenAI 对标 Anthropic Claude Code 的产品：基于 GPT-5（或 o1/o3 系列），提供自主 shell 执行、多文件编辑以及先计划再执行的工作流。
我认为多代理工具并存不是冗余，而是分工。不是哪个更好，而是各自适合什么任务——由于模型能力的差异，两者组合使用往往比单一工具更高效。
本指南配置 Codex CLI，并向已使用 Claude Code 或 Cursor 的用户说明哪些任务适合交给 Codex。刚起步？建议同时阅读 Claude Code 配置。
TL;DR
- Node.js 20+ →
npm install -g @openai/codex→codex→ 浏览器认证 - 使用 OpenAI API 密钥或 ChatGPT Plus/Pro 订阅
- 默认为审批模式（每条命令需确认）—
--auto-edit/--full-auto提高自主度 - 选择模型：
--model gpt-5或o3（性能与成本的权衡） - 与 Claude Code 的分工：见 §5
前提条件
- Node.js 20+（mac/dev-toolchain 或 windows/initial-setup）
- OpenAI 账户 — platform.openai.com 或 ChatGPT Plus/Pro
- 一个 git 管理的项目
1. Codex CLI 的定位
这是 OpenAI 的官方编码代理 CLI。不同于调用 OpenAI 模型的第三方工具（Cursor、Aider、Continue.dev），Codex CLI 是 OpenAI 自家的标准发布物。
与 Claude Code 的相似之处
- 在终端中自主运行
- 多文件编辑 · shell 命令 · git 集成
- 项目上下文（Codex 存储在
.codex/目录） - 计划 → 执行 → 验证工作流
差异
| 方面 | Codex CLI | Claude Code |
|---|---|---|
| 模型 | GPT-5 · o3 · o4 | Claude Opus / Sonnet / Haiku |
| 上下文窗口 | 200K（因模型而异） | 1M（Opus/Sonnet 4） |
| 自主度标志 | --auto-edit、--full-auto | 权限模式 + hooks |
| 认证 | API 密钥或 ChatGPT 订阅 | API 密钥或 Pro/Max 订阅 |
| 定价 | 按 token 或 Plus($20)/Pro($200) | 按 token 或 Pro($20)/Max($100/$200) |
| MCP 支持 | 部分（进行中） | 完整 |
| IDE 集成 | 独立 IDE 扩展 | VS Code · JetBrains · CLI |
适合人群
- 已在使用 ChatGPT Plus/Pro — Codex CLI 包含在内
- 已在 OpenAI 生态 — 与 Embeddings、DALL·E 等共享密钥
- 需要 o3/o4 推理优势 — 用于长思考任务
- 需要 GPT-5 多模态 — 以图像 / 图表作为输入
2. 安装
2.1 npm 全局安装
npm install -g @openai/codex
codex --version安装失败或遇到权限错误，参见 Claude Code 配置 §1.1 中的 npm-prefix 解决方案。
2.2 首次运行
cd ~/projects/my-repo
codex浏览器标签页打开 OpenAI 登录 → 授权 → 返回 CLI。Token 存储在操作系统钥匙链中。
2.3 认证选项
三种方式：
# A. ChatGPT Plus/Pro（订阅）
codex auth login --use-chatgpt
# B. OpenAI API 密钥
codex auth login --use-api
# → 读取 OPENAI_API_KEY 或提示输入
# C. 专属 Codex.com 账户（测试版）
codex auth login --use-codex检查：
codex auth status
# Account: <email>
# Plan: ChatGPT Plus / API tier 23. 自主模式
默认模式较为保守 — 每条 shell 命令和编辑都需要确认。各级别说明：
| 标志 | 行为 | 风险 |
|---|---|---|
| （默认） | 每条命令和编辑都询问 | 低 |
--auto-edit | 编辑自动，shell 仍询问 | 中 |
--full-auto | 全部自动（危险） | 高 |
建议：在充分熟悉该工具之前保持默认，然后在信任的 repo 上切换到 --auto-edit。
codex --auto-edit
> Refactor the auth module into smaller files4. 核心命令
4.1 开始会话
codex
> Plan: add a password reset feature自然语言 prompt → Codex 提出执行计划 → 你审批 → 执行。
4.2 斜杠命令
会话内：
/help— 命令列表/init— 分析项目并创建AGENTS.md/model gpt-5— 切换模型/clear— 重置上下文/exit— 退出
4.3 AGENTS.md — 项目指引
Codex 对应 CLAUDE.md 的文件。放在项目根目录：
# AGENTS.md
## 技术栈
- Next.js 16 + TypeScript strict
- Supabase + Postgres
- pnpm 11
## 命令
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`
## 约定
- 不使用 `any` 类型
- 路由：kebab-case
- 提交：`[Project] type: description`
## 工作原则
- 5+ 文件变更前先计划
- 测试 + lint + 构建必须通过才算「完成」
- 永远不要提交密钥会话开始时自动加载，功能上与 CLAUDE.md 几乎相同。
与 Claude Code 同时使用时：可在
CLAUDE.md和AGENTS.md之间保持内容同步，或只维护AGENTS.md并在CLAUDE.md中通过@AGENTS.md引用。
5. Claude Code vs Codex CLI — 任务分配
| 任务 | 选择 | 原因 |
|---|---|---|
| 1M 上下文多文件工作 | Claude Code | Opus/Sonnet 4 的 1M 窗口 |
| 长推理（调试、架构） | Codex CLI（o3） | 推理模型优势 |
| 代码 + 图像（截图分析） | Codex CLI（GPT-5 多模态） | 图像输入 |
| 变更后的自主验证 | Claude Code | hooks + 验证体系 |
| OpenAI 生态集成（embeddings 等） | Codex CLI | 统一密钥 |
| MCP 服务器（Linear、Notion 等） | Claude Code | 完整 MCP |
| 最小化成本 | 已有的订阅选哪个 | 避免 API token 消耗 |
两者在同一 repo 中共存不冲突（均基于 git 工作流）。
6. 定价（截至 2026-05）
API 定价（Codex CLI）
| 模型 | 输入 | 输出 | 每千次成本 |
|---|---|---|---|
| GPT-5 | $1.25 / 1M | $10 / 1M | 输入成本低 |
| o3 | $2 / 1M | $8 / 1M | 推理调优 |
| o4-mini | $0.3 / 1M | $1.2 / 1M | 最佳性价比 |
订阅
| 套餐 | 价格 | Codex CLI 用量 |
|---|---|---|
| ChatGPT Plus | $20/月 | GPT-5 有限量，部分 o3 |
| ChatGPT Pro | $200/月 | 几乎无限制 |
实际花费因人而异。使用 API 的全栈开发者粗略平均约 $30–100/月，重度用户选 Pro 订阅更划算。
7. 验证
# 1. 已安装
codex --version
# 2. 认证
codex auth status
# 3. 项目文件
ls -la AGENTS.md .codex/
# 4. 首条命令测试
echo "create a hello.py that prints 'hello'" | codex --auto-edit四项全通过 = 配置完成。
8. 故障排查
codex: command not found
- 检查 npm prefix：
npm config get prefix的/bin必须在 PATH 中 - 打开新终端后重试
浏览器认证未打开
- 无头环境（WSL2/SSH）：将 CLI 中的 URL 复制到浏览器
- 仍然失败？删除
~/.codex/auth.json后使用codex auth login --use-api加密钥
"Insufficient quota"
- OpenAI 使用量上限已到 — platform.openai.com/usage
- 免费层限制极严。Tier 1+（预充 $10 后激活）是实际可用的最低门槛
Codex 和 Claude Code 同时编辑同一文件
- 一次运行一个，或让第二个等待
- 或在
.gitignore中添加.codex-lock风格的哨兵文件协调
--full-auto 运行过于激进
- 立即按
Ctrl+C中断 git reset --hard HEAD或git stash恢复状态- 此后坚持使用
--auto-edit
MCP 服务器无法连接
- 截至 2026-05，Codex CLI 的 MCP 支持尚不完整（测试版）
- 完整 MCP 集成请使用 Claude Code
9. 下一步
- Claude Code 配置 — /ai-agents/claude-code
- Cursor 配置 — /ai-agents/cursor-setup
- Copilot 配置 — /ai-agents/github-copilot
- 多工具工作流 — /ai-agents/multi-tool-workflow
参考资料
更新日志
- 2026-05-16：初稿。Codex CLI 安装 + 三种认证方式 + 自主模式 + AGENTS.md + Claude Code 对比表 + 六个故障排查案例。