一句话总结
Codex 是 OpenAI 的编码 agent，有两个形态：Codex CLI 跑在你的终端里，Codex 云端（web） 会开一个隔离沙盒，拉一份仓库副本、起分支、改代码、跑测试、开 PR——你可以同时去干别的。截至 2026 年 6 月，两者默认都用 GPT-5.5。你需要一个付费 ChatGPT 套餐：入门是 Plus，每月 $20；免费版不含 Codex，Go（$8）只够干轻量任务。新手最大的错误，是把 Codex 当聊天框用，而不是写一份带明确约束和验收标准的任务 spec。
Codex 是什么、不是什么
Codex 走的是”扔个任务、走开、回来看 PR”这套 agent 思路。云端形态会把每个任务放进一个 OpenAI 托管的容器里跑，容器里有一份独立的仓库副本——这正是它能并行的原因，但也带来一类新手意料之外的 bug：环境漂移、缺 secrets，以及 agent”顺手”改了你压根没让它碰的东西。
关于这个沙盒，有两点决定了后面一切：
- 联网分两个阶段。 setup 阶段（装依赖时）容器能联网；agent 阶段则默认断网，只有任务确实需要时，你才按环境开放有限或完全的访问。（OpenAI：agent 联网）
- secrets 只在 setup 阶段存在。 你为云端环境配的任何 secret，只在 setup 脚本运行时可用，agent 阶段开始前就被清掉。如果你的测试在运行时需要一个真实 API key，沙盒里是没有的。（OpenAI：云端环境）
什么时候上 Codex：活儿是一个自成一体、跑得比较久、又不需要你盯着实时落地的改动——30 个文件的重构、依赖升级、测试覆盖率扫描、文档批改。像用 AI 审计 React Native 项目这种全仓任务尤其合适。
什么时候别用：需要看中间产出并随时介入、反馈循环很紧、任务需要被沙盒清掉的运行时 secret、或者一行小改（配置成本盖过节省）。这些场景下，Cursor 或 Claude Code 这类交互式工具更合适。
你到底能拿到哪个套餐、哪个模型（2026 年 6 月）
Codex 的用量从 2026 年 4 月 2 日起改成按 token / 额度计费，覆盖 Plus、Pro、Business 和新的 Enterprise 套餐，取代了原来的按条数限制。现在你拿到的是一个按时间窗口计的”本地消息”额度，超了之后可以按公布的每百万 token 价格再买额度。（Codex 定价）
| 套餐 | 价格（2026 年 6 月） | 含 Codex？ | GPT-5.5 额度（每 5 小时窗口） |
|---|---|---|---|
| Free | $0 | 不含 | — |
| Go | $8/月 | 仅轻量任务 | — |
| Plus | $20/月 | 含 | 约 15–80 条本地消息 |
| Pro（5x） | $100/月 | 含 | 约 80–400 条本地消息 |
| Pro（20x） | $200/月 | 含 | 约 300–1,600 条本地消息 |
| Business / Enterprise | 按席位 | 含 | Enterprise 走弹性额度，无固定上限 |
表里的区间是 OpenAI 公布的浮动带，不是固定值——实际用量取决于任务大小和推理强度。重度用户的实际反馈是：一旦同时跑多个实例、再开 fast 模式，每个开发者每月大概 $100–$200 的用量。
模型方面：GPT-5.5 大约在 2026 年 4 月 23–24 日成为 Codex 默认模型，也是大多数编码、重构、调试、测试任务的推荐选择。选择器里还有 gpt-5.4、更快的 gpt-5.4-mini（适合子 agent）和 gpt-5.3-codex。（Codex 模型）注意：Codex 只跑 OpenAI 模型——想在终端 agent 里用 Anthropic 模型，那是 Claude Code，不是 Codex。
装好 CLI（5 分钟）
想在本地驱动 Codex（替代云端，或两者并用），就装 CLI。它需要 Node.js 22 或更高版本。
npm install -g @openai/codex
codex --version
codex首次启动时选 Sign in with ChatGPT——这会通过 OAuth 链接你现有的 Plus / Pro / Business 订阅，不用重复付费。（你也可以用 OpenAI API key 登录、按 token 付费。）注意包名：是 @openai/codex，不是 2012 年那个无关的非作用域 codex 包。（npm：@openai/codex）
开始云端任务前的准备
- 确认仓库 CI 在
main上是绿的。从失败基线起步，Codex 会继承它，你就分不清哪些 bug 是它造的。 - 在仓库根放一个
AGENTS.md。Codex 靠它找你的构建 / lint / 测试命令和”绝不这么写”规则——这是投入产出比最高的一步。（OpenAI：AGENTS.md） - 把装依赖（setup 阶段）需要的 secret 配好。记住它们在 agent 跑之前会消失，所以测试要设计成运行时不依赖真实凭证。
- 提前定好分支命名和 PR 约定，让 agent 的产出能直接落进你的工作流。
具体步骤
- 登录并连接仓库。如果你对这个代码库不熟，写 spec 前先做一次快速 AI 代码库导览——让 spec 里写的是真实的文件名、函数名，不是猜的。
- 建任务，写明验收标准。一个不错的起手任务是用 Codex 审查 sitemap。Spec 像”bug 票 + 测试”那样写：
目标：将 `src/api/` 内已弃用的 `request.json()` 调用替换为 `await request.json()`。
约束：
- 不要修改 `src/api/` 之外的任何文件。
- 保留现有错误处理模式。
- 用项目现有的 async 风格（参考 `src/api/auth.ts`）。
验收：
- 现有测试全过。
- `src/api/__tests__/json-parse.test.ts` 新增测试覆盖新行为。
- `npm test` 无 console warning。- 让 Codex 跑。它会开沙盒、起分支、改代码、跑测试、开 PR。小而明确的任务通常 5–15 分钟完成；全仓扫描跑 30–60 分钟（OpenAI 给单个云端任务的活跃 agent 时间大致是 1–30 分钟）。
- 审 PR 像审人类 PR 一样：每个改动文件都读，看证明改动的那个测试，本地拉分支跑一遍再信它。
- 在 PR 评论里迭代。Codex 会读评论并 push 跟进 commit。这一步用来做小修正，不是用来重写目标——目标变了就开新任务。
- 满意就合。合并后才发现遗漏的情况，开新任务，别往已合并的 agent 分支上再补 commit。
合并前先核对产出
审查这一步决定了 Codex 是赢得还是失去你的信任。四个检查能挡掉大多数问题：
- 它守住 scope 约束了吗？ diff 的文件列表一眼就能回答”有没有动
src/api/之外的东西”。 - 测试是不是全过了，包括你没点名的？ 扫一眼 CI 日志里的 skipped——一个绿勾配三个 skip，不叫”全过”。
- 它有没有”顺手”加东西？ 你没要的额外重构是 Codex 最常见的失败模式。回滚掉，它们不是白送的。
- PR 描述准确吗？ Codex 偶尔会夸大它做了什么。读代码，别读总结。
容易踩的坑
- 任务描述模糊，比如”修登录 bug”。agent 会挑一种修法，未必是你要的。
- 没写验收。 没有具体的”完成”测试，agent 的”完成”和你的不是一回事。
- 不熟的仓库跳过代码库导览。 spec 要用真实名字，不写就靠猜，猜的都错。
- 以为沙盒运行时有你的 secret。 没有——setup 之后就被清掉了。围着这点设计。
- 让 Codex 碰 CI 配置或 secret 处理。 在约束里显式排除。
- 在相关文件上并行跑任务。 两个 agent 改相邻代码，会以很难收拾的方式冲突。
- 把 PR 当生产可用却不审。 Codex 产出是”PR 质量初稿”，不是”不读就合”。
FAQ
- 用 Codex 必须付费吗？：是的。截至 2026 年 6 月，免费版不含 Codex；入门是 Plus（每月 $20），Go（$8）只够轻量任务，Pro（$100 或 $200）能大幅抬高用量上限。
- Codex 用什么模型？：2026 年 4 月下旬起默认 GPT-5.5，另外还能选 GPT-5.4、GPT-5.4-mini 和 GPT-5.3-codex。Codex 只跑 OpenAI 模型。
- 云端沙盒能联网吗？：只在 setup 阶段能。agent 阶段默认断网；任务确实需要时，可以按环境开放有限或完全访问。
- 能跑我完整的测试套件吗？：能，在沙盒里跑——前提是依赖能用
AGENTS.md里的命令干净安装，且测试不依赖真实 secret（secret 在 agent 阶段前会被清掉）。 - 任务中途失败怎么办？：Codex 通常会带着已完成的部分开 PR 并附失败说明。读失败日志、精修 spec、重跑。
- 跟 Claude Code、Cursor 有啥不同？：Codex 云端是异步的；Cursor、Claude Code 是交互式的。想扔出去并行、然后走开就选异步；想要紧反馈循环就选交互。