Codex 使用指南：快速上手、5 个实用技巧与最佳实践
Codex 与其说是“代码补全工具”，不如说是一个可以读代码、改文件、跑命令、做审查的 AI coding agent。对多数搜索“codex 用法”的开发者来说，关键不只是安装，而是明确哪些工作交给它，哪些环节必须保留人工把关。
先说结论：Codex 在 小范围、目标明确 的任务里最稳定。相比“把整个仓库都修好”这种模糊指令，明确给出目标文件、完成标准和约束条件，产出质量更高，后续 review 也更省力。
如果你想先看更大的 AI coding 背景，可以先读 AI Coding 主题页 和 2026 年最佳 Vibe Coding 工具。如果你正在比较工具差异，建议配合阅读 Codex vs Claude Code Skills。
快速结论：Codex 应该怎么用最顺手？
| 你的场景 | 建议入口 | 原因 |
|---|---|---|
| 以终端和仓库为中心开发 | CLI | 路径最短，适合“提需求 -> 修改 -> 测试 -> 审查”闭环 |
| 经常并行做任务，重视 diff 可视化 | App | review pane、worktree、handoff、automations 更完整 |
| 希望尽量留在当前编辑器里 | IDE extension | 不改主工作流，接入成本最低 |
建议用下面的顺序上手：
- 先选 CLI 或 App 其中一个，不要一上来两边都用。
- 连续完成 3 个小任务闭环。
- 熟悉
AGENTS.md与 review 流程。 - 再进阶到 skills 与 subagents。
多数团队卡住的第一步就是“该从哪里开始”。CLI 上手最快，App 在审查与并行协作上更强，IDE extension 则适合不想切换开发环境的场景。
Codex 到底是什么
Codex 是 OpenAI 的 coding agent。在 CLI 中，它可以读取本地仓库、编辑文件、执行命令；在 App 中，它还提供更强的差分审查、worktree 并行任务和后台任务能力；IDE extension 则把这些能力带到编辑器工作流里。
一个常见误区是：把 Codex 当成“会写代码的聊天窗口”。这样只能用到一部分能力。它更适合这些任务：
- 快速读懂陌生代码库
- 完成小到中等规模改动
- 定位问题根因并修复 bug
- 结合 test、lint、build 验证改动
- 做结构化 code review 与差分收敛
- 把重复工作沉淀成 skills 与 automations
实操里，Codex 更像“嵌入工程流程的执行代理”，而不是一次性生成结果的模型输出。
Codex 快速上手
1. 安装 CLI 并启动第一轮会话
Codex CLI 官方快速安装流程：
npm i -g @openai/codex
codex首次启动后，用 ChatGPT 账号或 API key 完成认证。第一轮不要直接上大任务，建议先让它做低风险扫描。
例如：
请总结这个仓库的目录结构和开发流程。
先不要修改任何文件，只做调研。这样可以先看清 Codex 对仓库的理解深度和输出粒度。
2. 第二轮只给一个可审查的小改动
第二个任务要刻意收窄：
只修改这个组件里的文案。
改动范围限制在一个文件内，完成后总结 diff。Codex 能处理复杂任务，但上手阶段“范围可控”比“功能大而全”更重要。
3. 第三轮把验证环节也加进去
Codex 的高价值在于不只“改代码”，而是“改完并验证”：
修复这个失败的测试。
修复后只运行相关测试，并用 3 行说明改了什么。把“编辑 + 验证”变成固定动作，稳定性会明显提升。
把 Codex 固定在 read -> plan -> edit -> test -> review 闭环里，准确率和可控性会明显提高。中间的人工校验节点代表一条底线：只接受你能解释清楚的改动。
核心使用模式
先让它解释，再让它动手
在现有仓库中，这个顺序通常更稳：
请先总结这个模块的职责和依赖关系。
然后给出两个最小改动方案。
先不要开始编辑。多花一轮确认理解，通常比返工错误补丁更便宜。
每个任务都写清“完成标准”
完成条件越清楚，输出越稳定。
弱提示词：
优化这个页面。强提示词：
请缩短这个页面的导语。
让首屏同时回答“这是什么”和“为什么重要”。
保留现有 H2 结构，不要新增代码块。把 diff 当成审查对象，而不是自动接收结果
在 App 的 review pane 里，你可以同时查看 Codex 改动与本地未暂存改动，按 staged / unstaged 管理，并通过行内评论回流反馈。相比一句“再改一下”，这种方式可控性更高。
如果你主要在 App 中工作，建议继续阅读 Parallel Code Agents，它和 Codex 的 worktree + review 工作流直接对应。
5 个实用技巧
Tip 1：先要方案，再要实现
把第一句从“直接实现”换成“先给计划”，通常能减少无效往返。
先用 3 步给出修复方案。
确认后再执行实现。这个方法对 bug 修复、重构、内容更新都有效。
Tip 2：每次都写清范围与非目标
模糊任务会得到模糊输出。每个任务至少包含三点：
- 允许改哪里
- 目标是什么
- 明确不改什么
即使短指令也可以很清晰：
只修改 `components/header.tsx`。
目标是缩小导航间距。
不要改业务逻辑，也不要新增依赖。Tip 3：把长期规则沉淀到 AGENTS.md
把同一批约束每次都写在 prompt 里，成本高且容易淹没任务本身。Codex 官方 best practices 也建议把持久规则放进 AGENTS.md。
至少建议包含：
- 仓库结构
- build / test / lint 命令
- 代码规范
- PR 要求
- 完成定义
CLI 的 /init 可以快速生成 AGENTS.md 雏形，但需要结合团队实际流程调整，不要直接照搬。
推荐的分层是：单次任务放 prompt，仓库常驻规则放 AGENTS.md，可复用流程放 skills，周期性任务交给 automations。这样职责边界更清楚。
Tip 4：把 subagents 用在可并行任务上
截至 2026 年 3 月 16 日，Codex 的 subagent workflows 默认开启，并在 App 与 CLI 中可见。你显式要求时，Codex 可以拉起多个专业 subagent 并汇总结果。
最适合的场景：
- 大仓库探索
- 多视角 PR 审查
- 方案比较
- 多步骤规划
例如做 PR review：
请对这个分支相对 main 做 review。
把 security、bugs、test flakiness、maintainability 分别交给不同 subagent。
最后返回一份汇总结论。这样可以把“探索、验证、汇总”拆开处理，避免单条长推理链过载。
你可以把它理解为一个主 agent，按 security、bugs、tests、maintainability 等视角并行分派，再收敛成一份可执行结论。
注意边界：
- 不显式要求时，subagent 不会自动拉起
- 每个 subagent 都会独立消耗模型与工具预算
- 强耦合的单线程改动，硬拆并行可能提高合并成本
并行不是目的。任务可拆，才值得并行。
Tip 5：改完必须带 review 或测试
Codex 的价值不在“写得快”，而在“改得快且能验证”。
每轮改动至少要求一项：
- 运行相关测试
- 跑一次
/review做二次检查
App 的行内评论能显著缩短反馈闭环。
最佳实践
1. 任务规模逐级放大
不要一上来就给大任务。推荐这条阶梯：
- 只调研
- 单文件改动
- 小 bug 修复
- 修复 + 测试
- 多文件改动
- subagents + automation
这样能更早暴露仓库约束，减少后期返工。
2. 权限与沙箱先收紧，再按需放开
Codex 官方实践建议先用更保守的默认设置，再根据实际需要逐步放宽。这样失败成本更低。
尤其是共享仓库或接近生产环境的场景，务必把人工审查保留在环路里。
3. 持久规则放配置，不要反复塞进 prompt
当 prompt 里塞入大量固定规则时，任务核心反而会被稀释。更稳妥的分工是：AGENTS.md 放长期规则，skills 放复用流程，automations 处理定时任务。
Codex 的 skill 以 SKILL.md 为中心，配合 references 与可选脚本，很适合沉淀重复性的评审和发布流程。
4. 并行线程涉及同仓库时，优先用 worktree
同一仓库多线程并行时，worktree 能显著降低冲突。Codex App 的 worktree 机制允许你在不污染当前工作区的前提下并行推进任务。
典型场景：
- 一条线程修 bug，另一条线程改文档
- 后台任务持续运行，同时手工任务继续推进
- 在不污染主工作区的情况下验证独立改动
没有 worktree 纪律时，重叠文件改动会很快变得难以审查和合并。
5. 不“全盘接收”，只“挑选可解释改动”
不要把 Codex 输出当成自动合并输入。用 stage、revert、inline comment 逐步收敛补丁，结果会更稳定。
长期有效的操作模型不是 autopilot，而是“高速草稿伙伴 + 验证伙伴”。
谁更适合这样使用 Codex
初学者
先用解释和修复型任务，不要直接追求全自动生成：
- “这个函数在做什么？”
- “这个报错的根因是什么？”
- “给我一个最小且安全的修复方案。”
这样既能学到东西，也能推进工作。
独立开发者
Codex 非常适合一人项目：规划、改动、测试、审查可以放在一个闭环里。需要并行探索或多视角 review 时，subagents 尤其有用。
团队
团队场景下，稳定性更多取决于共享规范，而不是个人 prompt 技巧。优先建设 AGENTS.md、review 机制、worktree 纪律和可复用 skills。
哪类人不太适合这套用法？
如果目标是“模糊指令一扔，结果直接全接收”，这套流程并不合适。Codex 在“意图清晰 + 差分审查 + 规则迭代”的模式下效果最好。
FAQ
Codex 对新手友好吗？
友好。建议从代码解释、小修复和调试支持开始，而不是直接交给它做大规模自治实现。
应该先用 CLI 还是 App？
终端工作流优先选 CLI；更看重差分可视化和并行任务管理选 App。拿不准时，先用 CLI 建立基本闭环，再扩展到 App。
什么时候适合用 subagents？
当任务可以按视角拆分时最合适，例如探索、审查和方案比较。强耦合的单线程改动，不建议强行并行化。
AGENTS.md 和 skills 应该怎么分工？
AGENTS.md 负责仓库级规则与协作约定，skills 负责可复用的任务流程。前者是“长期规范”，后者是“可执行手册”。
Codex 的改动可以不审查直接接收吗？
不建议。相关测试和 diff review 应该是必经门槛。Codex 可以很快，但最终采纳仍需人工决策。
Related Guides
- AI Coding 主题页
- 并行代码智能体指南
- 用 Claude Agent SDK 构建 Claude Code 风格 Agent
- 2026 年最佳 Vibe Coding 工具
- Codex vs Claude Code Skills