ChatGPT Plus / Pro 用户的 Codex 进阶实战：从 CLI 配置到 Agent 工作流、多文件重构与用量控制的完整指南

1. 先厘清一个认知：Codex 不只是聊天框里的"代码生成"

很多从 ChatGPT 网页版过来的开发者，拿到 Plus / Pro 后第一反应是在聊天框里让模型"帮我写一个爬虫"。这能用，但远不是 Codex 的正确打开方式。

Codex 真正的形态是一套面向软件工程的 Agent 系统，它可以：

读取并理解整个仓库，而不是单文件片段；
跨多个文件规划并执行修改；
在沙箱里运行测试、安装依赖、执行命令并观察结果；
根据报错回溯、自我修正，直到测试通过；
通过 CLI、IDE 插件、Cloud Sandbox 三种入口接入你的工作流。

换句话说，ChatGPT 对话是"问一句答一句"，而 Codex 更接近"把任务交给一个能动手的工程师"。理解了这一点，后续的玩法才有意义。

2. 开通 Plus / Pro 后你实际解锁了什么

权益差异这里不谈价格，只讲对开发工作流有影响的部分：

能力	Plus	Pro
Codex 模型访问	可用，受标准速率限制	更高配额与更高并发
Cloud 并行任务	有限数量	更多并行沙箱任务
Codex CLI 登录	支持	支持，更长会话
推理强度档位	可用	更宽松的 high effort

对于个人项目而言，Plus 已经完全够用；Pro 的价值在于你把它当作常驻的并行开发 Agent，同时跑多个 GitHub Issue 或重构任务时不会被限流打断。

一个容易被忽略的点：Codex CLI 支持用 ChatGPT 账号（OAuth）登录，也支持直接用 OPENAI_API_KEY。如果你是 API 计费用量较大的用户，用 Key 方式可以在配额和成本之间做更细的权衡。

3. 环境准备与 Codex CLI 安装

Codex CLI 是开源命令行工具，也是所有玩法里工程感最强、可控性最高的入口。先装工具：

bash 复制代码

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

# 或者用 Homebrew
brew install codex

首次运行会引导登录：

bash 复制代码

codex

如果你走 API Key 路线，配置环境变量：

bash 复制代码

export OPENAI_API_KEY="sk-..."

推荐维护一份 ~/.codex/config.toml 来自定义默认行为：

toml 复制代码

model = "gpt-5-codex"
model_reasoning_effort = "high"

# 审批策略：建议先用 on-request，等信任度建立后再考虑 auto
approval_policy = "on-request"

# 每次任务默认携带项目上下文
profile = "default"

安装完成后，可以先跑一个最小验证，确认它能正常读写你的工作目录：

bash 复制代码

codex exec "帮我在当前目录创建一个 hello.py，打印当前 Python 版本"

exec 模式适合单次、非交互的自动化任务；日常开发更常用的是进入交互式会话：

bash 复制代码

codex

进入后就是一个带文件读写、命令执行能力的对话终端。你可以直接说需求，它会先展示计划，再按审批策略执行命令。

4. 第一个进阶实战：用 Codex 重构一个真实项目

假设你手上有一个历史遗留的 Node.js 脚本项目，目录结构混乱，且没有任何测试。直接丢给 Codex 一个模糊需求通常效果不好，正确做法是给它明确的验收标准。

启动 Codex 前，先建一个任务描述文件 task.md：

markdown 复制代码

# 重构任务

## 输入
当前目录是一个 Express API 项目，路由和业务逻辑全部混在 app.js。

## 目标
1. 将路由拆分为 routes/ 目录，按资源分文件。
2. 将数据库访问收敛到 services/ 目录。
3. 保留原有 API 路径与返回结构不变。

## 验收标准（必须全部满足）
- `npm test` 全部通过；
- 新增一个 GET /health 接口返回 200；
- 不改变任何现有接口的响应格式。

## 约束
- 不使用 ORM，保持现有 SQL 写法；
- 不要升级依赖版本。

然后启动会话，把这份文件作为上下文输入：

bash 复制代码

codex

在交互界面中执行：

text 复制代码

请先阅读 task.md，然后按其中的验收标准执行重构。
每完成一个阶段，先跑对应测试，确认通过后再继续。

这里有两个关键技巧：

验收标准驱动：Codex 在多步任务中容易"顺手改过头"，把不变的 API 结构当成可优化对象。事先声明"不改变响应格式、不升级依赖"，能显著减少回滚次数。
阶段确认：让它"每完成一个阶段先跑测试"，相当于给它设置了检查点，能避免任务跑偏到后期才发现。

如果只想让它干完活不交互，可以用 exec 加非交互参数：

bash 复制代码

codex exec --sandbox read-only "阅读 task.md 并给出重构方案，先不要修改文件"

先让它做 read-only 规划，再切换成可写模式执行，是控制风险的好习惯。

5. 让 Codex 理解你的项目：AGENTS.md 与上下文工程

Codex 不是读心术。在陌生仓库里，它只能靠文件内容猜测规范。想让输出贴近你的习惯，最有效的方式是在仓库根部放一个 AGENTS.md。

示例：

markdown 复制代码

# Agents Guideline

## 语言与框架
- 本项目使用 TypeScript 5，不使用 JavaScript；
- 使用 pnpm 作为包管理器，禁止生成 package-lock.json。

## 代码风格
- 文件命名使用 kebab-case；
- 所有导出函数必须有 JSDoc，参数需注明类型；
- 测试统一放在 __tests__ 目录，使用 vitest。

## 提交与变更
- 除非明确要求，否则不要直接修改 .env 文件；
- 每次修改请同步更新 README 中的接口说明。

## 禁止事项
- 不要引入新的运行时依赖；
- 不要手动格式化 TypeScript，统一交给 prettier。

Codex CLI 会自动读取仓库根目录的 AGENTS.md 作为系统级项目上下文。这对团队协作尤其有用------把规范沉淀到文件里，每个成员启动的 Codex 会话都会遵守同一套规则。

进阶一点，还可以配合 codex exec 的配置文件区分不同 profile：

toml 复制代码

[profiles.reviewer]
model_reasoning_effort = "high"
approval_policy = "on-request"

在同一次任务中，你可以先用 default 生成实现，再用 reviewer profile 做只读审查，形成"生成---审查"的闭环：

bash 复制代码

codex exec "当前改动做一次只读代码审查，按严重程度列出问题"

这样比单纯"让它重写一遍"更有工程价值。

6. 多文件任务的组织方式：把大目标拆成可验证的小任务

Codex 擅长单次大任务，但面对"重写整个后台管理系统"这种需求，容易在中途产生不可控的偏差。更稳妥的玩法是任务切片。

一个推荐的结构：

text 复制代码

.github/agents/
  tasks/
    01-split-routes.md
    02-move-services.md
    03-add-tests.md
    04-ci-fix.md

每个任务文件都包含：输入、目标、验收标准、约束。然后按顺序执行：

bash 复制代码

codex exec "$(cat .github/agents/tasks/01-split-routes.md)"

执行完一个、跑一次测试、提交一次，再进入下一个。这样做的好处：

每次会话的上下文更聚焦，模型不会在长任务中遗忘早期约束；
出现问题时回滚范围可控；
配合 Git 分支，可以并行让多个 Codex 任务处理互不冲突的模块。

如果再进一步，可以把这些任务串进 CI：

yaml 复制代码

codex-review:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: npm install -g @openai/codex
    - run: codex exec "对本次 PR 做只读审查，重点关注安全与性能"

让 Codex 作为 PR 审查的辅助角色，是比"全自动写代码"更稳健的落地方式。

7. 和 Cursor、Claude Code 的取舍：什么时候用 Codex

非小白的开发者大概率同时接触过 Cursor 和 Claude Code，这里直接给结论性的对比：

场景	建议
编辑器内实时补全、Tab 跟随手写节奏	Cursor
单个仓库内的多文件 Agent 重构	Codex / Claude Code 均可
云端沙箱执行、脱离本地环境跑任务	Codex 原生优势
强大的终端可编程性与自定义 hook	Claude Code 生态更丰富
需要 ChatGPT 账号内统一管理、网页发起任务	Codex

Codex 的核心优势在于开箱即用的云端执行环境：你可以在网页端开一个 Cloud Sandbox，让它安装依赖、运行测试，而本地环境完全不受影响。这对于"想在 Mac 上检验一段只适配 Linux 的构建脚本"这类场景非常友好。

实际工程中，不少人的折中方案是：用 Cursor 做逐行级补全与局部重构，用 Codex 做跨文件的大任务与 CI 审查，用 Claude Code 做带复杂 hook 的工作流编排。三者不是替代关系。

8. 用量控制与排错：避免 Plus / Pro 被无谓消耗

对于 Pro 用户，用量宽裕并不代表可以放任 Codex 反复空转。几个有效的控制手段：

设低初始推理强度 ：小幅重构用 medium，只有跨文件架构调整才用 high。可以在 config.toml 中按 profile 区分。

强制 read-only 先行规划：

bash 复制代码

codex exec --sandbox read-only "先规划再动手，给我实施步骤"

它能读文件、能思考，但不能写文件和执行有副作用的命令，非常适合方案确认阶段。

控制沙箱命令范围：

bash 复制代码

codex exec --sandbox workspace-write "只允许在当前工作目录内写文件"

比完全放开更安全，适合处理陌生仓库。

常见排错清单：

codex 提示未登录 ：重新执行 codex 走 OAuth，或检查 OPENAI_API_KEY；
执行命令一直等待审批 ：检查 approval_policy，本地个人项目可临时设为 on-failure；
修改了大量无关文件 ：回溯会话后，在下一轮明确给出"只修改与目标相关的文件，其余保持原样"的约束，并把验收标准写进 task.md；
生成代码风格漂移 ：确认 AGENTS.md 在仓库根目录，且会话是从该目录启动。

9. 一个可以立即复用的工作流

把前面的内容串起来，得到一个适合个人项目的日常流程：

bash 复制代码

# 1. 确保项目上下文就绪
ls AGENTS.md

# 2. 用只读模式先出方案
codex exec --sandbox read-only "$(cat task.md)"

# 3. 确认方案后，切到可写模式执行
codex exec "$(cat task.md)"

# 4. 跑项目自带的验证
npm test

# 5. 让 Codex 回看 diff 做一次审查
git diff --stat
codex exec "审查当前未提交的改动，重点看是否有破坏性变更"

整个过程没有依赖任何 IDE 插件，纯终端即可完成，也方便写进脚本或 CI。

10. 总结

ChatGPT Plus / Pro 开通之后，Codex 的正确用法不是"在聊天框里多问几句代码问题"，而是把它作为一个可按验收标准驱动的软件工程 Agent 接入你的仓库与流程。

如果你只有一分钟，记住这四件事：

先用 codex exec --sandbox read-only 规划，再用可写模式执行；
把规范写进根目录的 AGENTS.md；
用 task.md 定义输入、目标、验收标准、约束四要素；
大任务切片，每个切片跑测试后提交，再进入下一个。

Codex 的上限不取决于 Plus 还是 Pro，而取决于你给它提供多少工程上下文、以及你是否愿意用验收标准和检查点去约束它。