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"]；
OpenClaw 7×24 小时长稳运行方案 — 进程守护、异常重启、断连重连、断点续跑、资源回收、日志监控。确保 OpenClaw 零崩溃、零断连、零漏执行。无人值守必备。
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 干扰。
