Codex Subagent 实用教程：并行 AI 代理工作流揭秘

Codex Subagent（子代理）是官方推出的并行化 AI 任务协作机制，允许主代理按需创建多个专业化子代理，并行拆解执行复杂任务、汇总结果后统一输出，尤其适合代码审查、多维度检测、批量审计、跨模块开发等高并发、高复杂度场景。本文基于官方 Subagent 文档，完整讲解子代理的工作原理、使用流程、管理方式、自定义配置与批量任务实战，帮助开发者用并行化 AI 大幅提升复杂任务处理效率。

一、Subagent 核心认知

1.1 什么是 Subagent

Subagent 是由主 Codex 代理 Spawn（创建）的独立工作线程，每个子代理可拥有专属模型、指令集、沙箱权限与技能栈，主代理负责调度、等待、汇总结果，形成一主多从的并行协作架构。

1.2 核心特性

• 默认启用：最新版 Codex 已默认开启子代理工作流，无需额外配置开关；

• 显式触发：仅在用户明确要求创建子代理时才会 Spawn，不会自动创建；

• 消耗说明：子代理会独立执行模型推理与工具调用，Token 消耗高于单代理任务；

• 全端支持：CLI 与桌面端完整支持，IDE 扩展可视化能力即将上线。

1.3 适用场景

• 多维度 PR 审查（安全、质量、Bug、可维护性并行检查）；

• 大型代码库批量审计（文件 / 包 / 服务逐一审视）；

• 多模块功能并行开发与调试；

• 前端 UI 问题：浏览器复现、代码定位、修复并行执行；

• 批量任务自动化处理（CSV 批次任务）。

二、典型子代理工作流

子代理采用主代理调度→子代理并行执行→结果汇总返回的标准化流程，全程无需手动管理线程。

标准执行步骤

1. 用户在提示词中明确要求 Spawn 子代理，并指定分工；

2. 主代理解析任务，创建对应数量的子代理线程；

3. 子代理并行执行各自任务，主代理等待全部完成；

4. 主代理收集所有子代理结果，整理为结构化报告输出；

5. 可手动关闭完成的线程，或让主代理自动管理生命周期。

快速上手示例（PR 审查）

直接在 Codex 中输入以下提示，一键触发多代理并行审查：

我需要对当前分支对比main的PR做以下审查，为每个检查点创建一个子代理，等待全部完成后汇总结果：
1. 安全漏洞检测
2. 代码质量规范
3. 潜在Bug
4. 竞态条件
5. 测试用例完整性
6. 代码可维护性

执行后，Codex 会自动创建 6 个子代理并行工作，最终返回分点总结报告。

三、子代理管理命令

在 CLI 中使用 /agent 命令集，可对子代理线程进行查看、切换、停止、关闭等操作。

核心管理命令

# 查看所有活跃代理线程
/agent

# 切换到指定代理线程（查看执行日志、上下文）
/agent <线程ID>

# 停止运行中的子代理
/agent stop <线程ID>

# 关闭已完成的代理线程
/agent close <线程ID>

# 关闭所有闲置线程
/agent close-all

线程状态说明

• running：正在执行任务；

• waiting：等待审批 / 资源；

• completed：执行完成，等待结果汇总；

• closed：已关闭，释放资源。

四、审批与沙箱权限控制

子代理的安全策略继承自主代理，同时支持精细化覆写，保障执行安全。

4.1 权限继承规则

• 子代理默认继承当前会话的沙箱模式、审批策略、MCP 与技能配置；

• 会话内手动修改的配置（如/approvals、--yolo）会同步覆盖给子代理；

• 未信任项目的子代理同样无法加载项目级配置与钩子。

4.2 审批弹窗处理

• 非活跃线程也可能弹出审批请求，弹窗会标注来源线程 ID；

• 按o可快速跳转到对应线程，查看上下文后再审批 / 拒绝；

• 非交互式场景下，需要审批的任务会直接失败并返回错误给主代理。

4.3 子代理独立沙箱配置

自定义代理可独立指定沙箱模式，实现权限精细化管控：

# 只读审查专用代理
sandbox_mode = "read-only"

五、内置代理类型

Codex 提供 3 种开箱即用的内置代理，覆盖绝大多数通用场景：

1. default：通用型默认代理，平衡推理与执行，适合大多数任务；

2. worker：执行型代理，专注代码实现、修复、重构，效率优先；

3. explorer：探索型代理，只读代码库分析、路径梳理、结构探测，无写入权限。

直接在提示词中指定代理类型即可使用：

使用explorer代理梳理项目代码结构，worker代理修复入口文件Bug

六、自定义代理创建

可创建专属配置的自定义代理，适配团队规范、专项任务，支持全局与项目级两层配置。

6.1 配置文件路径

• 全局代理（所有项目生效）：~/.codex/agents/xxx.toml

• 项目代理（仅当前项目生效）：项目根目录/.codex/agents/xxx.toml

6.2 必填字段（必须配置）

每个自定义代理文件必须包含 3 个核心字段：

• name：代理唯一名称（用于调用、调度）；

• description：使用场景说明，主代理匹配任务时使用；

• developer_instructions：核心行为指令，定义代理的工作规则。

6.3 可选覆写字段

可按需覆写常规配置，实现完全个性化：
model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config、nickname_candidates。

6.4 自定义代理示例（PR 审查员）

文件路径：.codex/agents/reviewer.toml

name = "reviewer"
description = "专注正确性、安全、测试缺失的PR审查代理"
developer_instructions = """
以代码所有者视角审查，优先检查：
1. 逻辑正确性与回归风险
2. 安全漏洞与权限问题
3. 缺失的测试用例
4. 具体可复现的问题，不做纯风格评论
"""
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
nickname_candidates = ["Guardian", "Inspector", "Reviewer-Pro"]

6.5 昵称配置

nickname_candidates用于 UI 展示区分多实例代理，仅作显示，不影响调度。

七、全局子代理参数配置

在config.toml中配置全局子代理运行限制，避免资源过度消耗。

# 全局代理配置
[agents]
# 最大并发线程数，默认6
max_threads = 6
# 最大嵌套深度，默认1（禁止孙代理创建）
max_depth = 1
# CSV批量任务默认超时，默认1800秒
job_max_runtime_seconds = 1800

参数说明

• max_threads：限制并行代理数量，防止本地 / 模型资源过载；

• max_depth：嵌套深度，默认 1（仅允许子代理，不允许孙代理），调高会大幅增加消耗；

• job_max_runtime_seconds：批量任务单代理超时时间，防止死循环任务。

八、实验特性：CSV 批次任务处理

spawn_agents_on_csv是实验级批量任务能力，支持按 CSV 行创建子代理，批量执行同类任务。

适用场景

• 批量审查项目文件；

• 批量检查 PR / 工单；

• 批量生成结构化报告。

使用示例

1. 创建 CSV 文件 /tmp/components.csv：

path,owner
src/components/Button.tsx,front-end
src/components/Modal.tsx,front-end
src/components/Form.tsx,front-end

2. 提示词触发批量任务：

使用spawn_agents_on_csv处理以下任务：
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "审查{path}组件，归属{owner}，返回path、risk、summary、follow_up字段"
- output_csv_path: /tmp/components-review.csv
- output_schema: {"path":"string","risk":"string","summary":"string","follow_up":"string"}

3. 执行命令：

codex exec "执行上述批量审查任务"

执行完成后，结果自动导出到components-review.csv，包含状态、错误信息、结构化结果。

九、实战场景示例

场景 1：多代理并行 PR 审查

1. 配置 3 个专项代理：pr_explorer（代码探测）、reviewer（安全审查）、docs_researcher（文档校验）；

2. 提示词：

审查当前分支对比main的修改，pr_explorer梳理影响路径，reviewer检查安全与Bug，docs_researcher校验API文档一致性

3. 主代理调度 3 个代理并行执行，输出整合报告。

场景 2：前端 UI 问题并行调试

1. 配置 3 个代理：browser_debugger（浏览器复现）、code_mapper（代码定位）、ui_fixer（问题修复）；

2. 提示词：

排查设置弹窗无法保存的问题，browser_debugger复现问题，code_mapper定位代码，ui_fixer做最小化修复

3. 子代理按顺序并行 / 串行协作，快速定位并解决问题。

十、常见问题排查

1. 子代理无法创建

   • 检查max_threads是否达到上限，关闭闲置线程；

   • 确认提示词明确要求spawn subagents；

   • 重启 Codex 重置线程状态。

2. 审批弹窗不显示

   • 交互式 CLI 才会弹出审批，非交互式直接失败；

   • 按o查看对应线程上下文，确认审批来源。

3. 自定义代理不生效

   • 检查文件路径是否在agents/目录；

   • 确认必填name/description/developer_instructions完整；

   • 文件名与代理名建议保持一致，便于识别。

4. 批量 CSV 任务失败

   • 检查 CSV 格式正确，列名匹配占位符；

   • 确认output_schema格式合法；

   • 调高job_max_runtime_seconds避免超时。

十一、最佳实践

1. 单代理单职责：自定义代理专注单一任务，避免泛用化，提升执行精度；

2. 嵌套深度默认：保持max_depth=1，禁止深层嵌套，降低 Token 消耗与不可控性；

3. 只读优先：审查、探测类代理固定sandbox_mode="read-only"，杜绝误修改；

4. 并发数控制：个人开发max_threads设为 3-6，团队环境适当调高；

5. 显式触发：始终明确要求创建子代理，不依赖隐式匹配；

6. 及时清理：完成任务后关闭闲置线程，释放本地与模型资源；

7. 批量慎用：CSV 批量任务仅用于稳定、重复的审计场景，实验特性谨慎用于生产环境。

十二、总结

Codex Subagent 把 AI 编程从单线程执行升级为并行化团队协作，通过主从代理架构，让复杂、多维度、大批量的开发任务得以并行处理，效率成倍提升。内置代理满足通用场景，自定义代理适配团队专属规范，配合沙箱、审批、全局限流策略，可在安全可控的前提下最大化并行优势。无论是日常 PR 审查、大型项目调试，还是批量代码审计，Subagent 都能成为高效处理复杂任务的核心能力。