OpenClaw 多团队组织架构设计

在复杂的 AI 自动化场景中，单一 Agent 往往难以胜任跨领域、多角色的协作需求。OpenClaw 提供了一套完整的多 Agent 编排体系，让我们可以像搭建真实组织一样，设计出具备清晰职责边界、灵活任务分工的多团队架构。本文将从架构原理出发，结合完整的配置示例，带你系统掌握 OpenClaw 的多团队组织设计方法。

---

一、核心概念：两层体系的分工

理解 OpenClaw 多团队架构的关键，在于区分两个层次的概念。

Multi-Agent 是系统架构层面的概念。你在配置文件中预先定义多个具名 Agent（如 team-a、team-b、team-c），每个 Agent 拥有独立的 workspace、独立的沙箱环境和独立的工具权限集。它们是并列存在、长期运行的实体，通过 bindings 规则决定哪个渠道的消息路由给哪个团队。

Sub-Agent 是运行时层面的概念。它由一个正在运行的 Agent 在处理任务过程中动态派生，会话 key 形如 agent:<agentId>:subagent:<uuid>，任务完成后通过 announce 机制将结果汇报回发起方，生命周期短暂（默认 60 分钟后自动归档）。

两者的映射关系非常清晰：每个团队对应一个 Multi-Agent 里的具名 Agent，每个团队内的角色对应该 Agent 动态派生的 Sub-Agent。团队之间天然隔离，团队内部通过 Orchestrator 模式实现多角色并行协作。

---

二、整体架构图

整个架构分为三层：最顶层是 Gateway 负责消息路由，中间层是各团队的 Multi-Agent 实体，最底层是团队内部通过 Nested Sub-Agents 实现的角色分工。

---

三、第一层：用 Multi-Agent 定义团队

3.1 基础配置结构

在 agents.list 中为每个团队声明一个具名 Agent，核心要素包括独立的 workspace、沙箱策略（sandbox）和工具权限（tools）。同时，在 agents.defaults.subagents 中开启嵌套深度支持，这是后续角色分工的基础。

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 2,
        "maxChildrenPerAgent": 5,
        "maxConcurrent": 12,
        "runTimeoutSeconds": 900
      }
    },
    "list": [
      {
        "id": "team-product",
        "name": "Team A - Product",
        "workspace": "~/.openclaw/workspace-team-product",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "write", "browser", "exec"],
          "deny": ["gateway"]
        }
      },
      {
        "id": "team-engineering",
        "name": "Team B - Engineering",
        "workspace": "~/.openclaw/workspace-team-engineering",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "write", "exec", "apply_patch"],
          "deny": ["browser", "gateway"]
        }
      },
      {
        "id": "team-research",
        "name": "Team C - Research",
        "workspace": "~/.openclaw/workspace-team-research",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "browser", "exec"],
          "deny": ["write", "apply_patch", "gateway"]
        }
      }
    ]
  }
}

3.2 团队隔离机制

每个团队 Agent 的安全隔离体现在三个维度：

• 文件系统隔离：各团队使用独立的 workspace 目录，互不干扰。
• 凭证隔离：每个 Agent 从自己专属的 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 读取凭证，不共享。如需跨团队共享凭证，需手动复制文件。
• 沙箱隔离：scope: "agent" 模式下，每个团队 Agent 拥有独立的 Docker 容器，运行环境完全隔离。

3.3 渠道路由绑定

通过 bindings 可以将不同的渠道（Discord 频道、WhatsApp 群组等）路由到对应的团队 Agent，实现自动分流：

{
  "bindings": [
    {
      "agentId": "team-product",
      "match": {
        "provider": "discord",
        "accountId": "*",
        "peer": { "kind": "channel", "id": "product-channel-id" }
      }
    },
    {
      "agentId": "team-engineering",
      "match": {
        "provider": "discord",
        "accountId": "*",
        "peer": { "kind": "channel", "id": "engineering-channel-id" }
      }
    }
  ]
}

---

四、第二层：用 Nested Sub-Agents 实现角色分工

4.1 Orchestrator 模式原理

将 maxSpawnDepth 设置为 2 后，即可启用 Orchestrator 模式。任务流转路径如下：

1. 团队 Agent（depth 0）收到任务，派生一个 Orchestrator Sub-Agent（depth 1）作为团队协调者。
2. Orchestrator 并行派生多个 Worker Sub-Agent（depth 2），每个 Worker 扮演一个具体角色。
3. 各角色 Worker 完成任务后，通过 announce 机制将结果汇报给 Orchestrator。
4. Orchestrator 综合所有角色的输出，向团队 Agent 汇报最终结果。
5. 团队 Agent 将结果回复给用户。

depth-1 的 Orchestrator 会自动获得 sessions_spawn、sessions_list、sessions_history 等管理工具，具备调度子角色的能力。depth-2 的 Worker 则是纯粹的执行者，永远无法再派生子任务。

4.2 角色差异化配置

不同角色的差异化通过 sessions_spawn 的参数实现：

// Orchestrator 内部的派生逻辑（伪代码示意）

sessions_spawn({
  task: "作为产品经理，分析用户需求并输出需求文档",
  label: "pm-role",
  model: "gpt-4o",
  thinking: "high",
  runTimeoutSeconds: 600
})

sessions_spawn({
  task: "作为 UI 设计师，基于需求文档提出交互设计方案",
  label: "designer-role",
  model: "claude-3-5-sonnet",
  runTimeoutSeconds: 600
})

sessions_spawn({
  task: "作为数据分析师，评估方案的可行性与风险",
  label: "analyst-role",
  model: "gpt-4o-mini",
  runTimeoutSeconds: 300
})

• label：标识角色身份，方便后续用 /subagents info 或 /subagents log 追踪。
• model：不同角色可以使用不同的模型，高复杂度角色用高质量模型，执行类角色用轻量模型以控制成本。
• task：任务描述本身就是角色 prompt，直接在此注入角色定义和具体指令。
• runTimeoutSeconds：为每个角色设置合理的超时，防止某个角色卡死影响整体流程。

4.3 Announce 结果汇聚

每个 Worker 完成后，announce payload 会包含以下信息，供 Orchestrator 综合判断：

• 执行结果（assistant 回复或最后一个 toolResult）
• 运行状态（completed successfully / failed / timed out / unknown）
• 运行时长、token 用量、估算成本
• sessionKey 和 transcript 路径（Orchestrator 可通过 sessions_history 获取完整对话记录）

值得注意的是，announce 的状态来自运行时信号，而非模型输出推断，因此是可靠的程序化判断依据。

---

五、关键参数与调优

5.1 并发与容量规划

参数	默认值	说明
maxSpawnDepth	1	最大嵌套深度，设为 2 启用 Orchestrator 模式
maxChildrenPerAgent	5	每个 Orchestrator 最多同时管理的子 Worker 数
maxConcurrent	8	全局 Sub-Agent 并发上限（所有团队共享）
runTimeoutSeconds	0（无超时）	默认任务超时时间
archiveAfterMinutes	60	Sub-Agent 完成后自动归档的等待时间

多团队并发时，maxConcurrent 是所有团队共享的全局资源池。例如 3 个团队各有 3 个角色同时运行，就需要至少 maxConcurrent: 9（还需加上各团队的 Orchestrator）。建议根据实际团队数量和角色数量合理估算，预留一定余量。

5.2 成本控制策略

每个 Sub-Agent 有独立的 context 和 token 用量，多角色并行会显著放大 token 消耗。推荐策略：

• 通过 agents.defaults.subagents.model 为所有 Sub-Agent 设置轻量默认模型。
• 仅在需要高质量输出的关键角色上，通过 sessions_spawn.model 单独覆盖为高性能模型。
• 对于重复性或模板化的角色任务，优先使用成本更低的模型。

5.3 工具权限的精细管控

Sub-Agent 的工具权限通过 tools.subagents.tools 统一管控，与 Multi-Agent 的 per-agent 工具配置是独立的两套体系：

{
  "tools": {
    "subagents": {
      "tools": {
        "deny": ["gateway", "cron"],
        "allow": ["read", "exec", "write", "browser"]
      }
    }
  }
}

注意 deny 优先级始终高于 allow，且工具限制是单向收紧的——上层拒绝的工具，下层无法恢复。

---

六、运维与调试

6.1 常用管理命令

部署运行后，可以通过以下命令实时监控和干预：

# 查看当前会话的所有 Sub-Agent 运行状态
/subagents list

# 查看某个角色的详细信息（状态、时间戳、transcript 路径）
/subagents info <id|#>

# 查看某个角色的运行日志（含工具调用记录）
/subagents log <id|#> 50 tools

# 向某个运行中的角色发送补充指令
/subagents steer <id|#> "请重点关注安全性方面的风险"

# 停止某个角色及其所有子任务（级联停止）
/subagents kill <id>

# 停止当前会话下所有 Sub-Agent
/subagents kill all

6.2 验证架构配置

# 检查 Agent 路由与绑定配置是否正确
openclaw agents list --bindings

# 验证沙箱容器是否按预期启动
docker ps --filter "name=openclaw-sbx-"

# 实时监控路由、沙箱、工具过滤日志
tail -f "/logs/gateway.log" | grep -E "routing|sandbox|tools"

6.3 常见问题排查

角色 Worker 无法启动：检查 maxSpawnDepth 是否已设为 2，以及 maxChildrenPerAgent 是否已达上限。

工具权限未生效：注意工具过滤链的优先级——全局 tools.deny > agent 级 > sandbox 级 > subagent 级，上层拒绝的工具无法在下层恢复。

Announce 结果丢失：Sub-Agent announce 是 best-effort 机制，gateway 重启会导致待处理的 announce 丢失。对于关键任务，建议结合 sessions_history 主动拉取子任务的完整记录作为兜底。

团队间跨 Agent 派生失败：默认情况下，Sub-Agent 只能在发起者所属的 Agent 下派生。如需跨团队调用，需在目标团队的配置中显式设置 agents.list[].subagents.allowAgents: ["source-agent-id"]。

---

七、局限性说明

在实际应用中，有几点硬性约束需要提前了解：

• 最大嵌套深度为 5，官方推荐 depth 2 适合绝大多数场景，更深的嵌套会显著增加调试复杂度。
• depth-2 的 Worker 永远无法再派生子任务，这是系统级硬约束，无法通过配置绕过。
• Sub-Agent context 注入有限，仅包含 AGENTS.md 和 TOOLS.md，不包含 SOUL.md、IDENTITY.md 等个性化文件，角色身份完全依赖 task 参数中的 prompt 注入。
• 团队间没有原生的直接通信机制，跨团队协作需要通过主流程的消息路由来协调，而非在 Sub-Agent 层面直接互调。

---

八、总结

OpenClaw 的多团队架构设计本质上是两个维度的叠加：用 Multi-Agent 在水平方向划分团队边界，用 Nested Sub-Agents 在垂直方向构建团队内部的角色层级。前者解决的是隔离与路由问题，后者解决的是并行与编排问题。

这套架构的优雅之处在于，它将"组织设计"的思维直接映射到了配置层面——你可以像定义公司架构图一样定义你的 AI 团队，每个团队有自己的职责边界、工具权限和运行环境，每个角色有自己的模型选型和任务定义，整个系统在结构上清晰可控，在运行时灵活高效。