当前位置：首页 » AI智能体

一文吃透底层机制：OpenClaw🦞如何跑起多智能体（Multi-Agents）

3小时前 AI智能体 25 0

本文延续前文（在企微里带130个AI员工：用OpenClaw把Agency Agent落地的组织学）

聚焦拆解 OpenClaw 原生的多智能体机制到底怎么运转，并给出“如何安装并跑起多 agents”的落地方法。

不少人第一次打开 OpenClaw 的目录结构，会被这些名词绕晕：

workspace
agents
agentDir
sessions
subagents
sessions_spawn

再看到额外的目录：

agency-agents

就更困惑了。别急，本文只做一件事：先把 OpenClaw 的原生概念讲清楚，再说 agency-agents 这 100+ 个 agents 如何接入这套体系。

先看一个典型目录结构

~/.openclaw/
├── openclaw.json         # 多智能体总控配置
├── workspace/            # 默认工作区（主 agent）
│   ├── AGENTS.md
│   ├── SOUL.md
│   ├── TOOLS.md
│   └── memory/
│
├── agents/               # 各 agent 的运行态目录
│   └── /
│       ├── agent/        # agentDir：状态、认证、模型配置
│       │   ├── auth-profiles.json
│       │   └── models.json
│       │
│       ├── sessions/     # 会话历史记录
│       │   ├── sessions.json
│       │   └── *.jsonl
│       │
│       └── subagents/    # 子任务运行登记
│           └── runs.json

一句话速记：

workspace = 办公桌（工作内容）
agentDir = 档案柜（运行状态）
sessions = 工作日志（历史记录）
subagents = 任务派工单（子任务登记）

一、workspace：Agent 的工作区

在 OpenClaw 中，workspace 可以理解为某个 agent 的“工作目录/办公桌”。这里放的是运行期可读的上下文与材料，例如：

AGENTS.md
SOUL.md
USER.md
TOOLS.md
memory/
其他工作区级资料

它不描述“系统状态”，而用于设定 agent 的：

工作方式
身份与边界
语气风格
可读取的长期/短期上下文

常见默认路径：

~/.openclaw/workspace（单 agent）
~/.openclaw/workspace-（多 agent 场景常见）

注意：这只是常见习惯路径，真正生效的是配置文件里为每个 agent 指定的 workspace。

二、agentDir：Agent 的状态目录

如果 workspace 是办公桌，agentDir 就像档案柜。典型路径：

~/.openclaw/agents//agent

这里保存更偏系统运行态的信息，例如：

auth-profiles.json
models.json
认证信息、模型配置、状态文件

对比关系：

workspace：可编辑、面向工作内容与上下文
agentDir：面向系统配置、认证、模型与状态

设计理念：清晰区分“怎么工作”（workspace）与“怎么运行”（agentDir）。

三、sessions：每个 Agent 的会话记录

每个 agent 有各自的会话存储，典型路径：

~/.openclaw/agents//sessions

常见内容：

sessions.json、*.jsonl
一些 lock / deleted / reset 标记文件

它记录：

该 agent 跑过哪些会话
每个会话的对话转录
清理、重置、归档情况

理解为该 agent 的“工作日志系统”。注意：OpenClaw 按 agent 隔离管理会话历史，而非所有 agent 共用一套历史。

四、subagents：子任务运行登记

容易与 agents 混淆的目录还有一个：

subagents

它并不是另一批 agent 本体，而是“子代理运行记录/调度索引”。例如：

runs.json：记录谁 spawn 了子任务、runId、状态与完成情况等

对比区分：

agents//sessions：某个 agent 自己的会话历史
subagents/runs.json：子代理任务的运行登记

五、sessions_spawn：到底在调用什么？

多智能体里最常见的疑问是：sessions_spawn 究竟调用哪个目录的 agent？

答案：它调用的不是“某个目录”，而是“配置中定义好的 agent”。执行逻辑为：

根据 agentId 查找配置中的目标 agent
读取该 agent 的 workspace
读取该 agent 的 agentDir
在该 agent 的上下文与状态下启动新的子会话

本质上，sessions_spawn 是“基于配置的会话生成机制”，而非“目录发现机制”。

六、agents_list 是什么？它不是配置，是工具

先澄清“工具（Tool）”在 OpenClaw 里的含义：工具是 agent 可调用的功能单元（“手脚”），用于与外部世界交互。常见类型：

文件工具：Read、Write、Edit（读写文件）
执行工具：Bash、Exec、Process（执行命令/脚本）
搜索工具：Grep、Glob（在代码库中搜索）
会话工具：sessions_list、sessions_send、sessions_spawn（多 agent 协作）
agent 查询工具：agents_list（查询可调用的 agent 列表）

工具 vs 配置（易混点）：

工具（Tool）：功能/能力，代码实现，运行时由 agent 主动调用
配置（Config）：参数/规则，文件数据，系统启动或调用时读取

类比：

agents_list 是“相机 App”—— agent 打开它查看可用 agent
subagents.allowAgents 是“相机设置”——白名单决定能看到谁

常见误解：磁盘上只要有 agent 目录，agents_list 就应该列出来。事实并非如此。agents_list 返回的是当前上下文下，被允许通过 sessions_spawn 调用的 agent 列表。

agents_list 实际检查的来源：

全局配置：~/.openclaw/openclaw.json（系统有哪些 agent、各自的 id、workspace、agentDir 等）
权限控制：openclaw.json 中的 subagents.allowAgents（每个 agent 的可调用白名单）
运行时上下文：调用者是谁（不同调用者看到的列表可能不同）

示例配置：

{
  "agents": [
    {
      "id": "manager",
      "workspace": "~/.openclaw/agency-agents/manager",
      "agentDir": "~/.openclaw/agents/manager/agent",
      "subagents": {
        "allowAgents": ["seo-specialist", "frontend-developer", "copywriter"]
      }
    },
    {
      "id": "seo-specialist",
      "workspace": "~/.openclaw/agency-agents/seo-specialist",
      "agentDir": "~/.openclaw/agents/seo-specialist/agent"
    },
    {
      "id": "frontend-developer",
      "workspace": "~/.openclaw/agency-agents/frontend-developer",
      "agentDir": "~/.openclaw/agents/frontend-developer/agent"
    },
    {
      "id": "copywriter",
      "workspace": "~/.openclaw/agency-agents/copywriter",
      "agentDir": "~/.openclaw/agents/copywriter/agent"
    },
    {
      "id": "data-analyst",
      "workspace": "~/.openclaw/agency-agents/data-analyst",
      "agentDir": "~/.openclaw/agents/data-analyst/agent"
    }
  ]
}

解读：

系统共配置了 5 个 agent
manager 的 subagents.allowAgents 仅包含 ["seo-specialist","frontend-developer","copywriter"]，不含 data-analyst

因此：当 manager 调用 agents_list 时，只能看到：

seo-specialist
frontend-developer
copywriter

即便 data-analyst 已存在于系统中，它对 manager 也不可见。

一句话总结：

agents_list：工具，用于查询可调用 agent 列表
subagents.allowAgents：配置，权限白名单，控“能看到谁”
openclaw.json：配置，全局注册表，定义系统所有 agent

核心逻辑：agents_list 工具读取 openclaw.json 全局配置，并受 subagents.allowAgents 权限过滤，最终返回当前 agent 可调用的其他 agent 列表。

七、openclaw.json：多智能体的总控台

将前述概念串起来的关键文件是：

~/.openclaw/openclaw.json

在多 agent 场景下，它定义每个 agent 的核心属性：

id、workspace、agentDir
model、tools、bindings
subagents.allowAgents

换言之：目录只是“承载内容”的位置，配置才是 OpenClaw 识别 agent 的入口。

示例：

{
  "id": "manager",
  "workspace": "~/.openclaw/agency-agents/manager",
  "agentDir": "~/.openclaw/agents/manager/agent",
  "subagents": {
    "allowAgents": ["seo-specialist", "frontend-developer"]
  }
}

{
  "id": "seo-specialist",
  "workspace": "~/.openclaw/agency-agents/seo-specialist",
  "agentDir": "~/.openclaw/agents/seo-specialist/agent"
}

八、现在再谈 agency-agents：它到底是什么？

时机已到：agency-agents 并非 OpenClaw 的内建固定目录，而是一种“外部 agent workspace 的组织方式”。

OpenClaw 原生只“认”：

workspace
agentDir
agentId
对应配置

而 agency-agents 提供的是：

一批预置的 agent workspace（角色模板）
一种便于管理角色模板的目录结构

因此它更像“被接入 OpenClaw 的 workspace 仓库”，本质就是各 agent 的工作区。

九、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 模板来源，“安装”它的正确理解不是“clone 即用”，而是“接入 OpenClaw 的 agent 配置体系”。通常三步：

准备 workspace（例如 ~/.openclaw/agency-agents/seo-specialist），放置角色工作区内容
准备 agentDir（例如 ~/.openclaw/agents/seo-specialist/agent），存放运行状态
注册到 OpenClaw（写入 openclaw.json 或用命令添加）

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 下的目录。

调用链路：

sessions_spawn(agentId = ...)
查配置
定位该 agent 的 workspace
定位该 agent 的 agentDir
在这套上下文 + 状态下启动子会话

这也是为什么 agency-agents 并非内置概念，却能自然融入 OpenClaw：系统看的是“配置结果”，而非“目录名”。

十二、实战：多 agent 协作怎么用更高效？

1. 何时用单 agent？

任务具备以下特点时，用单 agent 更省心：

任务短、集中
不需要多角色分工
不需要并行探索

例如：查看一份日志、回答一个技术小问题、修改一段脚本。硬拆成多 agent 反而增加协调成本。

2. 何时用 sessions_spawn 启动其他 agent？

当任务天然存在“角色分工”时，spawn 才真正带来价值。

典型场景 A：主从协作

主 agent 负责总控与对话
spawn seo-specialist 分析关键词
spawn frontend-developer 实现页面
主 agent 汇总成果后统一输出

典型场景 B：临时专项

主任务在进行中
某子问题可独立解决
需要隔离上下文或希望并行加速

3. 主 agent 如何管理已 spawn 的 sub-agent？

常用工具：

sessions_list：列出所有会话（含自己 spawn 的 sub-agent）
sessions_history：查看某个 sub-agent 会话的完整历史
sessions_send：向某个 sub-agent 会话发送消息/追加指令
sessions_spawn：继续启动新的 sub-agent

关键点：

sub-agent 会话独立存储（各自有独立 sessions 目录）
主 agent 可随时通过 sessions_history 跟进进度
任务完成后 sub-agent 结果会汇总回主 agent
支持并发：可同时 spawn 多个 sub-agent 并行推进

示例请求：

“帮我 spawn 一个 seo-specialist 做关键词分析，同时 spawn 一个 copywriter 起标题。等两边都完成后，把结果汇总给我。”

4. 最实用原则：按“产出物”拆，不按“动作”拆

不要按动作切分：

你看文件 A / 你看文件 B / 你看文件 C

而要按产出物切分：

你产出技术方案
你产出风险清单
你产出用户说明
你产出执行计划

让每个 sub-agent 对“结果”负责，汇总时质量与清晰度更高。

十三、收束与总览

如果只用一句话概括：别急着纠结 agency-agents，先厘清 OpenClaw 的原生概念，再看外部 agent 模板如何接入。

要点回顾：

workspace：agent 的工作区
agentDir：agent 的状态目录
sessions：agent 的会话记录
subagents：子任务运行登记
sessions_spawn：按配置调用 agent，而非扫描磁盘目录
agency-agents：并非 OpenClaw 原生概念，而是一批被接入为 workspace 的角色模板

理顺这层边界，目录就不再拧巴：OpenClaw 提供框架与机制，agency-agents 提供可以即插即用的角色工作区。理解了它们的关系，安装、扩展 agent 和设计实际工作流都会顺畅很多。

现在，挑几个合适的 agents，用 sessions_spawn 让你的主 Agent 指挥它们开工吧！🦞

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

未经允许不得转载：一文吃透底层机制：OpenClaw🦞如何跑起多智能体（Multi-Agents）

请登录后发表评论