从底层机制一文讲透：OpenClaw🦞如何运行多Agents

从底层机制一文讲透：OpenClaw🦞如何运行多Agents 从底层机制一文讲透：OpenClaw🦞如何运行多Agents Modified March 15 这个目录名不是内建保留字，也不是系统默认必须存在的层级。 它之所以在当前实例里“有效”，是因为： • 某些 agent 的 workspace • 被配置到了 /.openclaw/agency agents/<agent id 也就是说： OpenClaw 原生负责的是： • 认 workspace • 认 agentDir • 认 agentId • 认配置 agency agents 提供的是： • 一批预先写好的 agent workspace • 一种方便组织角色模板的目录结构 所以它更像： 被接入 OpenClaw 的 agent 模板/workspace 仓库 而不是 OpenClaw 系统本身的一层。简单讲： agency agents本质上是 workspace （工作区）！！！！！！ 九、 agency agents 和 OpenClaw 原生概念如何对应？ 如果当前机器把某个 agent 配成这样： • workspace = /.openclaw/agency agents/seo specialist • agentDir = /.openclaw/agents/seo specialist/agent 那么它们的关系就是： /.openclaw/agency agents/seo specialist 对应的是这个 agent 的 workspace /.openclaw/agents/seo specialist/agent 对应的是这个 agent 的 agentDir /.openclaw/agents/seo specialist/sessions 对应的是这个 agent 的 会话历史 十、那 agency agents 应该怎么安装？ 讲到这里，安装逻辑就容易明白了。 如果 agency agents 只是一个外部 workspace 模板来源，那么“安装它”就不应该被理解成： 把 repo clone 下来就完事 更准确的理解应该是： 把这些 workspace 接入 OpenClaw 的 agent 配置体系。 通常要经过几步： 第一步：准备 workspace 例如： • /.openclaw/agency agents/seo specialist 这里放角色工作区内容。 第二步：准备 agentDir 例如： • /.openclaw/agents/seo specialist/agent 这里放状态目录。 第三步：注册进 OpenClaw 也就是把这个 agent 写进 openclaw.json ，或者通过官方命令添加： Code block Plain Text Copy openclaw agents add seo specialist \ workspace /.openclaw/agency agents/seo specialist \ agent dir /.openclaw/agents/seo specialist/agent \ non interactive 备注：当然，你并不真的需要挨个安装，只需要把agency agents的Github仓库喂给openclaw，让它理解之后安装即可； 这一步完成后，OpenClaw 才真正“认识”这个 agent。 所以，“安装 agency agents”这件事，本质上不是文件复制，而是： workspace 落地 + agentDir 准备 + agent 配置注册 十一、OpenClaw 是怎么调用这些来自 agency agents 的 agent 的？ 答案其实已经呼之欲出了： OpenClaw 调用的不是“agency agents 目录”，而是： 配置文件中定义的 agent 而这个 agent 的 workspace ，恰好指向了 agency agents 里的目录。 所以链路是： 1. sessions spawn(agentId=...) 2. OpenClaw 查配置 3. 找到该 agent 的 workspace 4. 找到该 agent 的 agentDir 5. 用这套上下文和状态启动子会话 这也是为什么： • agency agents 本身不是内置概念 • 但它依然可以很好地融入 OpenClaw 体系 因为 OpenClaw 看的是“配置结果”，不是“目录名字”。 十二、工作中到底该怎么用多 agent 协作？ 把概念讲清楚之后，再谈工作方法才不会漂。 1. 单 agent 适合什么情况？ 如果任务是： • 短 • 集中 • 不需要多角色分工 • 不需要并行探索 那单 agent 就够了。 例如： • 看一份日志 • 回答一个技术问题 • 改一段简单脚本 这类任务硬拆成多 agent，反而会增加协调成本。 2. 什么时候该用 sessions spawn 启动其他 agent？ 当一个任务天然带有“分工需求”时，通过 sessions spawn 启动其他 agent 才真正有价值。 典型场景 A：主从协作模式 • 主 agent 负责总控和用户对话 • 通过 sessions spawn 启动 seo specialist 分析关键词 • 通过 sessions spawn 启动 frontend developer 实现页面 • 主 agent 汇总结果，统一输出 这时候的意义不是“多开几个窗口”，而是 给不同任务块分配稳定角色 。 典型场景 B：临时专项任务 • 已经有主任务在进行 • 但其中一个子问题可以独立解决 • 希望隔离上下文，避免污染主会话 • 或者希望并行推进，节省时间 这时候 sessions spawn 相当于 把一个临时专项任务派给另一个 agent 去做 ，主 agent 继续自己的主线工作。 3. 主 agent 如何管理 spawn 出来的 agent？ 一旦通过 sessions spawn 启动了其他 agent，主 agent 可以通过以下工具进行管理： 工具 作用 sessions list 列出当前所有会话（包括自己 spawn 的 sub agent） sessions history 查看某个 sub agent 会话的完整历史记录 sessions send 向某个 sub agent 会话发送消息、追问或下达新指令 sessions spawn 再次启动新的 sub agent 关键点 ： • Sub agent 的会话是独立的 —— 主 agent 和 sub agent 各自有独立的 sessions 目录记录 • 主 agent 可以随时查看进度 —— 通过 sessions history 检查 sub agent 的工作进展 • 任务完成后结果会返回 —— sub agent 完成后，结果会汇总给主 agent • 并发执行是支持的 —— 可以同时 spawn 多个 sub agent 并行工作 例如，主 agent 可以这样操作： "帮我 spawn 一个 seo specialist 去分析关键词，同时 spawn 一个 copywriter 去写标题。等他们都完成后，汇总结果给我。" 这就是典型的 主从协作管理 模式。 例如： • 主 agent 继续和用户对话 • 同时 spawn 一个 agent 去分析仓库结构 • 再 spawn 一个 agent 去整理竞品资料 • 最后统一收口 这就是很典型的 sub agent 工作方式。 4. 一个实用原则：按“产出物”拆，不按“动作”拆 这是多智能体协作里最实用的一条经验。 不要这样拆： • 你看文件 A • 你看文件 B • 你看文件 C 更好的拆法是： • 你产出技术方案 • 你产出风险清单 • 你产出用户说明 • 你产出执行计划 也就是说： 让每个 sub agent 对一个结果负责，而不是只负责一个动作。 这样最后汇总起来，质量和清晰度都会高很多。 十三、最后总结一下 如果只用一句话概括这篇文章，最重要的不是“agency agents 是什么”，而是： 先分清 OpenClaw 原生概念，再理解外部 agent 模板是怎么被接入进去的。 更具体一点说： • workspace 是 agent 的工作区 • agentDir 是 agent 的状态目录 • sessions 是 agent 的会话记录 • subagents 是子任务运行登记 • sessions spawn 调用的是配置中的 agent，而不是磁盘上随便哪个目录 • agency agents 不是 OpenClaw 原生概念，而是当前环境里一批被接入成 workspace 的 agent 模板目录 一旦这个边界清楚了，很多原本绕口的目录结构就会突然变简单： OpenClaw 提供的是原生多智能体框架， agency agents 提供的是可接入这套框架的一批角色工作区。 理解了这一层，后面无论是安装 agent、扩展 agent，还是设计实际工作流，都会顺很多。 好了，赶紧挑几个合适的agents，然后用sessions spawn来让你的主Agent指挥它们干活儿吧！ 这个目录名不是内建保留字，也不是系统默认必须存在的层级。 它之所以在当前实例里“有效”，是因为： • 某些 agent 的 workspace • 被配置到了 /.openclaw/agency agents/<agent id 也就是说： OpenClaw 原生负责的是： • 认 workspace • 认 agentDir • 认 agentId • 认配置 agency agents 提供的是： • 一批预先写好的 agent workspace • 一种方便组织角色模板的目录结构 所以它更像： 被接入 OpenClaw 的 agent 模板/workspace 仓库 而不是 OpenClaw 系统本身的一层。简单讲： agency agents本质上是 workspace （工作区）！！！！！！ 九、 agency agents 和 OpenClaw 原生概念如何对应？ 如果当前机器把某个 agent 配成这样： • workspace = /.openclaw/agency agents/seo specialist • agentDir = /.openclaw/agents/seo specialist/agent 那么它们的关系就是： /.openclaw/agency agents/seo specialist 对应的是这个 agent 的 workspace /.openclaw/agents/seo specialist/agent 对应的是这个 agent 的 agentDir /.openclaw/agents/seo specialist/sessions 对应的是这个 agent 的 会话历史 十、那 agency agents 应该怎么安装？ 讲到这里，安装逻辑就容易明白了。 如果 agency agents 只是一个外部 workspace 模板来源，那么“安装它”就不应该被理解成： 把 repo clone 下来就完事 更准确的理解应该是： 把这些 workspace 接入 OpenClaw 的 agent 配置体系。 通常要经过几步： 第一步：准备 workspace 例如： • /.openclaw/agency agents/seo specialist 这里放角色工作区内容。 第二步：准备 agentDir 例如： • /.openclaw/agents/seo specialist/agent 这里放状态目录。 第三步：注册进 OpenClaw 也就是把这个 agent 写进 openclaw.json ，或者通过官方命令添加： 备注：当然，你并不真的需要挨个安装，只需要把agency agents的Github仓库喂给openclaw，让它理解之后安装即可； 这一步完成后，OpenClaw 才真正“认识”这个 agent。 所以，“安装 agency agents”这件事，本质上不是文件复制，而是： workspace 落地 + agentDir 准备 + agent 配置注册 十一、OpenClaw 是怎么调用这些来自 agency agents 的 agent 的？ 答案其实已经呼之欲出了： OpenClaw 调用的不是“agency agents 目录”，而是： 配置文件中定义的 agent 而这个 agent 的 workspace ，恰好指向了 agency agents 里的目录。 所以链路是： 1. sessions spawn(agentId=...) 2. OpenClaw 查配置 3. 找到该 agent 的 workspace 4. 找到该 agent 的 agentDir 5. 用这套上下文和状态启动子会话 这也是为什么： • agency agents 本身不是内置概念 • 但它依然可以很好地融入 OpenClaw 体系 因为 OpenClaw 看的是“配置结果”，不是“目录名字”。 十二、工作中到底该怎么用多 agent 协作？ 把概念讲清楚之后，再谈工作方法才不会漂。 1. 单 agent 适合什么情况？ 如果任务是： • 短 • 集中 • 不需要多角色分工 • 不需要并行探索 那单 agent 就够了。 例如： • 看一份日志 • 回答一个技术问题 • 改一段简单脚本 这类任务硬拆成多 agent，反而会增加协调成本。 2. 什么时候该用 sessions spawn 启动其他 agent？ 当一个任务天然带有“分工需求”时，通过 sessions spawn 启动其他 agent 才真正有价值。 典型场景 A：主从协作模式 • 主 agent 负责总控和用户对话 • 通过 sessions spawn 启动 seo specialist 分析关键词 • 通过 sessions spawn 启动 frontend developer 实现页面 • 主 agent 汇总结果，统一输出 这时候的意义不是“多开几个窗口”，而是 给不同任务块分配稳定角色 。 典型场景 B：临时专项任务 • 已经有主任务在进行 • 但其中一个子问题可以独立解决 • 希望隔离上下文，避免污染主会话 • 或者希望并行推进，节省时间 这时候 sessions spawn 相当于 把一个临时专项任务派给另一个 agent 去做 ，主 agent 继续自己的主线工作。 3. 主 agent 如何管理 spawn 出来的 agent？ 一旦通过 sessions spawn 启动了其他 agent，主 agent 可以通过以下工具进行管理： 工具 作用 sessions list 列出当前所有会话（包括自己 spawn 的 sub agent） sessions history 查看某个 sub agent 会话的完整历史记录 sessions send 向某个 sub agent 会话发送消息、追问或下达新指令 sessions spawn 再次启动新的 sub agent 工具 工具 作用 作用 sessions list sessions list 列出当前所有会话（包括自己 spawn 的 sub agent） 列出当前所有会话（包括自己 spawn 的 sub agent） sessions history sessions history 查看某个 sub agent 会话的完整历史记录 查看某个 sub agent 会话的完整历史记录 sessions send sessions send 向某个 sub agent 会话发送消息、追问或下达新指令 向某个 sub agent 会话发送消息、追问或下达新指令 sessions spawn sessions spawn 再次启动新的 sub agent 再次启动新的 sub agent 关键点 ： • Sub agent 的会话是独立的 —— 主 agent 和 sub agent 各自有独立的 sessions 目录记录 • 主 agent 可以随时查看进度 —— 通过 sessions history 检查 sub agent 的工作进展 • 任务完成后结果会返回 —— sub agent 完成后，结果会汇总给主 agent • 并发执行是支持的 —— 可以同时 spawn 多个 sub agent 并行工作 例如，主 agent 可以这样操作： "帮我 spawn 一个 seo specialist 去分析关键词，同时 spawn 一个 copywriter 去写标题。等他们都完成后，汇总结果给我。" 这就是典型的 主从协作管理 模式。 例如： • 主 agent 继续和用户对话 • 同时 spawn 一个 agent 去分析仓库结构 • 再 spawn 一个 agent 去整理竞品资料 • 最后统一收口 这就是很典型的 sub agent 工作方式。 4. 一个实用原则：按“产出物”拆，不按“动作”拆 这是多智能体协作里最实用的一条经验。 不要这样拆： • 你看文件 A • 你看文件 B • 你看文件 C 更好的拆法是： • 你产出技术方案 • 你产出风险清单 • 你产出用户说明 • 你产出执行计划 也就是说： 让每个 sub agent 对一个结果负责，而不是只负责一个动作。 这样最后汇总起来，质量和清晰度都会高很多。 十三、最后总结一下 如果只用一句话概括这篇文章，最重要的不是“agency agents 是什么”，而是： 先分清 OpenClaw 原生概念，再理解外部 agent 模板是怎么被接入进去的。 更具体一点说： • workspace 是 agent 的工作区 • agentDir 是 agent 的状态目录 • sessions 是 agent 的会话记录 • subagents 是子任务运行登记 • sessions spawn 调用的是配置中的 agent，而不是磁盘上随便哪个目录 • agency agents 不是 OpenClaw 原生概念，而是当前环境里一批被接入成 workspace 的 agent 模板目录 一旦这个边界清楚了，很多原本绕口的目录结构就会突然变简单： OpenClaw 提供的是原生多智能体框架， agency agents 提供的是可接入这套框架的一批角色工作区。 理解了这一层，后面无论是安装 agent、扩展 agent，还是设计实际工作流，都会顺很多。 好了，赶紧挑几个合适的agents，然后用sessions spawn来让你的主Agent指挥它们干活儿吧！ 🔗 原文链接： https://mp.weixin.qq.com/s/8yaZAOqX... https://mp.weixin.qq.com/s/8yaZAOqX... 原创 DracoVibeCoding DracoVibeCoding Draco正在VibeCoding2026年3月15日 15:50 海南 本文承接昨天的文章（ 我在企微里养了130个AI员工：OpenClaw+The Agency实战全记录 ）讲解OpenClaw内秉的多agents机制如何运作，以及如何安装并运行多agents 我在企微里养了130个AI员工：OpenClaw+The Agency实战全记录 很多人第一次看 OpenClaw 的目录结构，都会被几个词绕住： • workspace • agents • agentDir • sessions • subagents • sessions spawn 接着再看到一个额外的目录： • agency agents 问题就变得更复杂了。 反正我一开始是晕了一阵的 这篇文章就做一件事： 先把 OpenClaw 原生概念讲清楚，再解释 agency agents 100多个agents怎么接到这套体系里。 先直观感受一下 OpenClaw 的典型目录结构： 💡 一句话记忆 ： workspace 是办公桌（工作内容）， agentDir 是档案柜（运行状态）， sessions 是工作日志（历史记录）， subagents 是任务派工单。 一、workspace：Agent 的工作区 在 OpenClaw 里， workspace 可以理解成一个 agent 的“工作目录”或“办公桌”。 这里通常放的是 agent 运行时会读取的上下文文件，比如： • AGENTS.md • SOUL.md • USER.md • TOOLS.md • memory/ • 其他工作区级别的说明和资料 这些文件决定的不是“系统状态”，而是这个 agent 的： • 工作方式 • 身份设定 • 语气和边界 • 可以读取到的长期/短期上下文 所以， workspace 更接近： 这个 agent 用来思考和工作的环境 而不是一个纯粹的配置缓存目录。 默认情况下 OpenClaw 的默认工作区一般是： • /.openclaw/workspace 如果是多 agent，也常见这种命名方式： • /.openclaw/workspace <agentId 但这里要注意一点： 这只是常见默认路径，不是强制命名规则。 OpenClaw 真正认的，是配置文件里给每个 agent 指定的 workspace 路径。 二、agentDir：Agent 的状态目录 如果说 workspace 是办公桌，那 agentDir 更像档案柜。 它通常对应类似这样的路径： • /.openclaw/agents/<agentId /agent 这里放的是更偏运行态、系统态的内容，比如： • auth profiles.json • models.json • 认证相关信息 • 模型配置 • agent 自己的状态文件 这部分和 workspace 的区别非常重要： workspace 偏向： • 可编辑 • 面向工作内容 • 面向上下文和人格 agentDir 偏向： • 运行态 • 面向系统配置 • 面向认证、模型与状态 之所以分开，是因为 OpenClaw 在设计上明确区分了： “怎么工作” 和 “怎么运行” 三、sessions：每个 Agent 的会话记录 除了 workspace 和 agentDir ，每个 agent 还有自己的会话存储。 常见路径会是： • /.openclaw/agents/<agentId /sessions 这里面通常会看到： • sessions.json • .jsonl • 一些 lock / deleted / reset 文件 这一层记录的是： • 这个 agent 跑过哪些会话 • 每个会话的 transcript • 哪些会话被清理、重置、归档 所以它更像： 这个 agent 的工作日志系统 这也说明一个关键点： OpenClaw 不是“所有 agent 共用一份会话历史”，而是按 agent 分开管理。 四、subagents：子任务运行登记 再往下，就会碰到另一个容易和 agents 混淆的目录： • subagents 这个目录不是“另一批 agent 本体”，而更像： 子代理运行记录和调度索引 例如你会看到： • runs.json 它用来记录的，不是 agent 的人格设定，也不是 workspace，而是： • 谁 spawn 了子任务 • 子任务运行到了哪里 • runId、状态、完成情况等 所以： agents/<id /sessions 存的是某个 agent 自己的会话历史 subagents/runs.json 存的是子代理任务的运行登记 两者不是一回事。 五、 sessions spawn ：到底在调用什么？ 理解多智能体时，最容易问的一个问题是： sessions spawn 到底是在调用哪个目录里的 agent？ 这个问题如果只从目录结构看，很容易越看越乱。更准确的答案是： sessions spawn 调用的不是“某个目录”，而是“配置中定义好的 agent”。 也就是说，它的工作逻辑不是： • 去磁盘上扫一圈 • 看到哪个目录像 agent 就拿来用 它真正做的是： 1. 1. 根据 agentId 找到配置里的目标 agent 2. 2. 读取这个 agent 对应的 workspace 3. 3. 读取这个 agent 对应的 agentDir 4. 4. 在这个 agent 的上下文和状态下启动一个新的子会话 所以， sessions spawn 的本质不是“目录发现机制”，而是： 一个基于 agent 配置的会话生成机制 六、 agents list 是什么？它不是配置，是工具 要理解这一章，必须先搞清楚 OpenClaw 中” 工具（Tool） ”的概念。 什么是工具？ 在 OpenClaw 的语境下， 工具是 agent 可以调用的功能单元 。你可以把它理解为 agent 的”手脚”——agent 通过调用工具来与外部世界交互。 OpenClaw 提供的工具包括但不限于： 工具类型 示例 作用 文件工具 Read、 Write 、 Edit 读写文件内容 执行工具 Bash、 Exec 、 Process 执行命令和脚本 搜索工具 Grep、 Glob 在代码库中搜索 会话工具 sessions list、 sessions send 、 sessions spawn 多 agent 协作 agent 查询工具 agents list 查询可调用的 agent 列表 工具类型 工具类型 示例 示例 作用 作用 文件工具 文件工具 Read、 Write 、 Edit Read、 Write 、 Edit 读写文件内容 读写文件内容 执行工具 执行工具 Bash、 Exec 、 Process Bash、 Exec 、 Process 执行命令和脚本 执行命令和脚本 搜索工具 搜索工具 Grep、 Glob Grep、 Glob 在代码库中搜索 在代码库中搜索 会话工具 会话工具 sessions list、 sessions send 、 sessions spawn sessions list、 sessions send 、 sessions spawn 多 agent 协作 多 agent 协作 agent 查询工具 agent 查询工具 agents list agents list 查询可调用的 agent 列表 查询可调用的 agent 列表 工具 vs 配置：本质区别 这是最容易混淆的地方： 对比维度 工具（Tool） 配置（Config） 本质 功能/能力 参数/规则 存在形式 代码实现的函数 写在文件里的数据 如何被使用 agent 在运行时主动调用 系统启动时读取 类比 手机里的”相机”App 相机设置里的”分辨率”参数 对比维度 对比维度 工具（Tool） 工具（Tool） 配置（Config） 配置（Config） 本质 本质 功能/能力 功能/能力 参数/规则 参数/规则 存在形式 存在形式 代码实现的函数 代码实现的函数 写在文件里的数据 写在文件里的数据 如何被使用 如何被使用 agent 在运行时主动调用 agent 在运行时主动调用 系统启动时读取 系统启动时读取 类比 类比 手机里的”相机”App 手机里的”相机”App 相机设置里的”分辨率”参数 相机设置里的”分辨率”参数 举个例子： • agents list 是工具 → 就像相机 App，agent 可以”打开”它来查看有哪些 agent 可用 • subagents.allowAgents 是配置 → 就像相机设置里的白名单，规定了 agent 能看到谁 agents list 如何使用？ 当你在 OpenClaw 界面中和 agent 对话时说： “你能帮我列出你现在可以调用的其他 agent 吗？” 当前 agent 会主动调用 agents list 这个工具 ，返回可调用的 agent 列表。 类似地： • “帮我读取这个文件” → agent 调用 Read 工具 • “让 seo specialist 来帮我分析” → agent 调用 sessions spawn 工具 常见误区 很多人以为： 只要磁盘上存在一个 agent 目录， agents list 就应该把它列出来 但事实并非如此。 agents list 返回的不是”磁盘上有什么”，而是 当前上