SubAgent 是主 Agent 动态派生的临时并行单元，用于解决响应延迟、上下文混乱与高成本问题；需满足可拆分任务、启用 spawn 权限、开放 sessions_spawn 工具、支持模型降级，并通过命令行、工作流嵌入、CLI 管理及专用工具配置实现安全隔离执行。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 OpenClaw 处理复杂任务时遇到响应延迟、上下文混乱或成本过高的问题，则很可能是主 Agent 独自承担全部工作所致。SubAgent 机制正是为解决此类问题而设计的并行执行单元。以下是具体使用方法：
一、理解 SubAgent 的核心定位与触发时机
SubAgent 是主 Agent 在运行中动态派生的临时执行单元，具备完全隔离的会话环境和精简上下文，适用于需并行处理、领域专注或成本敏感的子任务。它不长期驻留，任务完成即销毁，避免资源冗余。
1、确认当前任务是否满足“可拆分”特征：包含多个逻辑独立环节（如同时查资料、写报告、生成图表）；
2、判断主 Agent 是否已配置 spawn 权限：检查 AGENTS.md 中 main agent 的 maxSpawnDepth ≥ 1；
3、确保 TOOLS.md 已启用 sessions_spawn 工具 并未被禁用；
4、验证模型路由策略是否支持子代理降级：例如主 Agent 使用 Opus，SubAgent 显式指定 Haiku 或 Sonnet。
二、通过命令行直接调用 SubAgent
该方式适用于调试、脚本集成及快速验证子任务流程，无需修改配置文件即可立即启动隔离执行环境。
1、在主会话中输入指令：/subagents spawn --task "分析用户反馈情感倾向" --model haiku --timeout 60；
2、系统返回唯一 runId（格式为 agent::subagent:xxxx-xxxx），主会话立即恢复响应；
3、等待 announce 频道推送结果，或使用 /subagents status --runid xxx 主动查询；
4、结果将以结构化 JSON 形式回传至主会话上下文，可被后续步骤直接引用。
三、在工作流中嵌入 SubAgent 调用
通过编辑 AGENTS.md 或自定义 Skill，在任务编排逻辑中声明子代理调用点，实现自动化任务分流。此方式适合高频、固定模式的复杂流程。
1、打开 ~/.openclaw/agents/main/AGENTS.md 文件；
2、在对应 Skill 或 workflow block 中添加 spawn 指令块，例如：- tool: sessions_spawn\n input:\n task: "提取PDF中的技术参数表格"\n model: sonnet\n tools: ["pdf_parser"]；
3、保存文件后重启 main agent 或执行 clawhub reload agent main；
4、当该 Skill 被触发时，系统自动创建子代理并加载指定工具集，主 Agent 继续执行后续步骤。
四、使用 ClawHub CLI 批量管理 SubAgent 实例
当需要跨多个会话或批量监控子任务状态时，ClawHub CLI 提供底层控制能力，绕过 Web UI 限制，适用于运维与集成场景。
1、执行 clawhub subagents list --status running 查看所有活跃子代理；
2、使用 clawhub subagents logs --runid agent::subagent:abcd1234 获取实时执行日志；
3、对异常子任务执行强制终止：clawhub subagents kill --runid agent::subagent:abcd1234；
4、导出历史子任务统计：clawhub subagents report --from "2026-03-25" --to "2026-03-27"。
五、配置 SubAgent 的专用权限与工具集
默认 SubAgent 不继承主会话工具权限，必须显式声明可用工具，以保障安全隔离与执行确定性。此配置直接影响子任务能否成功调用外部能力。
1、编辑 ~/.openclaw/agents/main/TOOLS.md，在 subagent-scoped 区块下定义工具白名单；
2、为每个允许的工具添加 subagent: true 标记，例如：- name: web_search\n subagent: true\n config: {max_results: 3}；
3、在 spawn 指令中通过 tools: ["web_search", "json_formatter"] 显式指定本次子任务可调用项；
4、验证子代理会话中仅加载 AGENTS.md 与 TOOLS.md 两个文件，无 USER.md 或 MEMORY.md 干扰。
