本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/concepts/customization

自定义

如何使用项目指导、Skills、MCP 和 Subagents 自定义 Codex

自定义就是让 Codex 按照你的团队工作方式运行的方法。

在 Codex 中，自定义来自几个协同工作的层次：

• 用于持久化指令的 项目指导（AGENTS.md）
• 用于存储从先前工作中学习到的有用上下文的 Memories
• 用于可复用工作流和领域专长的 Skills
• 用于访问外部工具和共享系统的 MCP
• 用于将工作委派给专门 Subagents 的 Subagents

这些是互补的，而不是相互竞争的。AGENTS.md 用于塑造行为，memories 会延续本地上下文，skills 用于封装可重复的流程，而 MCP 则将 Codex 连接到本地工作区之外的系统。

AGENTS 指导

AGENTS.md 为 Codex 提供持久的项目指导，这些指导会随你的仓库一起存在，并在 agent 开始工作前生效。请保持精简。

将它用于你希望 Codex 在某个仓库中每次都遵循的规则，例如：

• 构建和测试命令
• 评审期望
• 仓库特定约定
• 目录特定说明

当 agent 对你的代码库做出错误假设时，在 AGENTS.md 中纠正它，并要求 agent 更新 AGENTS.md，以便该修复能够持久保留。把它当作一个反馈循环。

更新 AGENTS.md： 一开始只写真正重要的指令。将重复出现的评审反馈固化下来，把指导放在最接近其适用位置的目录中，并在你纠正某些内容时告诉 agent 更新 AGENTS.md，这样后续会话就能继承这些修复。

何时更新 AGENTS.md

• 重复错误：如果 agent 反复犯同样的错误，就添加一条规则。
• 阅读过多：如果它找到了正确的文件，但读取了过多文档，就添加路由指导（优先查看哪些目录/文件）。
• 重复出现的 PR 反馈：如果你留下同样的反馈超过一次，就将其固化。
• 在 GitHub 中：在 pull request 评论中，用请求标记 @codex（例如，@codex add this to AGENTS.md），将更新委派给一个云端任务。
• 自动化漂移检查：使用 automations 运行周期性检查（例如每天），查找指导缺口并建议向 AGENTS.md 添加什么内容。

将 AGENTS.md 与能强制执行这些规则的基础设施配合使用：pre-commit hooks、linters 和 type checkers 会在你看到问题之前就捕获它们，因此系统在防止重复错误方面会变得更聪明。

Codex 可以从多个位置加载指导：Codex 主目录中的全局文件（面向你这个开发者）以及团队可提交到仓库中的仓库专用文件。离工作目录越近的文件优先级越高。 使用全局文件来塑造 Codex 与你沟通的方式（例如评审风格、详细程度和默认值），并让仓库文件专注于团队和代码库规则。

使用 AGENTS.md 的自定义指令

Skills

Skills 为 Codex 提供适用于可重复工作流的可复用能力。 对于可复用工作流，Skills 往往是最佳选择，因为它们支持更丰富的说明、脚本和参考资料，同时又能在不同任务之间保持可复用。 Skills 会被加载并对 agent 可见（至少其元数据可见），因此 Codex 可以发现并隐式选择它们。这样可以在不提前膨胀上下文的情况下提供丰富的工作流。

使用 skill 文件夹在本地编写并迭代工作流。如果该工作流已经有现成的 plugin，先安装它以复用经过验证的设置。当你想要在团队间分发自己的工作流，或将其与 app 集成一起打包时，可将其打包为一个 plugin。Skills 仍然是编写格式；plugins 则是可安装的分发单元。

一个 skill 通常是一个 SKILL.md 文件，再加上可选的脚本、参考资料和资源文件。

skill 目录可以包含一个 scripts/ 文件夹，其中放置 CLI 脚本，Codex 会在工作流中调用这些脚本（例如，填充种子数据或运行校验）。当工作流需要外部系统（问题跟踪器、设计工具、文档服务器）时，可将该 skill 与 MCP 配合使用。

示例 SKILL.md：

---
name: commit
description: 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.

在以下场景中使用 Skills：

• 可重复工作流（发布步骤、评审流程、文档更新）
• 团队特定专长
• 需要示例、参考资料或辅助脚本的流程

Skills 可以是全局的（位于你的用户目录中，供你作为开发者使用），也可以是仓库专用的（签入到 .agents/skills 中，供你的团队使用）。当工作流适用于该项目时，将仓库 skills 放在 .agents/skills 中；如果你希望 skills 在所有仓库中都可用，则使用你的用户目录。

Layer	Global	Repo
AGENTS	~/.codex/AGENTS.md	仓库根目录或嵌套目录中的 AGENTS.md
Skills	$HOME/.agents/skills	仓库中的 .agents/skills

Codex 对 skills 使用渐进式披露：

• 它首先使用元数据（name、description）进行发现
• 仅当某个 skill 被选中时，它才会加载 SKILL.md
• 仅在需要时，它才会读取参考资料或运行脚本

Skills 可以被显式调用；当任务与 skill 描述匹配时，Codex 也可以隐式选择它们。清晰的 skill 描述可以提高触发可靠性。

Agent Skills

MCP

MCP（Model Context Protocol）是将 Codex 连接到外部工具和上下文提供方的标准方式。 它对于远程托管的系统尤其有用，例如 Figma、Linear、GitHub，或你的团队依赖的内部知识服务。

当 Codex 需要本地仓库之外的能力时，请使用 MCP，例如问题跟踪器、设计工具、浏览器或共享文档系统。

一种理解方式是：

• Host：Codex
• Client：Codex 内部的 MCP 连接
• Server：外部工具或上下文提供方

MCP servers 可以暴露：

• Tools（操作）
• Resources（可读取数据）
• Prompts（可复用提示模板）

这种分离有助于你理解信任边界和能力边界。有些 server 主要提供上下文，而另一些则暴露强大的操作能力。

在实践中，MCP 通常在与 skills 配合时最有用：

• 一个 skill 定义工作流，并指定要使用的 MCP tools

Model Context Protocol

Subagents

你可以创建具有不同角色的不同 agents，并提示它们以不同方式使用工具。例如，一个 agent 可能运行特定的测试命令和配置，而另一个则拥有用于获取生产日志以便调试的 MCP servers。每个 subagent 都保持专注，并为其工作使用合适的工具。

Subagent 概念

Skills + MCP 结合使用

Skills 加上 MCP 就是所有内容汇聚在一起的地方：skills 定义可重复工作流，而 MCP 将它们连接到外部工具和系统。 如果一个 skill 依赖 MCP，请在 agents/openai.yaml 中声明该依赖，以便 Codex 可以自动安装并完成连接（参见 Agent Skills）。

下一步

按以下顺序构建：

1. 使用 AGENTS.md 的自定义指令，让 Codex 遵循你的仓库约定。添加 pre-commit hooks 和 linters 来强制执行这些规则。
2. 当已经存在可复用工作流时，安装一个 plugin。否则，创建一个 skill，并在你想共享它时将其打包为 plugin。
3. 当工作流需要外部系统（Linear、GitHub、文档服务器、设计工具）时，使用 MCP。
4. 当你准备好将嘈杂或专业化的任务委派给 Subagents 时，使用 Subagents。