---
title: "定制 Codex 行为"
description: "把 AGENTS.md、Memories、Skills、MCP 和 Subagents 放到同一张行为定制地图里。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Customization 的目标，是让 Codex 按你和团队的工作方式运行。它不是多装功能，而是把长期规则、重复流程、外部系统和角色分工放到正确层级。

> [!IMPORTANT]
> 行为定制先从 `AGENTS.md` 和验证命令开始。不要在项目规则还不清楚时先堆 MCP、skills 和 subagents。

<Cards>
  <Card title="Customization" href="https://developers.openai.com/codex/concepts/customization">
    官方定制能力总览。
  </Card>
  <Card title="AGENTS.md" href="/docs/codex/understanding/agents-md-guide">
    长期项目规则应该先写进 `AGENTS.md`。
  </Card>
  <Card title="Skills and MCP" href="/docs/codex/understanding/skills-subagents-hooks">
    区分可复用流程、外部工具和角色分工。
  </Card>
</Cards>

## 五层地图

```mermaid
flowchart LR
    Agents["AGENTS.md"] --> Behavior["Codex behavior"]
    Memories["Memories"] --> Behavior
    Skills["Skills"] --> Behavior
    MCP["MCP"] --> Behavior
    Subagents["Subagents"] --> Behavior
```

这几层互补，不竞争：

- `AGENTS.md`：持久项目指导。
- Memories：从过去工作中延续有用上下文。
- Skills：可复用 workflow 和 domain expertise。
- MCP：连接外部工具和 shared systems。
- Subagents：把工作委派给 specialized agents。

先问“这个需求应该放哪层”，再动配置。

## AGENTS.md：稳定规则

`AGENTS.md` 给 Codex 提供 durable project guidance，会在 agent 开始工作前生效。它适合写：

- build and test commands。
- review expectations。
- repo-specific conventions。
- directory-specific instructions。
- 受保护路径。
- 文档和测试同步规则。

当 agent 对 codebase 做出错误假设时，把正确规则补进 `AGENTS.md`。这应该是反馈循环，不是一次性文档工程。

更新原则：

- 从真正重要的 instructions 开始。
- 把反复出现的 review feedback codify。
- 把 guidance 放到离适用目录最近的位置。
- 全局文件塑造个人工作习惯，repo 文件聚焦团队和 codebase rules。

`AGENTS.md` 应该和 pre-commit hooks、linters、type checkers 配合。规则只靠模型遵守不够，能自动验证的就交给工具。

## Skills：重复流程

Skills 适合封装重复 workflows。它们通常比单纯写进 prompt 更适合复用，因为 skill 可以包含 instructions、scripts、references 和 assets。

常见结构：

```text
my-skill/
  SKILL.md
  scripts/
  references/
  assets/
```

适合做 skill 的情况：

- release steps。
- review routines。
- docs updates。
- migration checklist。
- 需要 examples、references 或 helper scripts 的流程。

不要把还没跑稳的想法直接做成 skill。先用普通 prompt 跑通，重复出现后再沉淀。

## MCP：外部系统

MCP 是把 Codex 连接到 external tools 和 context providers 的方式。它适合：

- issue trackers。
- design tools。
- browsers。
- shared documentation systems。
- internal knowledge services。

MCP server 可以暴露 tools、resources 和 prompts。区别要清楚：

- context 型 MCP 主要提供信息。
- action 型 MCP 可能改外部系统。
- 带写权限的 MCP 必须考虑审批、日志和回滚。

实践中，MCP 和 skills 搭配最有价值：skill 定义 workflow，并说明什么时候调用哪些 MCP tools。

## Memories：延续上下文

Memories 适合保存跨任务仍然有价值的偏好、项目习惯和历史经验。

不要把敏感信息、临时任务细节、过期路径、一次性结论写进 memory。Memory 是长期注入上下文，错误内容会持续影响后续任务。

## Subagents：角色分工

Subagents 适合把 noisy 或 specialized tasks 拆出去。例如：

- 一个 agent 专门跑测试和复现。
- 一个 agent 专门审查 diff。
- 一个 agent 专门查询日志或外部系统。

不要把 subagent 当成“更多模型就更强”。角色、输入、输出、权限和验收要写清，否则只是把混乱并行化。

## 建设顺序

推荐顺序：

1. 写清 `AGENTS.md`，让 Codex 遵守 repo conventions。
2. 用 lint、type check、test、pre-commit 强制可验证规则。
3. 重复流程跑稳后创建 skill。
4. 需要外部系统时接 MCP。
5. 准备好角色边界后再用 subagents。
6. 需要分发给团队时，把 skill 和配置打包成 plugin。

## 常见坑

- 项目规则没写清，却先装很多 MCP。
- 把一次性 prompt 做成 skill。
- 把个人偏好写进团队 repo `AGENTS.md`。
- 把 action 型 MCP 当成只读上下文。
- subagent 职责重叠，最后没人负责验收。
- Memory 里保存敏感信息或过期事实。

## 验收清单

- 任何定制项都能说清属于哪一层。
- `AGENTS.md` 小而具体，包含验证方式。
- skill 有真实触发词、步骤和验收。
- MCP 权限和数据来源可审计。
- memory 不含 secret、token 或临时结论。
- subagent 的输入、输出、权限和复核人明确。

## 官方资料

- [Customization](https://developers.openai.com/codex/concepts/customization)
- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md)
- [Skills](https://developers.openai.com/codex/skills)
- [MCP](https://developers.openai.com/codex/mcp)
- [Subagents](https://developers.openai.com/codex/subagents)
