English
主导航

推荐
API 仪表板

自定义

如何通过项目指导、技能、MCP 和子代理来自定义 Codex

自定义是指让 Codex 适应您团队的工作方式。

在 Codex 中，自定义由协同工作的几个层级组成：

  • 项目指导（AGENTS.md) for persistent instructions
  • 记忆 提供从先前工作中获取的有用上下文
  • 技能 提供可复用的工作流和领域专业知识
  • MCP 用于访问外部工具和共享系统
  • 子智能体 用于将工作委派给专门的子代理

它们是互补的，而非相互竞争的。 AGENTS.md 塑造行为，记忆延续本地上下文，技能封装可重复的流程，而 MCP 将 Codex 连接到本地工作区之外的外部系统。

AGENTS 指导

AGENTS.md 为 Codex 提供随代码库保留的持久项目指导，并在代理开始工作前生效。请保持内容精简。

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

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

当代理对您的代码库做出错误假设时，请在 AGENTS.md 中予以纠正，并让代理更新 AGENTS.md 以便该修复得以持久保留。将其视为一个反馈循环。

更新 AGENTS.md: 从最重要的说明开始。将反复出现的审查反馈代码化，将指导放置在适用的最近目录中，并在您纠正问题时让代理更新 AGENTS.md 以便未来的会话能够继承该修复。

何时更新 AGENTS.md

  • 重复犯错: 如果智能体反复犯同样的错误，请添加一条规则。
  • 阅读过多: 如果它找到了正确的文件但读取了太多文档，请添加路由指引（优先处理哪些目录/文件）。
  • 反复出现的 PR 反馈: 如果你多次提供相同的反馈，请将其固化为规则。
  • In GitHub: 在拉取请求评论中，标记 @codex 附带一个请求（例如， @codex add this to AGENTS.md）将更新操作委托给云任务。
  • 自动化偏移检查：使用 自动化 以运行定期检查（例如，每日），这些检查会寻找指导缺口并建议向其添加什么内容 AGENTS.md.

搭配 AGENTS.md 其基础设施会强制执行这些规则：预提交钩子、代码检查工具和类型检查器会在你发现问题之前将其捕获，从而让系统在防止重复犯错方面变得更加智能。

Codex 可以从多个位置加载指导信息：Codex 主目录中的全局文件（面向作为开发者的你）以及团队可以签入的仓库特定文件。越靠近工作目录的文件优先级越高。使用全局文件来调整 Codex 与你的沟通方式（例如审查风格、详细程度和默认设置），并让仓库文件专注于团队和代码库规则。

  • ~/.codex/
    • AGENTS.md 全局（面向作为开发者的你）
  • repo-root/
    • AGENTS.md 特定于仓库（面向您的团队）

使用 AGENTS.md 自定义指令

技能

技能为 Codex 提供了可复用的能力，适用于可重复的工作流。技能通常最契合可复用工作流的需求，因为它们支持更丰富的指令、脚本和引用，同时能在不同任务间保持复用性。技能会被加载并对代理可见（至少是它们的元数据），因此 Codex 可以隐式地发现并选择它们。这样既保留了丰富的工作流，又不会在一开始就占用过多的上下文。

使用技能文件夹在本地编写和迭代工作流。如果已有适用于该工作流的插件，请先安装它，以复用经过验证的配置。当你想在团队间分发自己的工作流，或将其与应用集成打包时，请将其打包为 插件。技能仍然是编写格式；插件是可安装的发布单元。

一个技能通常是一个 SKILL.md 文件，外加可选的脚本、引用和资产。

  • my-skill/
    • SKILL.md 必填：指令 + 元数据
    • scripts/ 可选：可执行代码
    • references/ 可选：文档
    • assets/ 可选：模板、资源

技能目录可以包含一个 scripts/ 文件夹，其中包含 Codex 在工作流中调用的 CLI 脚本（例如，种子数据或运行验证）。当工作流需要外部系统（问题追踪器、设计工具、文档服务器）时，请将该技能与 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.

在以下场景使用技能：

  • 可重复的工作流（发布步骤、审查常规、文档更新）
  • 特定团队的专业知识
  • 需要示例、参考或辅助脚本的操作流程

技能可以是全局的（位于您的用户目录中，供您作为开发者使用），也可以是特定于仓库的（提交到 .agents/skills，供你的团队使用）。将仓库技能放在 .agents/skills 当工作流适用于该项目时；对于希望跨所有仓库使用的技能，请放在您的用户目录中。

将全局仓库
AGENTS~/.codex/AGENTS.mdAGENTS.md 位于仓库根目录或嵌套目录中
技能$HOME/.agents/skills.agents/skills in repo

Codex 对技能采用渐进式披露策略：

  • 它从元数据（name, description）开始进行发现
  • 仅当 SKILL.md 技能被选中时才会加载
  • 它仅在需要时读取引用或运行脚本

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

Agent 技能

MCP

MCP (模型上下文协议) 是将 Codex 连接到外部工具和上下文提供程序的标准方式。它对于远程托管的系统特别有用，例如 Figma、Linear、GitHub 或您的团队依赖的内部知识服务。

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

可以这样理解：

  • 主机: Codex
  • 客户端: Codex 内部的 MCP 连接
  • 服务器: 外部工具或上下文提供者

MCP 服务器可以暴露：

  • 工具 (操作)
  • 资源 (可读数据)
  • 提示词 (可复用的提示模板)

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

在实践中，MCP 通常在与技能（skills）结合使用时发挥最大效用：

  • 技能定义了工作流，并指定要使用的 MCP 工具

模型上下文协议

子智能体

你可以创建具有不同角色的不同代理，并提示它们以不同方式使用工具。例如，一个代理可能运行特定的测试命令和配置，而另一个代理则拥有用于获取生产日志以进行调试的 MCP 服务器。每个子代理各司其职，并使用适合其任务的工具。

子代理概念

技能 + MCP 结合使用

技能与 MCP 的结合使一切融为一体：技能定义可重复的工作流，而 MCP 将它们连接到外部工具和系统。如果某项技能依赖于 MCP，请在以下位置声明该依赖： agents/openai.yaml 以便 Codex 能够自动安装并连接它（参见 Agent 技能).

下一步

按以下顺序构建：

  1. 使用 AGENTS.md 自定义指令 以便 Codex 遵循你的仓库约定。添加预提交钩子（pre-commit hooks）和代码检查工具（linters）来强制执行这些规则。
  2. 在已有可复用工作流时安装 插件 。否则，创建一个 技能 并在需要共享时将其打包为插件。
  3. MCP 当工作流需要外部系统（Linear、GitHub、文档服务器、设计工具）时。
  4. 子智能体 当你准备好将繁杂或专业化的任务委托给子代理时。