Codex 教程 · 第一个任务 / AGENTS.md · 第 3 篇
Codex 新手第一个任务:从打开项目到写好 AGENTS.md(附中文模板)
Codex CLI 新手实操:在项目里启动 Codex、让它读懂项目、做第一个小改动并审查,再用 /init 和 AGENTS.md 给 Codex 写项目规则,附中文 AGENTS.md 模板和常用斜杠命令。
本页目录
本文命令和数字整理自 OpenAI 官方文档(developers.openai.com/codex、OpenAI 帮助中心和 GitHub 上的 openai/codex 仓库),核对日期 2026-10-25(北京时间)。Codex 更新很快,遇到出入以官方页面为准。
前提:已经按Codex 安装教程装好,并按Codex 登录方式与套餐怎么选登录。
第一步:先留一个“后悔药”
官方建议在任务前后都做 Git 检查点,改坏了能退回去:
cd 你的项目目录
git status # 确认没有没提交的改动
git add -A && git commit -m "交给 Codex 之前"
还没用 Git 的项目,先 git init 再提交一次。Codex 打开一个有版本管理的目录时,默认用 Auto 权限;没有版本管理的目录,默认只读。
第二步:启动 Codex,先让它读懂项目
codex
第一个问题别急着让它写代码,先让它介绍项目:
介绍一下这个项目:目录结构、主要功能、怎么运行、怎么跑测试。
几个常用的斜杠命令:
| 命令 | 作用 |
|---|---|
/status |
看当前会话配置、工作目录、剩余额度 |
/model |
切换模型和推理强度 |
/permissions |
调整 Codex 能做什么(只读 / 自动 / 更高权限) |
/review |
审查改动,只给意见,不改你的文件 |
/init |
生成 AGENTS.md 脚手架 |
/mcp |
查看已连接的 MCP 服务 |
第三步:做一个小而明确的改动
好的第一个任务应该小、可验证。比如:
在 README 里补一段“本地运行”说明,命令以 package.json 里的 scripts 为准。
只改 README.md,改完告诉我改了哪几行。
一个好提示词通常包含 4 样东西:目标、范围(改哪些文件、别动哪些)、完成标准(比如“跑 npm test 全部通过”)、约束(比如“不要新增依赖”)。
Codex 改完后:
- 看它给的改动摘要和 diff。
- 输入
/review,让它自己再审一遍。 - 自己跑一遍项目或测试,确认没问题再提交。
默认权限下,Codex 可以在当前项目里读文件、改文件、运行命令;要改项目外的文件或者联网时,会停下来问你。新手不建议一上来就用
--yolo(无沙箱、无审批),官方也不推荐。
第四步:写一份 AGENTS.md
AGENTS.md 是给 Codex 看的“项目说明书”。Codex 每次开始工作前都会读它,所以你不用每次都重复“用 pnpm”“改完要跑测试”这类要求。
最快的方式:/init
在 Codex 里输入 /init,它会根据项目生成一份 AGENTS.md 草稿,你再改一改。
Codex 怎么找 AGENTS.md
- 全局:
~/.codex/AGENTS.md(对你所有项目生效)。有AGENTS.override.md时优先用 override。 - 项目:从项目根目录(一般是 Git 根目录)一路往下到当前目录,每一层找
AGENTS.override.md→AGENTS.md,每层最多用一个。 - 合并:从根往下拼接,离当前目录越近的规则越靠后,优先级越高。
- 合并后总大小默认上限 32 KiB(
project_doc_max_bytes),超了会被截断。空文件会被跳过。
中文模板(按你的项目改)
# AGENTS.md
## 项目简介
- 这是一个 xxx 项目,技术栈:xxx。
## 常用命令
- 安装依赖:xxx
- 本地运行:xxx
- 运行测试:xxx
## 工作约定
- 改完代码后运行测试,测试不过不要说“完成”。
- 新增依赖前先问我。
- 不要修改 xxx 目录。
- 回复用中文,改动要列出改了哪些文件。
检查 Codex 有没有读到
codex --ask-for-approval never "Summarize the current instructions."
它应该会复述你写在 AGENTS.md 里的内容。改了 AGENTS.md 之后要重新启动 Codex 才会生效(每次启动时重新读取,不需要手动清缓存)。
小提醒:AGENTS.md 越长,每次消耗的额度越多。大项目可以把规则拆到各个子目录里。
进阶:接着上次继续、在脚本里用
codex resume:回到之前的会话继续。codex exec "任务描述":非交互运行,适合脚本和 CI。
参考资料
常见问题
第一个任务做什么比较好?
先让 Codex 介绍项目,再做一个小而可验证的改动,比如补文档、修一个小 bug、加一个测试。别一上来就让它重构整个项目。
AGENTS.md 放在哪里?
个人通用规则放 ~/.codex/AGENTS.md;项目规则放在项目根目录;某个子目录有特殊规则,就在那个目录里再放一个 AGENTS.md 或 AGENTS.override.md。
改了 AGENTS.md 没生效?
重新启动 Codex。还不行就检查是不是在正确的目录启动、文件是不是空的、上层有没有 AGENTS.override.md 覆盖了它。
Codex 改坏了怎么办?
这就是为什么要先提交 Git 检查点。用 git diff 看改了什么,用 git checkout 或 git reset 退回到提交前的状态。
/review 会改我的代码吗?
不会。官方说明 /review 只报告按优先级排序的问题,不修改工作区。