自定义 Subagent 适合处理那些职责明确、规则稳定且需要并行工作的专项任务。对于新手，推荐从创建一个只读的“风险审查员”（risk-reviewer）开始，这能让你在安全受控的前提下掌握子代理的配置逻辑。
为什么选择“风险审查”作为第一个案例？
- 职责清晰：仅负责检查修改风险，不涉及代码修改。
- 安全性高：只读模式避免了并行写文件可能导致的冲突。
- 价值明显：每次交付前都需要进行范围与质量的二次确认。
创建步骤
第一步：定义角色职责
一个标准的自定义 Subagent 需要在 TOML 配置文件中定义三个核心字段：
name: 代理的唯一标识，如risk-reviewer。description: 描述该代理的用途，帮助主会话判断何时调用它。developer_instructions: 定义该代理的工作规则、审查清单及输出格式。
第二步：编写配置文件
在项目根目录创建 .codex/agents/risk-reviewer.toml。第一版建议保持极简，仅配置上述三个字段，暂不涉及复杂的模型切换或沙盒调整。
配置示例：
``toml
name = "risk-reviewer"
description = "审查代码修改风险，防止范围失控与回归错误。"
developer_instructions = """
你是只读风险审查员。
你的任务是检查本次改动是否超出范围、是否存在安全隐患及是否符合项目规范。
严禁修改任何文件或执行写操作。
最后按高、中、低三个等级列出发现的问题及修复建议。
"""
`
第三步：加载与验证
重启 Codex 会话以确保新代理被正确加载。通过提示词指派任务：“请使用自定义 Subagent risk-reviewer 审查本次修改的风险”。
第四步：效果评估
观察子代理的输出是否比主会话更专业、更专注。检查其是否严格遵守了“不修改文件”的限制。
核心原则
- 边界要窄：不要创建“全能工程师”子代理，那会导致职责重叠。
2. 先做只读：在未掌握并行控制前，禁止让子代理自动修复代码。
3. 保持独立：子代理的输出应回到主会话汇总，由你做最终决策。
回滚与清理
如果不满意，只需删除 .codex/agents/ 下对应的 .toml` 文件即可，不会对项目代码产生任何副作用。
通过这一低风险的练习，你将能建立起对 Codex 并行协作能力的初步认知，为后续构建复杂的自动化工作流打下基础。