Codex使用教程：通过AGENTS.md编写自定义说明，让AI按你的规则工作

Codex使用教程：通过AGENTS.md编写自定义说明，让AI按你的规则工作

大家好 这里是「代码简单说」,欢迎大家关注同名公众号,不定时更新更多实用有趣的教程 也欢迎大家在评论区一起讨论交流!~

SEO关键词：Codex下载、Codex客户端、Codex教程、AGENTS.md使用方法、Codex配置指南、Codex自定义规则、AI编程工具、Codex客户端安装

最近在体验 OpenAI 推出的 Codex 客户端 时，我发现很多开发者虽然已经开始使用 Codex 辅助开发，但却不知道一个非常重要的功能：

AGENTS.md

这个文件可以理解为：

给 Codex 制定工作规范和团队规则的配置文件。

配置完成后，无论是代码生成、代码审查、单元测试还是项目维护，Codex 都会优先遵守你预先定义好的规则。

对于团队协作来说，这个功能非常实用。

例如：

• 统一代码规范
• 统一测试流程
• 统一依赖安装方式
• 统一提交规范
• 统一项目文档要求

今天详细介绍一下 Codex 如何使用 AGENTS.md 实现自定义行为控制。

Codex客户端下载

如果还没有安装 Codex，可以通过下面的网站获取客户端：

官方文档：

什么是AGENTS.md

AGENTS.md 本质上是一个 Markdown 文件。

Codex 启动时会自动读取它。

你可以在里面定义：

# 工作规范

– 修改代码后必须执行测试
– 优先使用 pnpm
– 新增依赖必须先确认
– 所有接口必须补充注释

当 Codex 开始工作时：

codex

它会先读取这些规则。

然后再执行用户的任务。

因此：

AGENTS.md = AI团队规范文件

Codex如何发现AGENTS.md

很多人以为 Codex 只会读取当前目录。

实际上并不是。

Codex 会按照固定规则查找配置。

V1 查找流程

全局配置
↓
项目根目录
↓
子目录
↓
当前工作目录

搜索顺序：

AGENTS.override.md
↓
AGENTS.md
↓
备用文件名

优先级最高的是：

AGENTS.override.md

如果存在：

AGENTS.md
将被忽略

Codex配置层级原理

假设项目结构如下：

project
│
├─ AGENTS.md
│
├─ services
│ │
│ ├─ search
│ │
│ └─ payments
│ │
│ ├─ AGENTS.md
│ └─ AGENTS.override.md

当在：

services/payments

目录运行 Codex 时。

最终加载顺序：

~/.codex/AGENTS.md
↓
project/AGENTS.md
↓
services/payments/AGENTS.override.md

因为：

AGENTS.override.md
优先级高于
AGENTS.md

所以：

services/payments/AGENTS.md
不会被读取

创建全局AGENTS.md

V1 创建配置目录

Linux/macOS：

mkdir -p ~/.codex

Windows：

mkdir $HOME\\.codex

V2 创建全局规则

文件：

~/.codex/AGENTS.md

内容：

# 工作规范

– 修改JavaScript后执行npm test
– 优先使用pnpm
– 新增生产依赖需要确认
– 提交前执行lint

保存后：

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

如果配置成功。

Codex会输出类似：

当前规则：

1. 修改JS文件后执行npm test
2. 优先使用pnpm
3. 新增依赖需要确认

说明已经生效。

使用AGENTS.override.md覆盖全局规则

有时候项目需要特殊规则。

例如：

支付系统

要求：

不能使用npm test

而必须：

make test-payments

此时可以创建：

AGENTS.override.md

示例：

# 支付系统规范

– 使用make test-payments
– 修改支付逻辑必须增加测试
– 更换API Key前通知安全团队

这样：

当前目录规则
覆盖
全局规则

项目级AGENTS.md配置

推荐在仓库根目录建立统一规范。

例如：

# 仓库规范

– PR前运行npm run lint
– 修改接口时同步更新docs
– 所有新增API必须补充测试

这样整个项目组都会遵循同一套规则。

自定义备用文件名

很多团队已经存在：

TEAM_GUIDE.md

或者：

.agents.md

不想重新命名。

Codex支持配置备用文件名。

修改：

~/.codex/config.toml

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

project_doc_max_bytes = 65536

配置后搜索顺序变成：

AGENTS.override.md
↓
AGENTS.md
↓
TEAM_GUIDE.md
↓
.agents.md

这样旧项目无需迁移。

Codex也能识别。

配置文件大小限制

默认情况下：

project_doc_max_bytes = 32768

即：

32KB

超过后：

后续说明文件不会继续加载

如果团队规范比较多。

建议调整：

project_doc_max_bytes = 65536

或者：

project_doc_max_bytes = 131072

使用CODEX_HOME切换配置

某些场景下：

• 多团队
• 多项目
• 自动化账号

需要独立配置。

可以通过：

CODEX_HOME=$(pwd)/.codex codex

指定新的配置目录。

例如：

project
│
├─ .codex
│ ├─ AGENTS.md
│ └─ config.toml

这样：

只使用当前项目的配置

不会读取默认：

~/.codex

验证AGENTS.md是否生效

方法1 查看当前规则

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

输出：

当前加载规则…

即可确认。

方法2 查看活动文件

codex \\
–cd services/payments \\
–ask-for-approval never \\
"Show which instruction files are active."

输出：

~/.codex/AGENTS.md
project/AGENTS.md
services/payments/AGENTS.override.md

说明加载成功。

方法3 查看日志

日志目录：

~/.codex/log/

常见文件：

codex-tui.log

或者：

session-xxx.jsonl

可以直接查看实际加载情况。

常见问题排查

问题1 AGENTS.md没有生效

检查：

codex status

确认：

当前工作目录
是否为正确项目

同时确认：

AGENTS.md不是空文件

问题2 规则不正确

优先检查：

AGENTS.override.md

因为它拥有最高优先级。

很多情况下问题都来自这里。

问题3 备用文件不生效

检查：

project_doc_fallback_filenames

是否拼写正确。

修改后记得重启 Codex。

问题4 规则被截断

检查：

project_doc_max_bytes

是否过小。

必要时拆分文件。

例如：

AGENTS.md
↓
backend/AGENTS.md
↓
frontend/AGENTS.md

进行分层管理。

推荐的团队级AGENTS.md模板

前端项目可以直接参考：

# 团队规范

## 包管理

– 优先使用pnpm
– 禁止npm install

## 代码规范

– 必须通过eslint
– 必须通过prettier

## 测试规范

– 修改代码后执行npm test

## 文档规范

– 接口修改同步更新docs

## 提交规范

– 使用Conventional Commits

## 安全规范

– 禁止提交密钥
– 禁止提交.env

对于 Vue、React、Node 项目都比较适用。

总结

AGENTS.md 可以说是 Codex 最值得学习的功能之一。

相比每次都向 AI 重复说明：

请使用pnpm
请运行测试
请遵循团队规范
请补充文档

更好的方式是：

把规则写进AGENTS.md

这样 Codex 每次启动都会自动读取。

核心机制总结如下：

对于团队开发而言，AGENTS.md 不仅能提高 AI 生成代码的一致性，还能把项目经验沉淀为可复用的协作规范，让 Codex 真正成为符合团队习惯的 AI 开发助手。