Codex 快速上手核心指南
版本说明：本文中的功能点根据 OpenAI 官方 Codex 文档与 Help Center，于
2026-03-23核对。
1. 先把 Codex 当成什么
最容易用错 Codex 的地方，是把它只当成“另一个聊天框”。
更准确的理解是：
CLI里，它像一个能读仓库、能改代码、能跑命令的工程代理IDE 扩展里，它像一个贴着当前文件工作的结对开发者App里，它像一个可以并行推进多个项目和线程的任务调度台
如果你刚开始上手，最推荐的顺序是：
- 先学
CLI或IDE 扩展 - 学会给清晰上下文
- 学会先让它出计划
- 再进入
Worktree / Cloud / Subagents
2. 第一次不要直接让它大改仓库
最稳的开局不是“帮我重构整个项目”，而是先让它回答 4 个问题：
text
请先阅读当前项目结构，不要改代码。
告诉我：
1. 这是个什么技术栈
2. 入口文件在哪里
3. 本地应该先运行什么命令
4. 最适合拿来验证 Codex 是否正常工作的小改动是什么这样做的好处是：
- 你能先判断 Codex 有没有读懂项目
- 它会先暴露自己的理解，而不是直接乱改
- 后面哪怕要继续实现，风险也会小很多
3. 先学会 3 个基础动作
动作一：先给上下文
不要只说“修一下 bug”。
更好的说法是：
text
用户反馈点击提交后页面卡住。
相关目录在 src/pages/order 和 src/api/order。
请先找可能的原因，再给出修复计划。动作二：先让它给计划
复杂任务不要让 Codex 直接写。先要求它输出：
- 对问题的理解
- 预计修改的文件
- 验证方式
- 回归风险
动作三：结束前必须验证
做完之后，一定要求它说明：
- 实际改了什么
- 跑了哪些测试 / 构建
- 哪些还没验证
4. AGENTS.md 是 Codex 协作的基础设施
Codex 最值得尽早建立的习惯，不是某条提示词，而是维护 AGENTS.md。
一个最小例子：
md
# AGENTS.md
## Repository expectations
- Before finishing, run `npm run build`.
- Keep diffs small and reviewable.
- Do not hardcode secrets.
- Update docs when behavior changes.只要仓库里有这份文件，Codex 在开始工作前就会先读到这些长期规则。
5. 什么时候该用 Worktree
如果任务带这些特征，就优先开 Worktree：
- 风险较高
- 需要大面积试验
- 你不想污染当前工作区
- 你想让多个线程并行改不同方向
一个很实用的经验是：
- 小改动用
Local - 中等风险改动用
Worktree - 耗时长、你不想一直盯着的任务再考虑
Cloud