Codex 配置指南：AGENTS.md、config.toml、Skills 与 MCP 怎么分工

Codex 每次新会话都像带新人，重复解释项目背景很浪费时间。这篇文章把配置拆成三层：项目规则写进 AGENTS.md，个人偏好放进 config.toml，能力扩展交给 Skills 和 MCP，并给出可直接套用的模板。

常见卡点：为什么每次都要从头讲

• 新会话基本从零开始，之前讲过的背景、偏好和项目约定不会自动带过来。
• README、AGENTS.md 和测试命令长期不更新，导致同一件事反复解释。
• 2025 年不少教程建议在 AGENTS.md 里塞几十上百条指令，OpenAI 在 2026 年 9 月提醒开发者重新审视：这些内容会占用上下文，还可能互相冲突。
• 第三方配置不要整份照抄，provider、权限和 API 端点可能已经变了，要以当前官方参数为准。

AGENTS.md：给 Codex 的项目入职手册

• 它是可选的项目指令文件，Codex 从某个目录启动时会自动读取该目录下的 AGENTS.md，通常就是项目根目录；用 /status 可以确认它是否生效。
• 三个放置层级：项目级用 /init 在当前目录生成后补充真实规则；全局级放在 ~/.codex 下，管跨项目的通用偏好；子目录级用于前端、后端、多服务仓库，根文件讲整体，局部文件补细节。
• 临时性的项目要求放项目文件，长期通用的规则放全局文件。
• 内容聚焦能改变工作方式的信息：项目概述、技术栈与目录结构、安装/启动/lint/test/build 命令、CLI 工具、MCP 服务、代码风格、受保护目录、发布流程与业务边界、开发流程、收尾汇报。
• 路径要写具体：与其写“代码在 src”，不如写“前端页面在 src/pages，API 请求在 src/api，改完跑 npm run lint 和 npm test”。

写好 AGENTS.md 的六条原则

• 短而聚焦：OpenAI 见到的大多数文件在 100 行以内，规则太多会淹没优先级。
• 可验证：写清检查方式，比如代码分析工具、相关测试、构建、报错怎么修；每条要求都问一句 Codex 怎么确认做到了。
• 从简起步：先写项目用途、代码位置、构建测试说明和常用命令，团队约定等重复出现后再补。
• 持续更新：反复犯的错就记进去，发现它找测试命令太慢就把命令写上。
• 主文件放通用指引，细节外置到 execplans.md、frontend.md、architecture.md、code-review-guidelines.md 等文件，主文件变成一张地图，按需读取。
• 定期重审每一条规则，换模型时尤其要重看。

2026 年的提醒：给更强的模型留出空间

• OpenAI 2026 年 9 月的文章认为更强的模型不需要那么多手把手指令，积累了一年的规则该在换模型时清理。
• 不要要求每次改动前先读一堆文档，为改一个错别字读完整张项目地图是浪费；改成按场景指向文档，比如改 schema 看 database.md，准备发布看 deployment.md。
• 可以删掉“总是运行测试”这类提醒，新模型会自己测试和检查结果，重复要求反而可能触发不必要的测试。
• 对确认安全的工作流明确授权，例如说明本地测试用一次性 fixture、不接触生产，允许它直接跑测试并修复由本次改动引起的失败，不必每步都问。
• 边界措辞不要过度强硬，否则模型会在你希望它继续的地方停下来；也可以让它按这些建议反过来审计你的 AGENTS.md 和 Skills。

三份可直接改的模板

• Next.js + pnpm：写明安装、开发、lint、测试、构建命令；编辑规则包括未经明确要求不改数据库 schema、不无故加依赖、改前读 README 和 package.json、结束时汇报改动文件和执行的命令。
• 小型 Python 项目极简版只要四项：Python 3.11+、PEP 8、pytest、中文注释。
• Python 入门完整版补充：代码保持简单可读、加功能时更新 README、改完尽量跑测试或启动程序验证；交互偏好包括先讲思路再动手、删文件/重构目录/装依赖前先问、用中文回复。
• 模板末尾的权限、默认模型、Skill 路径只是给模型看的文字，真正的权限和默认模型要在 config.toml 或界面里设置。

今天就能做

• 今天就在项目根目录跑一次 /init，把安装、启动、lint、test、build 五条命令和受保护目录补进去。
• 把 AGENTS.md 压到 100 行以内，细节拆到独立文档，并在主文件里写清什么场景读哪个文件。
• 检查现有规则里“总是运行测试”这类重复提醒，换成具体的验证命令和安全工作流的明确授权。