Codex使用教程：用AGENTS.md编写自定义说明
来源：互联网 2026-06-29 06:32:10AGENTS.md是Codex的工作手册，通过Markdown文件定义规则，实现代码规范、测试流程等统一。支持全局配置、项目级覆盖及子目录局部覆盖，可设置备用文件名和大小限制，通过CODEX_HOME切换多配置环境，显著提升团队协作效率。
最近在体验OpenAI推出的Codex客户端时，发现不少开发者虽然已经在用它辅助编程，却错过了一个能让效率大幅提升的核心功能。
AGENTS.md
长期稳定更新的攒劲资源： >>>点此立即查看<<<
简单来说，这个文件就像一份给AI的“工作手册”。一旦配置好，无论是在代码生成、代码审查、单元测试还是项目维护等环节，Codex都会优先遵守你预先设定好的规则。
对于团队协作，这个功能的威力尤为显著。比如，你可以用它来统一：
- 代码规范
- 测试流程
- 依赖安装方式
- 提交规范
- 项目文档要求
今天，我们就来深入聊聊，如何通过AGENTS.md文件，让Codex完全按照你的节奏来工作。
Codex客户端下载
如果你还没有安装Codex，可以通过这个网站获取客户端：
| 名称 | 地址 |
|---|---|
| Codex客户端下载 | https://codexdown.cn/ |
官方文档里也有详细的说明：
| 文档 | 地址 |
|---|---|
| AGENTS.md说明 | https://codexdown.cn/docs/configuration/agents/ |
什么是AGENTS.md
AGENTS.md本质上就是一个Markdown文件，Codex在启动时会自动读取它。你可以在里面定义各种规则，比如：
# 工作规范
- 修改代码后必须执行测试
- 优先使用 pnpm
- 新增依赖必须先确认
- 所有接口必须补充注释
当Codex开始工作时，它会先去“翻阅”这份手册，然后再执行你的任务。所以，你的规则就是它的最高行动指南。
Codex如何发现AGENTS.md
很多人以为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 的优先级最高，所以：
services/payments/AGENTS.md 不会被读取
创建全局AGENTS.md
V1 创建配置目录
对于Linux/macOS系统：
mkdir -p ~/.codex
对于Windows系统：
mkdir $HOME/.codex
V2 创建全局规则
创建文件：
~/.codex/AGENTS.md
在里面写入你想要的全局规范：
# 工作规范
- 修改Ja vaScript后执行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配置
一个更推荐的做法是在仓库的根目录建立一个统一的 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 环境变量来指定一个新的配置目录。
CODEX_HOME=$(pwd)/.codex codex
例如，如果你的项目结构如下：
project
│
├─ .codex
│ ├─ AGENTS.md
│ └─ config.toml
那么，Codex就只会使用这个项目下的配置：
只使用当前项目的配置
而不会去读取默认的：
~/.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 | 项目规范 |
| AGENTS.override.md | 覆盖规则 |
| 全局配置 | 所有项目共享 |
| 项目配置 | 当前仓库生效 |
| 子目录配置 | 局部覆盖 |
| fallback文件 | 兼容旧规范 |
| CODEX_HOME | 多配置环境 |
| project_doc_max_bytes | 控制说明大小 |
对于团队开发来说，AGENTS.md不仅能显著提升AI生成代码的一致性，更能把团队的项目经验沉淀为可复用的协作规范，让Codex真正成为那个最懂你团队的AI开发助手。
侠游戏发布此文仅为了传递信息，不代表侠游戏网站认同其观点或证实其描述
相关攻略
更多
热游推荐
更多-
- DreamStudio
- Android/ | AI绘图
- 2026-06-30
-
-
- Playground AI
- Android/ | AI绘图
- 2026-06-30
-
- Adobe Firefly
- Android/ | AI绘图
- 2026-06-30
-
-
-
- Leonardo AI
- Android/ | AI绘图
- 2026-06-30
-
- Stable Diffusion
- Android/ | AI绘图
- 2026-06-30
