自定义
自定义功能可以让 Codex 按照团队的工作方式运行。
在 Codex 中，自定义功能来自协同工作的几个层面：
- 项目指导（
AGENTS.md）：用于提供持久化指令 - 记忆：用于保存从先前工作中学到的有用上下文
- 技能：用于可复用的工作流和领域专业知识
- MCP：用于访问外部工具和共享系统
- 子代理：用于将工作委派给专门的子代理
这些层面彼此互补，而不是相互竞争。AGENTS.md 用于塑造行为，记忆用于延续本地上下文，技能用于封装可重复的流程，而 MCP 则将 Codex 连接到本地工作区之外的系统。
AGENTS 指导
Section titled “AGENTS 指导”AGENTS.md 为 Codex 提供持久的项目指导，这些指导会随仓库一起保存，并在代理开始工作前生效。请保持内容精简。
将你希望 Codex 在仓库中每次都遵循的规则写入其中，例如：
- 构建和测试命令
- 评审要求
- 仓库特定的约定
- 目录特定的指令
当代理对你的代码库做出错误假设时，请在 AGENTS.md 中纠正这些假设，并要求代理更新 AGENTS.md，以便让修复持久化。将其视为一个反馈循环。
更新 AGENTS.md： 仅从重要的指令开始。将反复出现的评审反馈编写成规则，把指导放在适用范围最近的目录中；当你纠正某个问题时，告诉代理更新 AGENTS.md，以便未来会话继承此修复。
何时更新 AGENTS.md
Section titled “何时更新 AGENTS.md”- 反复出现的错误：如果代理反复犯同一个错误，请添加一条规则。
- 阅读过多内容：如果代理找到了正确的文件，却读取了过多文档，请添加路由指导，说明应优先查看哪些目录或文件。
- 反复出现的 PR 反馈：如果你不止一次留下相同的反馈，请将其编写成规则。
- 在 GitHub 中：在拉取请求评论中使用
@codex并提出请求（例如，@codex 将此内容添加到 AGENTS.md），将更新委派给云端聊天。 - 自动执行偏差检查：使用定时任务运行定期检查（例如每天一次），查找指导缺口，并建议添加到
AGENTS.md的内容。
将 AGENTS.md 与执行这些规则的基础设施结合起来：提交前钩子、代码检查器和类型检查器会在问题出现之前捕获问题，让系统更智能地防止反复出现的错误。
Codex 可以从多个位置加载指导：Codex 主目录中的全局文件（供开发者使用）以及团队可以提交到仓库中的特定于仓库的文件。距离工作目录更近的文件具有更高优先级。
使用全局文件来调整 Codex 与你的沟通方式（例如评审风格、详细程度和默认设置），并让仓库文件专注于团队和代码库规则。
~/.codex/AGENTS.md：全局文件（供开发者使用）
repo-root/AGENTS.md：特定于仓库的文件（供团队使用）
技能为 Codex 提供可复用的能力，用于执行可重复的工作流。
对于可复用的工作流，技能通常是最佳选择，因为它们支持更丰富的指令、脚本和参考资料，同时仍能在不同任务中复用。
技能会被加载并对代理可见（至少其元数据如此），因此 Codex 可以隐式发现并选择技能。这样，丰富的工作流便能随时使用，而无需在开始时一次性占用过多上下文。
使用技能目录在本地编写和迭代工作流。如果某个插件已经存在于该工作流中，请先安装它，以便复用经过验证的配置。当你想在团队之间分发自己的工作流，或将其与连接器打包时，请将其打包为一个插件。技能是编写格式；插件是可安装的分发单元。
技能通常由一个 SKILL.md 文件以及可选的脚本、参考资料和资源组成。
my-skill/SKILL.md：必需，包含指令和元数据scripts/：可选的可执行代码references/：可选的文档assets/：可选的模板和资源
技能目录可以包含一个 scripts/ 文件夹，其中存放 Codex 在工作流中调用的 CLI 脚本（例如，用于填充数据或运行验证）。当工作流需要外部系统（问题跟踪器、设计工具、文档服务器）时，请将技能与 MCP 配合使用。
SKILL.md 示例：
---name: commitdescription: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.---
1. Do not run `git add .`. Stage files in logical groups by purpose.2. Group into separate commits: feat → test → docs → refactor → chore.3. Write concise commit messages that match the change scope.4. Keep each commit focused and reviewable.在以下情况下使用技能：
- 可重复的工作流（发布步骤、评审流程、文档更新）
- 团队特定的专业知识
- 需要示例、参考资料或辅助脚本的流程
技能可以是全局技能（位于用户目录中，供开发者使用），也可以是特定于仓库的技能（签入 .agents/skills，供团队使用）。当工作流适用于某个项目时，请将仓库技能放在 .agents/skills 中；如果希望在所有仓库中使用某项技能，请将其放在用户目录中。
| 层级 | 全局 | 仓库 |
|---|---|---|
| AGENTS | ~/.codex/AGENTS.md |
仓库根目录或嵌套目录中的 AGENTS.md |
| 技能 | ~/.agents/skills |
仓库中的 .agents/skills |
Codex 对技能使用渐进式披露：
- 首先加载元数据（
name、description）以便发现 - 仅在选择技能后加载
SKILL.md - 仅在需要时读取参考资料或运行脚本
技能可以显式调用；当任务符合技能描述时，Codex 也可以隐式选择技能。清晰的技能描述有助于提高触发可靠性。
MCP（Model Context Protocol）是将 Codex 连接到外部工具和上下文提供方的标准方式。
对于 Figma、Linear、GitHub 或团队依赖的内部知识服务等远程托管系统，它尤其有用。
当 Codex 需要本地仓库之外的能力时，请使用 MCP，例如问题跟踪器、设计工具、浏览器或共享文档系统。
可以这样理解：
- 主机：Codex
- 客户端：Codex 内部的 MCP 连接
- 服务器：外部工具或上下文提供方
MCP 服务器可以提供：
- 工具（操作）
- 资源（可读取的数据）
- 提示词（可复用的提示词模板）
这种分离方式有助于你思考信任边界和能力边界。有些服务器主要提供上下文，而另一些服务器会暴露强大的操作能力。
实际上，MCP 与技能配合使用时通常最有用：
- 技能定义工作流，并指定要使用的 MCP 工具
你可以创建具有不同角色的代理，并提示它们以不同方式使用工具。例如，一个代理可以运行特定的测试命令和配置，另一个代理可以使用 MCP 服务器获取生产日志来进行调试。每个子代理都会专注于自己的任务，并使用适合其工作的工具。
技能与 MCP 协同使用
Section titled “技能与 MCP 协同使用”技能与 MCP 结合后，整个体系便串联起来：技能定义可重复的工作流，而 MCP 将它们连接到外部工具和系统。
如果技能依赖 MCP，请在 agents/openai.yaml 中声明该依赖，以便 Codex 自动安装并完成连接配置（请参阅构建技能）。
请按以下顺序构建：
- 先设置使用 AGENTS.md 的自定义指令，让 Codex 遵循你的仓库约定。添加提交前钩子和代码检查器来执行这些规则。
- 如果某个可复用的工作流已经存在，请安装相应的插件。否则，请创建一个技能，并在希望共享时将其打包为插件。
- 当工作流需要外部系统（Linear、GitHub、文档服务器、设计工具）时，使用 MCP。
- 当你准备好将繁琐或专业化的任务委派给子代理时，使用子代理。