OpenClaw 怎样隔离多 Agent 任务与权限

核验范围： 本文以 2026 年 7 月查阅的 OpenClaw 官方文档为准，重点核对 agent 注册、子代理权限与并发边界。配置字段和默认值会随版本变化，部署时请以当前文档和实际配置为准。

多 Agent 不是“多开几个聊天窗口”。在 OpenClaw 里，多个 agent 是否隔离、谁能派发谁、子任务能不能继续派生，最终都由配置和运行时边界决定。本文从一条 sessions_spawn 调用出发，说明 agent 的注册、权限白名单、异步协作与递归上限分别在哪里生效。

初学者阅读地图

第一次看 OpenClaw 的目录，很容易被一堆词绕晕：workspace、agents、agentDir、sessions、subagents、sessions_spawn。先记住一句话，后面就不乱：

目录只是放东西的地方，openclaw.json 才是系统真正认的入口。 OpenClaw 认的是配置，不是「哪个文件夹名字听起来像 agent」。

阅读顺序：第一节把四个目录的分工理清；第二、三节是这篇的核心——agent 是配置而非目录、以及权限怎么隔离；第四、五节讲子代理怎么异步协作又不层层外包；最后看多 agent 的实战原则。

一、先分清四个目录

一个多 agent 的 OpenClaw，目录大致长这样：

1
2
3
4
5
6
7
8
9
10
11
~/.openclaw/
├── openclaw.json          # 多 agent 总控配置（系统唯一认的入口）
├── workspace/             # 主 agent 的默认工作区
│   ├── AGENTS.md  SOUL.md  TOOLS.md  memory/
└── agents/
    └── <agentId>/
        ├── agent/         # agentDir：运行态（认证、模型配置）
        │   ├── auth-profiles.json
        │   └── models.json
        ├── sessions/      # 该 agent 的会话历史（*.jsonl）
        └── subagents/     # 子任务运行登记（runs.json）

四个概念一句话各自记住：

概念 打个比方 装的是什么
workspace 办公桌 agent 的工作内容——SOUL.md、AGENTS.md、memory/ 这些决定它「怎么工作、是谁」的文件
agentDir 档案柜 agent 的运行态——认证信息、模型配置这些「怎么运行」的系统状态
sessions 工作日志 这个 agent 跑过的会话 transcript
subagents 派工单 子任务的运行登记（runs.json：谁 spawn 的、跑到哪、什么状态）

OpenClaw 把「怎么工作」和「怎么运行」分开：人格、记忆和工作说明放在可编辑的 workspace，认证和模型配置放在系统态的 agentDir。改 SOUL.md 不应影响认证；切换模型配置也不应改动工作区内容。这是理解隔离边界的第一步。

还要分清两个长得像的目录：agents/<id>/sessions 存的是某个 agent 自己的会话历史，agents/<id>/subagents/runs.json 存的是它派出去的子任务登记——一个是自己的日志，一个是给别人的工单，不是一回事。

二、Agent 不是目录，是配置

理解多 agent 最关键的一跳是：sessions_spawn 调用的不是「某个目录」，而是「配置里定义好的 agent」。

很多人以为 spawn 的逻辑是「去磁盘上扫一圈，看哪个文件夹像 agent 就拿来用」。不是。它真正做的是：

  1. 按 agentId 在 openclaw.json 里找到目标 agent 的配置
  2. 读取这个 agent 配置指定的 workspace
  3. 读取它指定的 agentDir
  4. 在这套上下文和状态下，启动一个新的子会话

所以 openclaw.json 才是多 agent 的总控台。它给每个 agent 定义 id、workspace、agentDir、model、tools、subagents.allowAgents 等属性。一个 agent 长这样：

1
2
3
4
5
6
7
8
{
  "id": "manager",
  "workspace": "~/.openclaw/agency-agents/manager",
  "agentDir": "~/.openclaw/agents/manager/agent",
  "subagents": {
    "allowAgents": ["seo-specialist", "frontend-developer", "copywriter"]
  }
}

注意那个 workspace 指向的路径名字（agency-agents/...）无所谓，OpenClaw 认的是「配置里写了这个路径」，不是路径长得像不像工作区。这一点在第七节还会回来。

三、权限隔离：一个 agent 凭什么只能指挥另一些 agent

这是我认为整套多 agent 设计里最值得说的一层，也是它接回本系列主线的地方。

先看一个工具和一个配置的区别，因为它俩最容易混：

  • agents_list 是工具——agent 运行时主动调用它，问「我现在能指挥哪些 agent？」
  • subagents.allowAgents 是配置——写在 openclaw.json 每个 agent 名下的权限白名单，规定它能 spawn 哪些 agent

关键在于 agents_list 返回的不是「磁盘上有哪些 agent」，而是「当前这个 agent 被允许 spawn 哪些」。举个例子，系统里配了 5 个 agent（manager、seo-specialist、frontend-developer、copywriter、data-analyst），但 manager 的 allowAgents 只写了前三个：

manager 调用 agents_list，返回的只有白名单里那三个。data-analyst 确实在系统里，但 manager 根本看不到它，也就无从 spawn。

这正是本系列反复撞见的那条主线——约束做进结构，而不是靠自觉。一个 agent 能指挥谁，不是靠在提示词里叮嘱「你不许调用 data-analyst」（那种软约束能被绕过），而是白名单直接把它从 agents_list 的返回里抹掉。看不见，就调不到。这比第三篇讲的 capability 分级更进一步：那是「能不能做某件事」，这是「能不能看见某个同伴」。

还有个安全默认值官方文档写得很明确、也很克制：allowAgents 默认是「仅自己」（same agent only），["*"] 才代表放开成任意目标。也就是说，多 agent 协作不是开箱就有的，你得显式授权谁能调谁——默认是关的。

四、Spawn 的本质：异步、隔离、可并行

sessions_spawn 启动子 agent 时，有三个官方文档里的特性值得记住，它们决定了多 agent 好不好用：

它是非阻塞的（non-blocking）。 spawn 出去后立即返回一个 runId 和 childSessionKey，父 agent 不会干等——它继续自己的对话，子 agent 在后台异步跑，跑完了再把结果 announce 回来。这解决了一个很实际的问题：主 agent 派活之后不会被卡住。

子会话是隔离的。 子 agent 有自己独立的 sessions 记录。它读了多少论文、点了多少网页、中间踩了多少坑，这些繁琐过程不会进到父 agent 的上下文里，父只看到最终结果。这其实是第四篇「省 token」那条思路的组织级应用——通过拆分任务来隔离上下文，就像你向导师汇报只给结论、不复述整个实验过程。默认是 context: "isolated"（干净的子会话）；如果子 agent 确实需要父的对话记录，才用 context: "fork"。

可以并行。 多个子 agent 能同时跑：一个查资料、一个写文案、一个核对之前发布的内容，几分钟做完串行要几小时的事。

五、怎么防止「层层外包」

一个自然的担心是：子 agent 也能 spawn，如果每一层都把活外包给下一层，最后就没人真正干活了。

李宏毅在一堂公开课里提到的说法是「子代理一律禁用 spawn」。方向对，但官方的实现更精细，值得纠正一下：OpenClaw 是按深度（maxSpawnDepth，默认 2）分配工具的——

  • depth-1 的 orchestrator 子 agent 会额外拿到 sessions_spawn、sessions_list、sessions_history 等工具，所以它能管自己的下一层孩子；
  • 但叶子层（leaf runs）拿不到这些递归编排工具，到了叶子就只能干活、不能再外包。

换句话说，不是「子代理一刀切禁用 spawn」，而是「递归到设定深度就自动收走编排能力」。配合几个全局上限一起兜底：maxConcurrent（并发数）、maxChildrenPerAgent（每个 agent 最多几个孩子）、runTimeoutSeconds（子任务超时，默认 900 秒）。这些都是写死的程序规则，不管模型怎么请求都突破不了——又一次「约束做进结构」。

六、主从协作：管理工具与一条实用原则

主 agent spawn 出子 agent 后，靠一组 sessions_* 工具管理它们：sessions_list（列出所有会话，含自己派出去的）、sessions_history（查某个子 agent 的完整进展）、sessions_send（给某个子会话追加指令）。值得注意的是，官方把这组「跨会话消息」工具和「spawn」工具分开授权——能查、能发消息，不等于能派生新 agent。

比概念更实用的是原文那条协作原则，我很认同：按「产出物」拆，不按「动作」拆。

  • 别这样拆：你看文件 A、你看文件 B、你看文件 C（这是按动作拆）
  • 该这样拆：你产出技术方案、你产出风险清单、你产出执行计划（这是按产出物拆）

让每个子 agent 对一个结果负责，而不是对一个动作负责。原因不难理解：按动作拆，最后还得有人把碎片拼起来，协调成本全压在主 agent 身上；按产出物拆，每个子 agent 交回来的是一块能直接用的完整结果，汇总时质量和清晰度都高得多。任务如果本身短、集中、不需要分工，那就别拆——单 agent 更省心，硬拆只是徒增协调开销。

七、agency-agents：原生机制 vs 第三方模板

最后厘清一个容易误会的名字。你可能会在别人的 OpenClaw 实例里看到一个 agency-agents 目录（比如「The Agency」那套号称 130 个 AI 员工的模板），然后以为它是 OpenClaw 的内建结构。

它不是。 agency-agents 不是 OpenClaw 的原生保留目录，而是一批预先写好的 agent workspace 模板——本质上就是一堆 workspace，被某人放在了这个路径下。OpenClaw 原生认的只有四样东西：workspace、agentDir、agentId、配置。agency-agents 之所以能用，是因为有人在 openclaw.json 里把某些 agent 的 workspace 指到了 ~/.openclaw/agency-agents/<id>。

所以「安装 agency-agents」这件事，本质不是把仓库 clone 下来就完事，而是把这些 workspace 接入配置体系：准备 workspace、准备 agentDir、再用 openclaw agents add 把 agent 注册进 openclaw.json。OpenClaw 看的永远是「配置结果」，不是「目录名字」。这也回到了第二节那句话——agent 是配置，不是目录。

我的理解与核验

我在整理这一篇时，重点把“目录结构”和“权限边界”分开核对。前者只是文件如何存放，后者才决定 agent 是否能被发现、被派发和继续派生。对实际部署而言，最值得检查的是 agents 配置、subagents.allowAgents、并发限制与超时设置，而不是先去复制一套看起来很完整的工作区模板。

本文的结论来自文档与配置语义的核对，不等同于对某个生产实例的压测结果；并发数、模型能力和具体任务拆分仍需要在自己的环境中验证。

小结

OpenClaw 的多 Agent 系统，拆开看是这么几层：

  • 配置是入口，不是目录。 openclaw.json 定义每个 agent 的 workspace、agentDir 和权限，sessions_spawn 调的是配置里的 agent。
  • 权限靠白名单隔离，不靠自觉。 allowAgents 默认「仅自己」，一个 agent 看不见白名单外的同伴，也就调不到——约束做进了结构。
  • 子代理异步、隔离、可并行，繁琐过程不污染父的上下文，是「上下文工程」的组织级手段。
  • 防层层外包靠按深度收工具，不是一刀切禁用；再配上并发、数量、超时的硬上限兜底。

把它接回系列主线：从第一篇的 lane 队列、第三篇的 capability 分级，到这一篇的 allowAgents 白名单和 maxSpawnDepth，OpenClaw 反复在做同一件事——把「谁能做什么、谁能看见谁、能递归到多深」这些约束，写进配置和程序规则里，而不是写进一句「请不要这样做」的提示词。 多 agent 之所以能放心地并行放养，靠的正是这套结构性的框。

多 agent 会用到各自的技能。下一篇《多 agent 模式下 Skills 的分层调用机制》接着讲：skill 从哪几层目录被发现、多个 agent 之间到底共享哪些技能——并破除「skill 共享靠实测」这个流传很广的误会。

参考资料