W
AI-Wiki
SOURCE

OpenClaw多Agent协作：从一脸懵到真正跑通 摘要

文档概览

本教程核心目标是帮助读者彻底理解并跑通OpenClaw多Agent协作机制，解决新手面对workspace、agents、sessions等多个相似概念的混淆问题，内容覆盖核心概念解析、存储结构说明、协作逻辑讲解、配置方法、适用场景、避坑指南全链路，配套核心概念速查表与可直接落地的实操步骤，零基础开发者可按教程快速完成多Agent协作流程搭建。

关键事实

  1. 核心概念体系：OpenClaw多Agent体系共包含5个核心概念，可类比为公司组织架构逻辑：openclaw.json为HR系统，每个Agent对应工位（workspace）、员工档案（agentDir）、工作日志（sessions），派工单（subagents）用于任务下发。
  2. 单Agent存储结构：每个Agent对应OpenClaw单Agent存储结构三件套，功能完全独立：
    • workspace：存储Agent的身份定义（SOUL.md）、可用工具（TOOLS.md）、上下文记忆（memory/），决定Agent的能力与身份，默认路径为~/.openclaw/workspace，支持自定义路径
    • agentDir：存储系统级配置（模型参数、认证信息、运行状态），默认路径为~/.openclaw/agents/<agent_id>/agent
    • sessions：存储该Agent独立的对话历史，不同Agent的会话完全隔离
  3. 协作机制：多Agent协作通过4个内置工具实现，权限由subagents.allowAgents白名单控制，不在白名单内的Agent无法被调用。
  4. 核心配置文件：openclaw.json是整个系统的核心，等同于组织架构图+通讯录+权限表三合一，存储所有Agent的唯一ID、workspace路径、agentDir路径、可调用子Agent白名单，OpenClaw仅认该配置内容，不扫描磁盘目录自动识别Agent。
  5. ****agency-agents本质：是预制的workspace模板集合，并非系统内置功能，需完成「落地workspace→创建agentDir→注册到openclaw.json」三步流程后方可使用，也可直接导入对应GitHub仓库批量注册。
  6. 适用场景：仅当任务涉及多专业能力、需并行处理时使用多Agent，单一简单任务无需拆分；典型适用场景为主从协作（1个调度Agent拆分任务下发给多个专业Agent并行处理）、临时外援（不中断主线会话的前提下调用专属Agent处理支线任务）。
  7. 任务拆分原则：多Agent任务拆分原则为按产出物拆分，而非按动作拆分，每个子Agent对单一明确的产出结果负责。
  8. 典型坑点：共梳理3个新手高频踩坑点，均对应明确的解决方案。
  9. 落地路径：提供最小可用快速上手路径，建议从1个主Agent+2个子Agent的最简架构开始跑通链路，再逐步扩展。

重要细节

协作工具与权限逻辑

  • sessions_spawn是调用子Agent的核心工具，仅能调用subagents.allowAgents白名单内的Agent，不会扫描磁盘目录识别未注册的Agent
  • agents_list工具用于查询当前Agent可调用的子Agent名单，返回结果仅包含白名单内的Agent

agency-agents注册流程

  1. 准备workspace：将预制角色模板放入对应目录（如~/.openclaw/**agency-agents**/seo-specialist/）
  2. 创建agentDir：生成系统状态目录（如~/.openclaw/agents/seo-specialist/agent/）
  3. 注册配置：通过openclaw agents add <agent_id>命令将Agent信息写入openclaw.json

3个典型坑点

  1. 误以为磁盘目录存在即等于Agent存在：OpenClaw仅读取openclaw.json配置识别Agent，未注册的Agent即使目录存在也无法被调用
  2. 混淆workspace与agentDir：口诀为「办公桌上放文件（workspace存业务相关配置），档案柜里放工卡（agentDir存系统级配置）」
  3. 未配置subagents.allowAgents导致权限混乱：建议按协作关系设置权限，调度Agent可调用所有专业Agent，专业Agent之间默认不开放互相调用权限

最小可用上手步骤

  1. 准备1个主Agent、1个专业子Agent的workspace模板
  2. 完成两个Agent的注册流程，写入openclaw.json
  3. 为主Agent配置子Agent的调用白名单
  4. 测试主Agent调用子Agent完成简单任务，确认链路通了之后再扩展更多Agent与复杂工作流

相关条目

  • OpenClaw
  • OpenClaw多Agent协作机制
  • OpenClaw单Agent存储结构
  • 多Agent任务拆分原则
  • agency-agents