第一次创建自定义 Subagent

第一次创建自定义 Subagent

这一篇开始创建第一个自定义 Subagent。

本篇目标不是创建一个能做所有事的代理，而是创建一个边界很窄、风险很低、容易验收的代理：

risk-reviewer：只负责审查本次代码修改风险，不修改文件。

它适合大多数真实项目，因为每次修改后都需要确认：有没有无关改动、有没有遗漏边界条件、有没有影响接口或数据、有没有缺少必要检查。

前置教程：什么时候需要自定义 Subagents
如果你还不能判断什么时候该自定义，先完成前置教程。

依据来源：OpenAI Codex 官方手册中 Subagents、custom agents、内置代理、项目级 .codex/agents/、自定义 agent 必填字段、nickname_candidates、沙盒继承等章节。

本篇目标

完成后，你应该得到：

• 一个项目级目录：.codex/agents/
• 一个自定义 agent 文件：.codex/agents/risk-reviewer.toml
• 一个只读风险审查代理：risk-reviewer
• 一次只读检查，确认配置没有危险项
• 一次调用练习，确认 Codex 能按这个角色审查修改风险
• 一套回滚方式

为什么第一个自定义 Subagent 选风险审查

第一个自定义代理应该满足 4 个条件：

1. 职责足够窄。
2. 不需要修改文件。
3. 输出标准容易判断。
4. 和当前项目长期相关。

风险审查刚好符合。

不建议第一次创建下面这些代理：

不建议的代理	原因
自动修复代理	容易并行改文件，风险高
全能工程师代理	边界太宽，和主会话职责重叠
自动提交代理	涉及 Git 提交，风险不适合新手第一篇
安装排障代理	可能频繁请求命令权限

本篇只做只读审查。

第 1 步：先让 Codex 判断是否适合创建

不要直接创建文件。 先让 Codex 只读检查项目状态。

复制这段：

请只读检查当前项目是否适合创建第一个自定义 Subagent。

目标角色：
risk-reviewer，用于审查本次代码修改是否存在明显风险。

要求：
1. 不要创建、修改、删除任何文件。
2. 检查项目是否已有 .codex/agents/ 目录。
3. 检查是否已有同名 risk-reviewer agent。
4. 检查项目里是否有 Git、构建脚本或测试脚本，判断这个角色是否有长期价值。
5. 如果已有自定义 agents，请列出文件名和用途，但不要修改。
6. 最后给出是否建议继续创建项目级 risk-reviewer 的结论。

预期结果：

• Codex 会检查项目结构。
• 如果没有 .codex/agents/，会说明可以新建。
• 如果已有同名文件，会提醒不要覆盖。
• 如果项目缺少可审查的代码修改流程，会建议先不要创建。

如果 Codex 发现已有 .codex/agents/risk-reviewer.toml，先不要继续。 让 Codex 解释已有文件：

请只读解释现有 .codex/agents/risk-reviewer.toml。

要求：
1. 不要修改文件。
2. 说明 name、description、developer_instructions 的含义。
3. 判断它是否只读。
4. 判断是否包含模型、沙盒、MCP 或 Skills 配置。
5. 判断是否建议复用、调整，还是重新设计。

第 2 步：先生成设计方案，不写文件

确认可以创建后，先让 Codex 生成方案。

复制这段：

请设计一个项目级自定义 Subagent，先不要写文件。

代理名称：
risk-reviewer

用途：
审查本次代码修改是否存在明显风险。

限制：
1. 第一版只配置 name、description、developer_instructions。
2. 不配置 model。
3. 不配置 model_reasoning_effort。
4. 不配置 sandbox_mode。
5. 不配置 MCP。
6. 不配置 Skills。
7. 代理只能只读审查，不修改文件。
8. 输出必须包含文件路径、风险等级、问题说明、建议修复方式。

请输出：
1. 为什么这个角色值得自定义。
2. 预计创建的文件路径。
3. TOML 内容草稿。
4. 风险点。
5. 回滚方式。

你要重点检查：

• 文件路径是 .codex/agents/risk-reviewer.toml。
• 必填字段都有：name、description、developer_instructions。
• 没有写入 API Key。
• 没有配置联网能力。
• 没有要求自动改文件。
• 没有让它自动提交 Git。
• 没有把它写成“全能代理”。

第 3 步：确认推荐 TOML 内容

第一版推荐保持简单。

TOML 内容可以接近这样：

name = "risk-reviewer"
description = "Review code changes for scope creep, regression risk, missing validation, unsafe commands, and unclear handoff notes."
developer_instructions = """
You are a read-only code change risk reviewer.

Scope:
- Review the current task, changed files, and diff when available.
- Focus on whether the change stays within scope and can be safely delivered.
- Check unrelated edits, missing validation, regression risk, unsafe commands, configuration changes, and unclear handoff notes.

Rules:
- Do not modify files.
- Do not run commands unless the parent explicitly asks for read-only inspection.
- Do not invent validation results.
- Mark uncertain findings as uncertain.
- Prefer concrete file paths and section names.

Output:
- Overall judgment.
- Findings grouped by severity: high, medium, low.
- For each finding: file path, issue, risk, reason, suggested fix.
- End with the smallest next improvement task.
"""

注意：这里没有配置模型、沙盒、MCP、Skills。 这是刻意的。

第一版先验证角色是否有用。 等它确实稳定，再考虑加更复杂的配置。

第 4 步：让 Codex 创建自定义 agent 文件

确认方案后，再让 Codex 写文件。

复制这段：

请创建项目级自定义 Subagent 文件。

目标文件：
.codex/agents/risk-reviewer.toml

要求：
1. 如果 .codex/agents/ 不存在，可以创建。
2. 如果 risk-reviewer.toml 已存在，不要覆盖，先停止并告诉我。
3. 只创建这个 TOML 文件，不修改其他文件。
4. 第一版只包含 name、description、developer_instructions。
5. 不配置 model、model_reasoning_effort、sandbox_mode、MCP、Skills。
6. developer_instructions 必须明确只读审查，不修改文件。
7. 完成后展示文件内容，并解释每个字段的作用。

预期结果：

• Codex 创建 .codex/agents/。
• Codex 创建 .codex/agents/risk-reviewer.toml。
• Codex 展示 TOML 内容。
• Codex 说明没有配置高风险项。

如果 Codex 想顺手改 AGENTS.md、config.toml 或其他文件，拒绝：

不要修改其他文件。
本次只允许创建 .codex/agents/risk-reviewer.toml。
请停止额外修改，并说明原因。

第 5 步：检查文件内容

创建后，让 Codex 自查：

请检查刚创建的 .codex/agents/risk-reviewer.toml。

要求：
1. 确认 TOML 语法是否合理。
2. 确认必填字段 name、description、developer_instructions 是否存在。
3. 确认 name 是否为 risk-reviewer。
4. 确认它是否只读。
5. 确认没有配置 model、sandbox_mode、MCP、Skills。
6. 确认没有密钥、账号、私有地址。
7. 如果发现风险，只说明风险，不要修改文件。

通过标准：

• name 正确。
• description 足够具体。
• developer_instructions 明确只读。
• 输出格式清楚。
• 没有额外复杂配置。

第 6 步：重新打开 Codex 会话或确认加载状态

项目级自定义 agent 可能需要重新打开项目、重启当前会话，或让 Codex 重新读取配置后才能稳定识别。

先问：

请告诉我当前会话是否已经能识别项目级自定义 Subagent：risk-reviewer。

要求：
1. 不要修改文件。
2. 如果需要重启会话或重新打开项目，请明确告诉我。
3. 如果可以直接使用，请说明我应该如何请求你调用它。

如果 Codex 建议重启，就重启当前 Codex 会话或重新打开项目。 不要在没加载成功前继续测试。

第 7 步：第一次调用自定义 Subagent

第一次调用必须只读。

复制这段：

请使用自定义 Subagent risk-reviewer 只读审查本次代码修改风险。

目标范围：
请优先审查本次任务涉及的改动文件和 Git diff。

要求：
1. 使用 risk-reviewer 这个自定义 Subagent。
2. 只读审查，不修改文件。
3. 不运行会改变项目状态的命令。
4. 不提交 Git。
5. 审查重点：无关改动、遗漏验证、回归风险、配置风险、交付说明是否清楚。
6. 等 risk-reviewer 完成后，由主会话汇总结果。

输出格式：
1. 被审查范围。
2. 总体判断。
3. 高 / 中 / 低问题列表。
4. 每条问题包含文件路径、问题、风险、原因、建议修复。
5. 最小下一步改进任务。

预期结果：

• Codex 明确使用 risk-reviewer。
• 子代理只读审查修改风险。
• 汇总结果带文件路径和风险等级。
• 没有文件被修改。

如果 Codex 没有使用自定义 agent，而是主会话自己审查，追问：

这次练习要求调用自定义 Subagent risk-reviewer。
请确认当前会话是否识别该 agent。
如果识别，请重新使用 risk-reviewer 只读审查。
如果不识别，请说明需要重启会话、调整文件位置，还是 TOML 配置有问题。
不要修改文件。

第 8 步：验收自定义 Subagent 是否合格

调用完成后，让 Codex 验收：

请验收 risk-reviewer 这个自定义 Subagent 是否创建成功。

验收标准：
1. .codex/agents/risk-reviewer.toml 存在。
2. 文件包含 name、description、developer_instructions。
3. 代理职责是代码修改风险只读审查。
4. 没有配置额外模型、沙盒、MCP、Skills。
5. 已经完成一次只读审查。
6. 审查结果包含文件路径、问题、风险、原因和建议修复。
7. 本次没有修改任何文件。

请按“通过 / 不通过 / 需要补充”的格式输出。

如果结果不通过，不要急着改复杂配置。 先修 developer_instructions。

例如：

risk-reviewer 输出太笼统。
请只修改 .codex/agents/risk-reviewer.toml 中的 developer_instructions。
目标：
让输出必须包含文件路径、风险等级、问题原因和建议修复。
不要修改其他文件。

回滚方式

如果不想保留这个自定义 agent，让 Codex 回滚：

请移除 risk-reviewer 自定义 Subagent。

要求：
1. 删除 .codex/agents/risk-reviewer.toml。
2. 如果 .codex/agents/ 目录为空，可以删除空目录。
3. 不要删除 .codex/ 下的其他配置。
4. 不要修改 AGENTS.md。
5. 删除后说明实际删除了哪些路径。

如果项目里已有其他 agents，不要删除目录。

常见问题

Codex 识别不到 risk-reviewer

优先检查：

• 文件是否放在 .codex/agents/。
• 文件扩展名是否是 .toml。
• name 是否是 risk-reviewer。
• TOML 是否有语法错误。
• 当前项目是否已重新打开或当前会话是否已重新加载。

让 Codex 只读排查：

请只读排查为什么当前会话识别不到 risk-reviewer。

要求：
1. 检查 .codex/agents/risk-reviewer.toml 是否存在。
2. 检查 TOML 必填字段。
3. 检查 name 是否正确。
4. 检查是否需要重启会话或重新打开项目。
5. 不要修改文件。

risk-reviewer 试图修改文件

立即停止：

请停止 risk-reviewer 的修改行为。
这个自定义 Subagent 第一版只能只读审查。
请说明它为什么尝试修改文件，并建议如何调整 developer_instructions。
不要继续执行修改。

然后只改 instructions：

请只修改 .codex/agents/risk-reviewer.toml 的 developer_instructions。
加强限制：该代理只能审查和输出建议，不能修改文件。
不要修改其他字段。

输出太像普通总结

说明 instructions 不够具体。 补充输出格式即可，不要增加复杂配置。

请优化 risk-reviewer 的 developer_instructions。

要求输出必须包含：
1. 文件路径。
2. 问题位置。
3. 风险等级。
4. 问题说明。
5. 为什么可能影响交付。
6. 建议修复方式。

不要增加模型、沙盒、MCP 或 Skills 配置。

本篇验收标准

完成本篇后，你应该能确认：

• 已创建 .codex/agents/risk-reviewer.toml。
• name、description、developer_instructions 字段正确。
• 代理职责足够窄。
• 代理第一版只读。
• 已完成一次只读审查。
• 审查结果比普通提示词更稳定。
• 你知道如何回滚。

下一步可以继续写团队工作流：如何把 AGENTS.md、Skills、Hooks、Subagents 组合成一套可持续的 Codex 使用规范。