如何为 Codex 设置自定义子代理

这个想法源于一个简单的 Codex 配置思路：如果 Codex 能够将任务委派给子代理，那么有用的问题就不仅仅是“Codex 应该做什么？”，而是“Codex 应该委派什么？”

目标是建立一个可复用的本地并行工作设置，避免在主聊天上下文中塞满每一次调查、编辑和审查。

核心思路

主 Codex 聊天应扮演协调者的角色：

• 理解用户请求
• 决定哪些可以委派
• 确保关键路径持续推进
• 整合结果
• 做出最终决策

子代理应处理有边界的辅助任务：

• 快速代码库侦察
• 更深入的只读分析
• 小补丁
• 复杂实现工作

然后，技能（Skills）教会主聊天如何用简洁的指令派遣这些代理。

通用代理

我最终配置了六个通用代理。它们按两个维度组织：

• 努力级别
• 权限级别

努力级别：

spark = 最快，不那么详尽，适合侦察和小型编辑 high = 谨慎的默认推理，适用于常规重要工作 max = 用于最困难或风险最高任务的高强度推理

权限级别：

reader = 只读 writer = 工作区可写

由此产生以下网格：

spark-reader -> 快速只读侦察 spark-writer -> 快速小修改

high-reader -> 谨慎的只读分析 high-writer -> 常规复杂实现

max-reader -> 最大努力的只读分析 max-writer -> 最大努力的高风险实现

Spark 代理使用 gpt-5.3-codex-spark，推理努力为 medium。

High 代理使用 gpt-5.5，推理努力为 high。

Max 代理使用 gpt-5.5，推理努力为 xhigh。

以下是 max-writer 的配置示例：

name = "max-writer"
description = "最大努力的可写代理，用于最困难的变更，此时 xhigh 推理、验证和精度最为重要。"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
service_tier = "fast"
sandbox_mode = "workspace-write"

developer_instructions = """
以最大推理努力，进行谨慎、范围明确的编辑。
将这种额外努力用于困难的调试、微妙的正确性工作、架构敏感的变更、迁移和高风险修复。
在修改之前，理解相关的代码路径，保留现有模式，彻底验证，并清晰报告权衡和剩余风险。
如果任务需要更改面向用户的契约、广泛不相关的区域或模糊的产品决策，请停止并报告。
"""

全局配置

共享配置设置了代理限制并启用多代理工作：

[agents]
max_threads = 24
max_depth = 1
job_max_runtime_seconds = 3600

[features]
fast_mode = true
multi_agent = true

我特意保留了 max_depth = 1。递归委派虽然强大，但可能变得昂贵且难以推理。对于这个设置，直接子代理解就够了。

任务卡片模式

最重要的部分是任务卡片。

主聊天不是将整个对话发送给每个子代理，而是发送一个紧凑的任务：

Mission:
Scope:
Known context:
Do not touch:
Output needed:
Stop condition:

Writer 代理会得到一个稍微具体一些的版本：

Mission:
Owned write scope:
Allowed read scope:
Do not touch:
Behavioral requirements:
Validation expected:
Output needed:
Stop condition:

这保持了主线程的干净，并有助于保留上下文。子代理获得了足够的信息来行动，但无需了解整个历史。

你可以将其转化为一组针对 reader 和 writer 代理的技能，以避免每次都手动编写。

为什么这有帮助

这种设置使得 Codex 更易于引导：

• 使用 spark-reader 快速定位可能的文件
• 使用 high-reader 分析可疑路径
• 使用 max-reader 在错误答案代价高昂时使用
• 使用 spark-writer 进行小型编辑
• 使用 high-writer 进行常规实现
• 使用 max-writer 进行困难、风险的变更

主聊天仍然负责编排和最终判断。子代理是专注的执行者，而不是协调功能的替代。

要点

有用的模式是：

main chat = 协调者
agents    = 执行者
skills    = 调度规则

良好的多代理工作主要关乎边界：

• 明确的范围
• 明确的权限
• 明确的输出格式
• 明确的停止条件
• 谨慎的整合

一旦这些就位，~/.codex 就不仅仅是一个配置文件夹。它成为了并行编码工作的一个小型控制面板。

参考资料

• Codex subagents
• Codex speed
• Codex config reference
• Codex skills
• Agent Skills specification