Codex 教程 · 第一个任务 / AGENTS.md · 第 3 篇

Codex 新手第一个任务:从打开项目到写好 AGENTS.md(附中文模板)

Codex CLI 新手实操:在项目里启动 Codex、让它读懂项目、做第一个小改动并审查,再用 /init 和 AGENTS.md 给 Codex 写项目规则,附中文 AGENTS.md 模板和常用斜杠命令。

作者 Niko约 5 分钟
本页目录

本文命令和数字整理自 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 改完后:

  1. 看它给的改动摘要和 diff。
  2. 输入 /review,让它自己再审一遍。
  3. 自己跑一遍项目或测试,确认没问题再提交。

默认权限下,Codex 可以在当前项目里读文件、改文件、运行命令;要改项目外的文件或者联网时,会停下来问你。新手不建议一上来就用 --yolo(无沙箱、无审批),官方也不推荐。

第四步:写一份 AGENTS.md

AGENTS.md 是给 Codex 看的“项目说明书”。Codex 每次开始工作前都会读它,所以你不用每次都重复“用 pnpm”“改完要跑测试”这类要求。

最快的方式:/init

在 Codex 里输入 /init,它会根据项目生成一份 AGENTS.md 草稿,你再改一改。

Codex 怎么找 AGENTS.md

  1. 全局:~/.codex/AGENTS.md(对你所有项目生效)。有 AGENTS.override.md 时优先用 override。
  2. 项目:从项目根目录(一般是 Git 根目录)一路往下到当前目录,每一层找 AGENTS.override.md → AGENTS.md,每层最多用一个。
  3. 合并:从根往下拼接,离当前目录越近的规则越靠后,优先级越高。
  4. 合并后总大小默认上限 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 只报告按优先级排序的问题,不修改工作区。