AGENTS.md 项目说明与 codex exec 自动化

你将得到什么

• 一份提交进仓库的 AGENTS.md，以及一份对所有项目生效的全局 ~/.codex/AGENTS.md
• 会验证 Codex 实际加载了哪些指令文件、按什么顺序合并
• 能用 codex exec 做管道输入、改文件、输出 JSONL 事件流、按 JSON Schema 输出结构化结果、续接上一次任务
• 一份可直接改用的 GitHub Actions 配置思路，以及 API Key 的安全用法

核心事实（先记住）

步骤 1：用 /init 生成 AGENTS.md

AGENTS.md 是 Codex 每次开工前都会读的「项目说明书」。在练习项目中启动 Codex：

cd ~/kun-codex-demo
codex

在会话中输入：

/init

对照结果：Codex 读取项目后，在仓库根目录生成 AGENTS.md 草稿，通常包含项目结构、测试命令（python3 -m unittest）和代码风格等小节。输入 /exit 退出。

官方建议把生成的草稿改成符合你仓库的约定再提交。为了让后面的对照结果确定，把它替换成下面这份（规则要具体、可验证）：

cat > AGENTS.md <<'EOF'
# AGENTS.md

## Repository expectations

- Run `python3 -m unittest` after changing any Python file.
- Every bug fix must come with a new or updated test.
- Do not add third-party dependencies.
- Reply to the user in Simplified Chinese.
EOF
git add AGENTS.md && git commit -qm "add AGENTS.md"

步骤 2：验证 Codex 读到了规则

官方给出的验证方式是直接问它（--ask-for-approval never 表示整个过程不弹审批）：

codex --ask-for-approval never "Summarize the current instructions."

对照结果：Codex 用中文复述上面四条规则（不加依赖、改完跑 unittest、修 Bug 必须带测试等）。复述完后输入 /exit 退出。

Codex 在每次启动（TUI 每次新会话）时重建指令链，没有缓存需要清理。改完 AGENTS.md 重新启动即可生效。

步骤 3：全局说明与目录级覆盖

全局：对所有仓库生效

mkdir -p ~/.codex
cat > ~/.codex/AGENTS.md <<'EOF'
# ~/.codex/AGENTS.md

## Working agreements

- Show the exact commands you ran in your final answer.
- Ask before deleting any file.
EOF

子目录：只对某块代码生效

在练习项目里建一个 scripts/ 目录，并给它单独的规则：

cd ~/kun-codex-demo
mkdir -p scripts
cat > scripts/AGENTS.override.md <<'EOF'
# scripts/AGENTS.override.md

## Scripts rules

- Shell scripts here must be POSIX sh and pass `sh -n`.
EOF
codex --cd scripts --ask-for-approval never \
  "List the instruction sources you loaded."

对照结果：Codex 按顺序列出三处来源——先全局 ~/.codex/AGENTS.md，再仓库根目录 AGENTS.md，最后 scripts/AGENTS.override.md。

官方的发现规则如下，出现「规则没生效」时按此排查：

1. 全局：在 ~/.codex（或 CODEX_HOME）中，AGENTS.override.md 存在就只读它，否则读 AGENTS.md。
2. 项目：从 Git 根目录一路走到当前目录，每层依次找 AGENTS.override.md、AGENTS.md，每层最多取一个文件；空文件会被跳过。
3. 合并：从根到当前目录依次拼接，越靠近当前目录的越靠后、优先级越高；总量到 32 KiB 后不再追加。

仓库已有别的说明文件名（如 TEAM_GUIDE.md）时，可在 ~/.codex/config.toml 里加入备选名并调大上限：

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

步骤 4：codex exec 入门

codex exec 不打开交互界面：进度输出到 stderr，只有最终回答输出到 stdout，所以可以直接重定向或接管道。

cd ~/kun-codex-demo
codex exec "summarize the repository structure in 3 bullets" \
  | tee summary.md

对照结果：终端先滚动显示 Codex 读取文件的过程，最后打印三条要点；summary.md 里只有这三条要点，不含过程日志。

不想在磁盘上留下会话记录时加 --ephemeral：

codex exec --ephemeral "list the public functions in calc.py"

步骤 5：把别的命令输出喂给它

同时给出提示词参数和管道输入时，提示词是指令，管道内容作为附加上下文：

git log --oneline -5 \
  | codex exec "write short release notes for these commits" \
  > release-notes.md
cat release-notes.md

对照结果：release-notes.md 里是根据 init demo、add AGENTS.md 等提交整理的简短更新说明（因为 AGENTS.md 要求中文，正文为中文）。

整段提示词都来自管道时，用 - 显式表示从 stdin 读：

printf 'Explain this test output in 2 bullets:\n\n%s\n' \
  "$(python3 -m unittest 2>&1)" | codex exec -

步骤 6：允许它改文件

codex exec 默认是只读沙箱，直接让它改代码只会得到建议、不会落盘。需要写入时显式放开到工作区：

codex exec --sandbox workspace-write \
  "add median(nums) to calc.py (return 0 for an empty list) with tests"

对照结果：calc.py 新增 median()，test_calc.py 新增对应测试；依照 AGENTS.md，它会自己跑 python3 -m unittest 并在最终回答里给出所用命令。自行核对：

git status --short
python3 -m unittest

应看到 calc.py、test_calc.py 为已修改（ M），另有前几步生成的 summary.md、release-notes.md 和 scripts/ 显示为未跟踪（??）；测试输出 OK。确认无误后自己提交：git commit -am "add median"。

官方提醒：danger-full-access 只在隔离的 CI Runner 或容器里用；旧脚本里的 --full-auto 已弃用，会打印警告，请改成 --sandbox workspace-write。

步骤 7：机器可读的 JSONL 事件流

codex exec --json "summarize the repo structure" > events.jsonl
jq -r '.type' events.jsonl | sort | uniq -c

对照结果：每行一个 JSON 事件，类型包括 thread.started、turn.started、item.started、item.completed、turn.completed（失败时为 turn.failed / error）。官方示例中的几行：

{"type":"thread.started","thread_id":"0199a213-..."}
{"type":"turn.started"}
{"type":"item.completed","item":{"type":"agent_message","text":"..."}}

只取最终回答：

jq -r 'select(.type=="item.completed" and .item.type=="agent_message")
  | .item.text' events.jsonl

turn.completed 事件里的 usage 字段给出本次输入、缓存、输出的 token 数，可用来做成本统计。只需要最终回答写文件时，用 -o <文件>（--output-last-message），它写文件的同时仍会打印到 stdout。

步骤 8：按 JSON Schema 输出结构化结果

下游脚本需要稳定字段时，用 --output-schema。先写一个 Schema（官方示例）：

cat > schema.json <<'JSON'
{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}
JSON
codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json
jq . project-metadata.json

对照结果（project_name 的取值以模型判断为准）：

{
  "project_name": "kun-codex-demo",
  "programming_languages": ["Python"]
}

步骤 9：两段式任务与续接

codex exec "review calc.py for edge cases, do not edit files"
codex exec resume --last "write a test for the first edge case you found"

对照结果：第二条命令接着第一条的上下文继续工作，无需重复说明。--last 只在当前目录的会话里选最近一个，加 --all 可跨目录；也可以用 codex exec resume <SESSION_ID> 指定会话。注意第二条仍是默认只读沙箱，要落盘请加 --sandbox workspace-write。

不在 Git 仓库里时 codex exec 会拒绝运行；确认环境安全后才用 --skip-git-repo-check 跳过。

步骤 10：放进 CI 时的安全做法

本地或自建 Runner：只给需要的那一次调用设置 Key，不要导出成整个任务的环境变量：

CODEX_API_KEY="sk-..." codex exec --json "triage open bug reports"

GitHub Actions：官方建议直接用 openai/codex-action@v1，而不是自己装 CLI 再把 Key 传给 shell 步骤；它会安装 Codex、启动 Responses API 代理来减少 Key 暴露，再按你给的权限运行 codex exec。核心写法：

- uses: actions/checkout@v5
  with:
    persist-credentials: false
- name: Run Codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt-file: .github/codex/prompts/review.md
    sandbox: read-only
    output-file: codex-output.md

官方安全要点：

• 跑 Codex 的 job 只给 contents: read；需要写仓库或发 PR 评论的步骤放到另一个不拿 Key 的 job
• 不要把 OPENAI_API_KEY / CODEX_API_KEY 设成会运行仓库代码的 job 级环境变量
• 保持默认 safety-strategy: drop-sudo；Windows Runner 只能用 unsafe，多租户 Runner 切勿如此
• 对来自 PR、提交信息、Issue 的文本做清洗，防提示词注入；把 Codex 放在 job 的最后一步

完整的「CI 失败自动出修复 PR」工作流见官方 Non-interactive mode 页面的 Autofix 示例。

本课检查清单

• 仓库根目录有已提交的 AGENTS.md，Codex 能复述其中规则
• codex --cd scripts ... 能按「全局 → 根目录 → scripts」顺序列出指令来源
• 用 codex exec 生成过 summary.md 与 release-notes.md
• 用 --sandbox workspace-write 让它加了 median() 且测试通过
• events.jsonl 与 project-metadata.json 都能用 jq 解析

常见问题

到这里，你已经能在终端里交互使用 Codex，也能把它写进脚本与 CI。想继续深入，可以看官方的 Code review、MCP 与 Subagents 文档。