Codex 入门 约 4 分钟

Codex 项目上下文：AGENTS.md 写什么、config.toml 边界在哪

Codex 每次运行只读一次指令链。讲清全局与项目 AGENTS.md 的发现顺序、config.toml 的信任边界，以及如何把上下文控制在真正有用的几百字里。

作者 Zenty 发布于

  • Codex
  • AGENTS.md
  • 上下文工程
  • 配置
本页目录

目标：让它每次都带上正确的项目常识

Codex 不会自动记住你上周说过的约定。每次运行开始时，它按固定顺序读一组指令文件，拼成“上下文链”，然后才开始干活。理解这条链，比在对话里反复重复要求有效得多。

本文的目标是产出一份 30 行以内的 AGENTS.md，并让它在新的会话里确实生效：不问就知道怎么跑测试、哪些目录不能碰。

前置条件

  • 已经用 Codex 完成过至少一次小改动（见 /articles/codex-first-task/）
  • 仓库根目录存在，且你能区分“个人偏好”和“项目规则”

发现顺序：先全局，再项目

官方文档给出的顺序可以概括成三层：

  1. 全局层：在 Codex home（默认 ~/.codex，可用 CODEX_HOME 改变）里，先找 AGENTS.override.md，没有才读 AGENTS.md。这一层只用第一个非空文件。
  2. 项目层：从启动目录开始，向上走到项目边界，读取沿途的项目指令文件。
  3. 合并：多层内容一起进入上下文，越靠近当前工作目录的规则越具体。

两个实践含义：

  • AGENTS.override.md 是给你临时压制全局规则用的，比如在客户项目里禁用个人习惯；它不是第二个配置文件。
  • 链只在启动时构建一次。改完 AGENTS.md 要开新会话才生效，别在旧会话里怀疑人生。

文档还提到项目指令有字节上限、超出部分会被截断，具体默认值随版本变化。写之前用 codex --help 或当前版本的配置文档核对上限，不要假设“写多少都读得进去”。

写什么：四类信息，别的都别写

一份有效的 AGENTS.md 只包含它无法从代码里推断出来的东西：

# 项目约定

## 常用命令
- 安装：npm ci
- 测试：npm test（单文件：node --test src/foo.test.js）
- 类型检查：npx tsc --noEmit
- 构建：npm run build

## 代码约定
- ESM，不用 CommonJS；导入使用相对路径 + 显式扩展名
- 错误处理统一抛出 Error 子类，不返回 { ok: false }
- 不新增运行时依赖，除非先说明理由

## 边界
- 不要修改 src/generated/**，由脚本生成
- 不要改动 .github/workflows/**，除非任务明确要求
- 提交前必须跑 npm test

## 审阅期望
- 改动超过 3 个文件时，先列计划再动手

这四类分别是：怎么验证（命令）、风格约束（无法从代码推断的选择）、禁区（防止误伤）、协作方式（计划先行）。它们都属于“说了就省一轮返工”的信息。

不该写什么

  • 能从代码读出来的事实。 “本项目使用 TypeScript”“入口是 src/index.ts”，它自己看得到，写进去只占预算。
  • 一次性的任务说明。 “把登录页改成蓝色”属于对话内容，不属于仓库规则。
  • 重复的长篇规范。 引用外部链接或单独文档，而不是把 500 行风格指南粘进来。
  • 与仓库不符的愿望。 写着 npm test 但实际用 pnpm test，比不写更糟——它会自信地跑错命令。

判断标准很简单：这句话在新会话、新任务里仍然成立吗？不成立就删。

config.toml 与信任边界

Codex 的用户级配置在 ~/.codex/config.toml，项目可以在仓库里放 .codex/config.toml 做覆盖。关键行为是：项目级 .codex/ 目录只在项目被信任时才加载。这是防止“克隆一个仓库就执行别人写的配置”的基本防线。

所以：

  • 个人偏好（默认模型、界面选项）放用户级；
  • 项目必需的配置放 .codex/config.toml，并且接受“未受信任时不生效”这个前提；
  • 首次打开陌生仓库，先读一遍它的 .codex/config.toml 和 AGENTS.md，再决定是否信任。

同理，沙箱默认是只读的，直到你把工作目录标记为可信，才会升级到允许在工作区内写入的预设。这个顺序不要为了省事反过来。

验证它真的生效

开一个新会话（不是在旧会话里），问一个只能用 AGENTS.md 回答的问题：

本项目跑测试用哪条命令？有没有不能修改的目录？

如果它答出了 npm test 和 src/generated/**，说明链加载成功。再让它做一次小改动，观察它是否主动跑测试——这比任何自述都可靠。

验收标准

  1. 新会话能正确回答测试命令和禁区；
  2. AGENTS.md 控制在 30～60 行，没有可从代码推断的内容；
  3. 项目级配置写在 .codex/config.toml，且你清楚它在未受信任时不生效；
  4. 有一次真实的“因为它写了规则，所以少返工一轮”的经历。

常见错误

  • 把 AGENTS.md 写成项目百科，结果关键命令被截断；
  • 在旧会话里验证修改，误判为“没生效”；
  • 把密钥、内网地址写进 AGENTS.md 并提交；
  • 用 AGENTS.override.md 存放长期项目规则，团队其他人根本看不到。

上下文里放什么，本质上是预算分配问题。Agent 侧同理，见 /articles/agent-tool-loop/；如果你还想把重复流程固化成可复用资产，接着读 /articles/skills-design/。

参考来源