05-子会话（Sub-agent）与任务编排

OpenClaw 第五篇：子会话（Sub-agent）与任务编排一句话概括：子会话是 OpenClaw 实现任务并行化、多智能体协作的核心机制。掌握它，你就能将复杂任务拆分为多个独立执行单元，大幅提升 AI 系统的处理能力和响应效率。前言随着 AI 应用的复杂度不断提升，单个会话往往需要处理多样化的任务——从数据分析到代码生成，从文档撰写到多平台消息处理。如果所有任务都在主会话中串行执行，不仅效率低下，还容易造成上下文混乱。OpenClaw 的子会话（Sub-agent）机制正是为解决这一问题而生。它允许你将复杂任务拆分为多个独立的执行单元，每个子会话都有自己的上下文、工具和生命周期，既能并行处理提高效率，又能通过消息机制实现协作。本文将深入探讨子会话的工作原理、使用场景以及实战技巧，帮助你构建更强大的多智能体协作系统。1. 何时使用子会话？1.1 使用场景分析子会话特别适合以下场景：场景类型说明示例任务并行化多个独立任务可以同时进行同时处理 10 个文件的分析请求上下文隔离不同任务需要独立的上下文代码审查与文档编写同时进行资源隔离防止一个任务影响其他任务一个子任务出错不中断主流程多步骤工作流复杂的流水线处理数据采集→清洗→分析→报告生成多智能体协作不同角色分工合作研究员、编辑、审校并行工作1.2 子会话 vs 主会话的区别理解子会话和主会话的区别，是正确使用子会话的前提：特性主会话子会话生命周期与用户交互期间持续存在任务完成后自动清理上下文隔离共享用户完整对话历史仅包含分配的任务描述工具访问继承所有配置的工具可独立配置工具集错误影响影响整个交互流程仅影响当前子任务并发能力单线程处理支持多实例并行资源占用持续占用按需创建和释放1.3 性能与资源考量使用子会话时需要权衡的关键因素：优势：并行加速：I/O 密集型任务可显著缩短总耗时故障隔离：单个子会话崩溃不影响主流程资源弹性：根据负载动态扩缩容代码复用：相同逻辑可在多个子会话中复用注意事项：模型调用成本：每个子会话都消耗独立的 API 额度并发上限：需根据 API 配额和系统资源合理设置结果聚合：并行任务的结果需要额外的同步和整合逻辑最佳实践原则：计算密集型且相互独立的任务 → 使用并行子会话需要严格顺序执行的任务 → 保持串行处理上下文强依赖的任务 → 考虑在主会话中执行2. sessions_spawn 详解sessions_spawn是 OpenClaw 提供的核心 API，用于创建和管理子会话。掌握其参数含义，是构建复杂任务编排系统的关键。2.1 方法签名与参数说明interfaceSessionSpawnOptions{// 任务描述：子会话将以此作为初始上下文task:string;// 运行时类型：'subagent' | 'acp'runtime?:'subagent'|'acp';// 执行模式：'run' | 'session'mode?:'run'|'session';// 子会话标签，用于标识和后续查询label?:string;// 指定模型，默认继承主会话配置model?:string;// 工作目录，默认继承主会话workspaceDir?:string;// 超时时间（秒），0 表示不超时runTimeoutSeconds?:number;// 清理策略：'keep' | 'auto' | 'immediate'cleanup?:'keep'|'auto'|'immediate';// 是否等待完成消息expectsCompletionMessage?:boolean;}// 调用方式constresult=awaitsessions_spawn({task:"分析这份销售数据并生成图表",runtime:"subagent",mode:"run",label:"data-analysis-task-001"});2.2 runtime 参数：subagent vs acpruntime参数决定了子会话的执行环境：subagent（默认）在 OpenClaw 的标准子代理环境中运行：{runtime:"subagent",// 子会话拥有完整的 OpenClaw 工具集// 包括：文件操作、数据库访问、API 调用等}适用场景：需要访问文件系统或数据库使用 OpenClaw 的 Skills 系统与其他 OpenClaw 功能深度集成acp（Agent Coding Protocol）在 ACP 兼容的编码环境中运行：{runtime:"acp",// 子会话在代码编辑器环境中运行// 特别适合代码生成、重构、分析任务}适用场景：代码审查和重构大型项目的代码生成需要与 IDE 功能（如 LSP）集成对比总结：维度subagentacp主要用途通用任务处理代码相关任务工具集OpenClaw Skills代码工具链上下文自然语言为主代码为主输出格式灵活结构化代码2.3 mode 参数：run vs sessionmode参数控制子会话的执行模式：run 模式（默认）子会话执行指定任务后自动终止：{mode:"run",task:"分析这份报告并总结关键发现"// 任务完成后子会话自动结束}特点：任务完成即终止，资源立即释放适合一次性、明确的任务自动返回执行结果session 模式创建持久化的子会话，可后续交互：{mode:"session",task:"作为数据分析助手，等待后续指令"// 子会话保持活跃，可后续发送消息}特点：会话保持活跃状态可通过消息机制持续交互需要显式终止选择建议：// 简单任务 → run 模式awaitsessions_spawn({mode:"run",task:"生成今日工作报告"});// 需要持续交互 → session 模式constsessionId=awaitsessions_spawn({mode:"session",task:"作为客户支持专员，处理用户咨询"});// 后续可通过 sessionId 发送消息2.4 任务超时与清理超时设置{// 5 分钟超时runTimeoutSeconds:300,// 永不超时（默认值）runTimeoutSeconds:0}超时后子会话会自动终止，避免资源浪费。清理策略{// 保留子会话记录，用于调试和审计cleanup:"keep",// 任务完成后自动清理（推荐用于生产环境）cleanup:"auto",// 立即清理，不保留任何痕迹cleanup:"immediate"}3. 子会话生命周期管理3.1 创建与启动创建子会话的基本流程：// 示例：创建一个数据分析子会话asyncfunctioncreateAnalysisSubagent(dataFile){constresult=awaitsessions_spawn({task:`请分析文件${dataFile}中的数据： 1. 读取并解析 CSV 格式 2. 计算关键统计指标（均值、中位数、标准差） 3. 识别异常值 4. 生成分析摘要 完成后将结果保存到 analysis_result.json`,runtime:"subagent",mode:"run",label:`analysis-${Date.now()}`,runTimeoutSeconds:600,// 10 分钟超时cleanup:"auto"});returnresult;}3.2 状态查询在子会话执行期间，可以通过sessions_list查询状态：// 查询所有活跃的子会话constactiveSessions=awaitsessions_list({status:"running"});// 查询特定标签的子会话constmyTasks=awaitsessions_list({label:"analysis-*"});// 子会话状态可能值：// - pending: 等待启动// - running: 执行中// - completed: 已完成// - failed: 执行失败// - timeout: 超时终止3.3 消息传递对于mode: "session"创建的持久化子会话，支持双向消息传递：// 创建持久化子会话constsessionId=awaitsessions_spawn({mode:"session",task:"作为代码审查助手，等待代码提交"});// 向子会话发送消息awaitsession_send(sessionId,{