Codex 子代理（Subagents）

子代理（Subagents）是 Codex 的高级功能，允许你将大型任务分解为更小的部分，并行或顺序处理。本节详细介绍如何配置和使用子代理。

什么是子代理？

子代理是 Codex 可以并行调用的辅助代理，用于处理复杂任务的不同部分。通过配置子代理，你可以：

  • 将大型任务分解为可管理的部分
  • 并行处理多个独立任务
  • 为不同类型的任务配置专门的代理
  • 提高处理大型项目的效率
子代理特别适合需要同时处理多个文件或多个独立任务的场景。

配置子代理

基础配置

配置子代理

# 启用多代理功能
[features]
multi_agent = true

# 配置代理参数
[agents]
# 最大并行线程数
max_threads = 6

# 最大嵌套深度
max_depth = 1

# 作业最大运行时间（秒）
job_max_runtime_seconds = 1800

自定义代理角色

你可以在配置中定义自定义代理角色：

定义代理角色

# 定义一个代码审查代理
[agents.reviewer]
description = "专注于代码审查和质量问题"
nickname_candidates = ["Reviewer", "CodeChecker", "QualityBot"]

# 可以指向一个配置文件
# config_file = "agents/reviewer.toml"

使用子代理

手动调用子代理

在 Codex 中，你可以使用以下方式调用子代理：

调用子代理

# 使用 @ 提及子代理
@reviewer 审查 src/auth.py 文件

# 使用 /agents 命令
/agents run reviewer --task "审查所有测试文件"

自动使用子代理

Codex 可以根据任务自动选择使用子代理。例如，对于大型重构任务，Codex 可能会自动启动多个子代理来处理不同的模块。

子代理的工作原理

Codex 子代理架构
图：Codex 子代理架构

并行处理

当任务可以分解为独立的部分时，子代理可以并行工作：

任务：审查整个代码库
  ├─ 子代理 1：审查 src/auth/ 目录
  ├─ 子代理 2：审查 src/api/ 目录
  ├─ 子代理 3：审查 src/utils/ 目录
  └─ 主代理：汇总结果

顺序处理

当任务有依赖关系时，子代理按顺序工作：

任务：实现新功能
  └─ 子代理 1：创建数据模型
       └─ 子代理 2：创建 API 端点
            └─ 子代理 3：编写测试

嵌套深度

配置中的 max_depth 控制代理可以嵌套的层数：

  • 深度 0：根会话
  • 深度 1：直接子代理
  • 深度 2：子代理的子代理
建议将 max_depth 保持在 1 或 2，过深的嵌套会增加复杂性和成本。

工具调用

子代理可以使用 Codex 的所有标准工具：

  • 读取和编辑文件
  • 执行命令
  • 使用技能
  • 调用 MCP 服务器

结果汇总

主代理负责汇总所有子代理的结果，提供统一的输出。

代理角色配置

创建自定义代理角色

创建代理角色配置文件

# agents/tester.toml

description = "专注于编写单元测试和集成测试"
nickname_candidates = ["Tester", "TestBot", "QABot"]

[behavior]
# 代理的行为配置
test_framework = "pytest"  # 偏好的测试框架
include_coverage = true     # 要求包含覆盖率报告

在主配置中引用

引用代理配置

[agents.tester]
config_file = "agents/tester.toml"

监控子代理

查看活跃代理

查看活跃代理

# 在 Codex 中查看
/agents status

# 查看详细信息
/agents list

代理输出

Codex 会显示每个子代理的输出，并在主界面中汇总结果。

子代理运行时会显示进度指示器，让你了解整体任务状态。

最佳实践

任务分解

  • 将大型任务分解为独立的子任务
  • 确保子任务之间没有强依赖（可以并行时）
  • 为每个子任务定义清晰的输入和输出

配置优化

  • 根据任务复杂度调整 max_threads
  • 为不同类型的任务配置专门的代理角色
  • 设置合理的 job_max_runtime_seconds 避免长时间运行

监控和调试

  • 定期检查子代理的输出
  • 使用 /agents status 了解整体进度
  • 必要时可以取消特定的子代理
子代理是高级功能，建议先熟悉 Codex 的基础操作后再使用。

常见问题

Q: 子代理和技能有什么区别？

子代理是独立的 AI 代理，可以执行复杂的多步骤任务。技能是预定义的工作流，专注于特定类型的任务。

Q: 最多可以同时运行多少个子代理？

通过 max_threads 配置，默认是 6。实际可用数量取决于你的订阅计划。

Q: 子代理可以访问我的文件吗？

是的，子代理可以读取和修改文件，但受到沙箱和安全策略的限制。

Q: 如何调试子代理的问题？

使用 /agents status 查看代理状态，查看它们的输出日志来定位问题。