文档建议反馈控制台
首页
学习
活动
专区
圈层
工具
MCP广场
文章/答案/技术大牛
发布
社区首页 >专栏 >Codex使用教程：通过AGENTS.md编写自定义说明，让AI按你的规则工作

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

作者头像
代码简单说
修改于 2026-06-29 15:53:44
修改于 2026-06-29 15:53:44
6200
举报
文章被收录于专栏：代码简单说代码简单说

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，可以通过下面的网站获取客户端：

名称

地址

Codex客户端下载

https://codexdown.cc/

官方文档：

文档

地址

AGENTS.md说明

https://codexdown.cn/docs/configuration/agents/

什么是AGENTS.md

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

Codex 启动时会自动读取它。

你可以在里面定义：

代码语言：javascript
复制
# 工作规范

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

当 Codex 开始工作时：

代码语言：javascript
复制
codex

它会先读取这些规则。

然后再执行用户的任务。

因此：

AGENTS.md = AI团队规范文件

Codex如何发现AGENTS.md

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

实际上并不是。

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

V1 查找流程

代码语言：javascript
复制
全局配置
↓
项目根目录
↓
子目录
↓
当前工作目录

搜索顺序：

代码语言：javascript
复制
AGENTS.override.md
↓
AGENTS.md
↓
备用文件名

优先级最高的是：

代码语言：javascript
复制
AGENTS.override.md

如果存在：

代码语言：javascript
复制
AGENTS.md
将被忽略

Codex配置层级原理

假设项目结构如下：

代码语言：javascript
复制
project
│
├─ AGENTS.md
│
├─ services
│   │
│   ├─ search
│   │
│   └─ payments
│       │
│       ├─ AGENTS.md
│       └─ AGENTS.override.md

当在：

代码语言：javascript
复制
services/payments

目录运行 Codex 时。

最终加载顺序：

代码语言：javascript
复制
~/.codex/AGENTS.md
↓
project/AGENTS.md
↓
services/payments/AGENTS.override.md

因为：

代码语言：javascript
复制
AGENTS.override.md
优先级高于
AGENTS.md

所以：

代码语言：javascript
复制
services/payments/AGENTS.md
不会被读取

创建全局AGENTS.md

V1 创建配置目录

Linux/macOS：

代码语言：javascript
复制
mkdir -p ~/.codex

Windows：

代码语言：javascript
复制
mkdir $HOME\.codex

V2 创建全局规则

文件：

代码语言：javascript
复制
~/.codex/AGENTS.md

内容：

代码语言：javascript
复制
# 工作规范

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

保存后：

代码语言：javascript
复制
codex --ask-for-approval never "Summarize the current instructions."

如果配置成功。

Codex会输出类似：

代码语言：javascript
复制
当前规则：

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

说明已经生效。

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

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

例如：

代码语言：javascript
复制
支付系统

要求：

代码语言：javascript
复制
不能使用npm test

而必须：

代码语言：javascript
复制
make test-payments

此时可以创建：

代码语言：javascript
复制
AGENTS.override.md

示例：

代码语言：javascript
复制
# 支付系统规范

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

这样：

代码语言：javascript
复制
当前目录规则
覆盖
全局规则

项目级AGENTS.md配置

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

例如：

代码语言：javascript
复制
# 仓库规范

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

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

自定义备用文件名

很多团队已经存在：

代码语言：javascript
复制
TEAM_GUIDE.md

或者：

代码语言：javascript
复制
.agents.md

不想重新命名。

Codex支持配置备用文件名。

修改：

代码语言：javascript
复制
~/.codex/config.toml
代码语言：javascript
复制
project_doc_fallback_filenames = [
    "TEAM_GUIDE.md",
    ".agents.md"
]

project_doc_max_bytes = 65536

配置后搜索顺序变成：

代码语言：javascript
复制
AGENTS.override.md
↓
AGENTS.md
↓
TEAM_GUIDE.md
↓
.agents.md

这样旧项目无需迁移。

Codex也能识别。

配置文件大小限制

默认情况下：

代码语言：javascript
复制
project_doc_max_bytes = 32768

即：

代码语言：javascript
复制
32KB

超过后：

代码语言：javascript
复制
后续说明文件不会继续加载

如果团队规范比较多。

建议调整：

代码语言：javascript
复制
project_doc_max_bytes = 65536

或者：

代码语言：javascript
复制
project_doc_max_bytes = 131072

使用CODEX_HOME切换配置

某些场景下：

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

需要独立配置。

可以通过：

代码语言：javascript
复制
CODEX_HOME=$(pwd)/.codex codex

指定新的配置目录。

例如：

代码语言：javascript
复制
project
│
├─ .codex
│   ├─ AGENTS.md
│   └─ config.toml

这样：

代码语言：javascript
复制
只使用当前项目的配置

不会读取默认：

代码语言：javascript
复制
~/.codex

验证AGENTS.md是否生效

方法1 查看当前规则

代码语言：javascript
复制
codex --ask-for-approval never \
"Summarize the current instructions."

输出：

代码语言：javascript
复制
当前加载规则...

即可确认。

方法2 查看活动文件

代码语言：javascript
复制
codex \
--cd services/payments \
--ask-for-approval never \
"Show which instruction files are active."

输出：

代码语言：javascript
复制
~/.codex/AGENTS.md
project/AGENTS.md
services/payments/AGENTS.override.md

说明加载成功。

方法3 查看日志

日志目录：

代码语言：javascript
复制
~/.codex/log/

常见文件：

代码语言：javascript
复制
codex-tui.log

或者：

代码语言：javascript
复制
session-xxx.jsonl

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

常见问题排查

问题1 AGENTS.md没有生效

检查：

代码语言：javascript
复制
codex status

确认：

代码语言：javascript
复制
当前工作目录
是否为正确项目

同时确认：

代码语言：javascript
复制
AGENTS.md不是空文件

问题2 规则不正确

优先检查：

代码语言：javascript
复制
AGENTS.override.md

因为它拥有最高优先级。

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

问题3 备用文件不生效

检查：

代码语言：javascript
复制
project_doc_fallback_filenames

是否拼写正确。

修改后记得重启 Codex。

问题4 规则被截断

检查：

代码语言：javascript
复制
project_doc_max_bytes

是否过小。

必要时拆分文件。

例如：

代码语言：javascript
复制
AGENTS.md
↓
backend/AGENTS.md
↓
frontend/AGENTS.md

进行分层管理。

推荐的团队级AGENTS.md模板

前端项目可以直接参考：

代码语言：javascript
复制
# 团队规范

## 包管理

- 优先使用pnpm
- 禁止npm install

## 代码规范

- 必须通过eslint
- 必须通过prettier

## 测试规范

- 修改代码后执行npm test

## 文档规范

- 接口修改同步更新docs

## 提交规范

- 使用Conventional Commits

## 安全规范

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

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

总结

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

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

代码语言：javascript
复制
请使用pnpm
请运行测试
请遵循团队规范
请补充文档

更好的方式是：

代码语言：javascript
复制
把规则写进AGENTS.md

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

核心机制总结如下：

功能

作用

AGENTS.md

项目规范

AGENTS.override.md

覆盖规则

全局配置

所有项目共享

项目配置

当前仓库生效

子目录配置

局部覆盖

fallback文件

兼容旧规范

CODEX_HOME

多配置环境

project_doc_max_bytes

控制说明大小

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

本文参与 腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。
原始发表：2026-06-15，如有侵权请联系 cloudcommunity@tencent.com 删除
客户端
配置
测试
工作
教程

本文分享自 作者个人站点/博客 前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ，欢迎热爱写作的你一起参与！

客户端
配置
测试
工作
教程
评论
登录后参与评论
0 条评论
热度
最新
登录 后参与评论
推荐阅读
目录
  • Codex使用教程：通过AGENTS.md编写自定义说明，让AI按你的规则工作
  • Codex客户端下载
  • 什么是AGENTS.md
  • Codex如何发现AGENTS.md
    • V1 查找流程
  • Codex配置层级原理
  • 创建全局AGENTS.md
    • V1 创建配置目录
    • V2 创建全局规则
  • 使用AGENTS.override.md覆盖全局规则
  • 项目级AGENTS.md配置
  • 自定义备用文件名
  • 配置文件大小限制
  • 使用CODEX_HOME切换配置
  • 验证AGENTS.md是否生效
    • 方法1 查看当前规则
    • 方法2 查看活动文件
    • 方法3 查看日志
  • 常见问题排查
    • 问题1 AGENTS.md没有生效
    • 问题2 规则不正确
    • 问题3 备用文件不生效
    • 问题4 规则被截断
  • 推荐的团队级AGENTS.md模板
  • 总结
领券

腾讯云开发者

扫码关注腾讯云开发者

扫码关注腾讯云开发者

领取腾讯云代金券

热门产品

热门推荐

更多推荐

Copyright © 2013 - 2026 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有 

深圳市腾讯计算机系统有限公司 ICP备案/许可证号：粤B2-20090059 粤公网安备44030502008569号

腾讯云计算（北京）有限责任公司 京ICP证150476号 |  京ICP备11018762号

问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档

Copyright © 2013 - 2026 Tencent Cloud.

All Rights Reserved. 腾讯云 版权所有

登录 后参与评论