# OpenClaw 子 Agent 架构设计（实用版） ## 目标 为 OpenClaw 建立一套**轻量、稳定、可扩展**的子 agent 协作模式。 核心原则不是“提前启动很多 agent 等任务”，而是： - 预先定义好少量高复用的 worker 模板 - 有任务时按模板临时拉起 - 做完后回报结果，由主 agent 汇总 这样能避免上下文污染、状态漂移和无谓的复杂度。 --- ## 设计原则 ### 1. 主 agent 负责决策，子 agent 负责执行 主 agent 职责： - 理解用户意图 - 判断风险与边界 - 拆分任务 - 选择合适 worker - 汇总结果并对用户输出 子 agent 职责： - 只处理单一、边界清晰的任务 - 在限定工具和上下文中执行 - 输出结构化结果 - 不自行扩展任务范围 --- ### 2. 预设模板，不预养常驻 worker 不建议维护一批长期常驻的子 agent，因为： - 上下文容易变脏 - 状态不透明 - 管理成本高 - 很容易出现“这个 agent 现在到底记得什么”的问题 推荐方式： - 保留 worker 角色模板 - 按需 spawn - 完成即回收或结束会话 --- ### 3. 默认少而精 第一阶段只保留 3～5 类高频 worker。 推荐优先级： 1. research-worker 2. ops-worker 3. code-worker 4. doc-worker 5. data-worker --- ## Worker 清单 ## 1. research-worker ### 适用场景 - Web 搜索 - 文档调研 - 技术方案对比 - 产品/竞品信息整理 - 多来源信息汇总 ### 推荐工具 - web_search - web_fetch - read ### 不应做的事 - 不做外部写操作 - 不代表用户公开表达观点 - 不把未经验证的信息说成确定事实 ### 输出格式 - 任务目标 - 已执行内容 - 结论 - 证据 - 不确定点 - 建议下一步 ### 典型任务示例 - 调研某功能最佳实践 - 比较两个技术方案差异 - 总结官方文档中的关键约束 --- ## 2. ops-worker ### 适用场景 - 服务状态检查 - 日志排查 - 配置诊断 - OpenClaw / gateway / cron / docker 巡检 - 健康检查与故障初步定位 ### 推荐工具 - exec - read - browser（仅在必须看 Web 管理界面时） ### 不应做的事 - 默认不做破坏性写操作 - 默认不改配置、不重启服务，除非明确授权 - 涉及安全策略、网络暴露、删除文件时必须上报主 agent ### 输出格式 - 任务目标 - 已执行内容 - 当前状态 - 发现的问题 - 可能原因 - 建议下一步 - 风险等级 ### 典型任务示例 - 检查 OpenClaw gateway 是否正常 - 查某服务为什么异常退出 - 验证某个 cron 是否实际生效 --- ## 3. code-worker ### 适用场景 - 读代码仓库 - 实现小功能 - 修 bug - 编写脚本 - 跑测试 - 生成代码修改建议 ### 推荐工具 - read - write - edit - exec - sessions_spawn（当明确转 ACP harness 时） ### 不应做的事 - 不直接做生产部署 - 不擅自删除重要文件 - 涉及大范围重构、不可逆修改、秘钥处理时必须上报 ### 输出格式 - 任务目标 - 已执行内容 - 修改文件 - 测试结果 - 风险/阻塞 - 建议下一步 ### 典型任务示例 - 修一个明确 bug - 增加一个小功能 - 分析 repo 启动方式 - 用 ACP harness 跑复杂 coding task --- ## 4. doc-worker ### 适用场景 - 会议纪要整理 - SOP 编写 - 知识库沉淀 - 文档结构化改写 - 把聊天记录整理成可复用文档 ### 推荐工具 - read - write - edit - feishu_doc（如目标是飞书文档） ### 不应做的事 - 不擅自发布正式对外文档 - 不覆盖已有关键文档，除非明确授权 - 对事实不确定的地方必须标注待确认 ### 输出格式 - 文档目标 - 产出摘要 - 保存位置 - 待确认问题 ### 典型任务示例 - 把故障排查过程整理成知识库 - 生成项目 README 初稿 - 整理会议纪要并提炼行动项 --- ## 5. data-worker ### 适用场景 - CSV / JSON / 文本批处理 - 数据抽取 - 清洗与标准化 - 简单统计 - 结构化导出 ### 推荐工具 - read - write - exec ### 不应做的事 - 不擅自删除源数据 - 默认保留原始文件 - 涉及敏感信息时必须清楚说明处理范围 ### 输出格式 - 输入说明 - 处理步骤 - 输出位置 - 异常数据/边界情况 - 建议下一步 ### 典型任务示例 - 从日志里提取错误类型 - 批量清洗联系人或记录 - 汇总文件夹中的结构化信息 --- ## 什么时候用 subagent，什么时候用 ACP ## 优先用 subagent 的场景 适合： - 调研 - 巡检 - 文档整理 - 数据处理 - 轻量代码任务 - 明确边界的后台任务 特点： - 轻量 - 启动快 - 适合主 agent 编排 --- ## 使用 runtime="acp" 的场景 适合： - 用户明确要求用 Codex / Claude Code / Gemini CLI 等 coding harness - 复杂代码改造 - 需要在大型 repo 内自主探索 - 需要较长生命周期的 coding session 特点： - 更适合工程性代码任务 - 不适合一般信息查询或简单整理任务 - `streamTo` 仅适用于 `runtime="acp"` ### 简单判断规则 - 非复杂代码任务：优先 subagent - 复杂代码任务 / 用户明确指定 harness：使用 ACP - `runtime="subagent"` 不应传 `streamTo` --- ## 调度规则（建议） ### 主 agent 自己完成 适合： - 简单问答 - 少于 3 步的小任务 - 小文件改动 - 单点查询 ### 调用 1 个子 agent 适合： - 需要独立搜索/分析/巡检 - 预计耗时较长 - 希望隔离上下文 ### 并行调用多个子 agent 适合： - 任务天然可拆分 - 彼此之间依赖弱 例如： - ops-worker 查本地状态 - research-worker 查官方文档 - 主 agent 汇总对比 ### 并行上限建议 初期建议最多同时 2～3 个子 agent。 超过这个数，主 agent 的协调和汇总成本通常会迅速升高。 --- ## 统一交付协议（强烈建议） 所有 worker 回报时，统一使用如下模板： - 任务目标 - 已执行内容 - 结果 - 风险/阻塞 - 建议下一步 如果是代码任务，再额外补充： - 修改文件 - 测试结果 如果是调研任务，再额外补充： - 证据来源 - 不确定点 统一格式的价值： - 降低主 agent 汇总成本 - 减少“每个子 agent 风格都不一样”的混乱 - 便于后续自动化处理 --- ## 外部动作审批原则 以下动作默认不能由子 agent 自主执行，必须回主 agent 或人工确认： - 删除重要文件 - 改生产配置 - 重启关键服务 - 发布对外内容 - 修改权限/共享范围 - 涉及敏感数据的外发 默认策略应为： **读多写少，先报后动。** --- ## 最小可落地版本（推荐起步方案） 第一阶段只正式启用这 3 个： ### A. research-worker 负责： - 搜索 - 阅读网页/文档 - 归纳结论 ### B. ops-worker 负责： - 状态检查 - 日志查看 - 配置诊断 ### C. code-worker 负责： - 代码探索 - 小修改 - ACP coding 委派 原因： - 覆盖率高 - 边界清晰 - 你最容易很快用起来 doc-worker 和 data-worker 可以在第二阶段补上。 --- ## 推荐落地顺序 ### 第一阶段：定义模板 为每个 worker 明确： - 角色说明 - 工具范围 - 禁止事项 - 输出格式 ### 第二阶段：定义主 agent 调度规则 明确： - 什么任务自己做 - 什么任务委派 - 什么任务必须审批 ### 第三阶段：补 prompt 模板 把每个 worker 的调用模板写成固定提示，方便直接 spawn。 ### 第四阶段：积累案例 将真实任务中的成功示例记录下来，逐步优化模板。 --- ## 一句话总结 最佳实践不是“提前养很多活着的子 agent”，而是： **保留少量高复用 worker 模板，让主 agent 按需拉起、统一编排、统一收口。** 这样最稳，也最符合 OpenClaw 的实际使用方式。