OpenClaw Agent与Sub-agent架构深度分析：关系、通信与权限隔离

OpenClaw Agent与Sub-agent架构深度分析：关系、通信与权限隔离

概述

OpenClaw是一个多智能体平台，支持复杂的Agent-Subagent架构设计。本文深入分析OpenClaw中Agent与Sub-agent的关系、通信机制、权限隔离以及实际应用场景。

1. Agent与Sub-agent的基本概念

1.1 Agent（智能体）

一个Agent在OpenClaw中是一个完全独立作用域的大脑，拥有：

• 独立的工作区（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）
• 独立的状态目录 （agentDir）用于认证配置文件、模型注册表
• 独立的会话存储 （聊天历史 + 路由状态）位于 ~/.openclaw/agents/<agentId>/sessions 下

1.2 Sub-agent（子智能体）

Sub-agent是从现有Agent运行中生成的后台智能体运行，具有以下特点：

• 在自己的会话中运行（agent:<agentId>:subagent:<uuid>）
• 完成后将结果通告回请求者的聊天渠道
• 主要用于并行化"研究/长任务/慢工具"工作，不阻塞主运行

2. 通信机制

2.1 Agent之间的通信

2.1.1 会话工具通信

OpenClaw提供专门的会话工具用于Agent间通信：

# 列出所有会话
sessions_list(kinds=["agent", "subagent"])

# 查看特定会话历史
sessions_history(sessionKey="agent:work:subagent:12345")

# 向其他Agent发送消息
sessions_send(sessionKey="agent:work:main", message="需要你的帮助")

# 启动子Agent
sessions_spawn(task="分析数据", agentId="data-analyzer")

2.1.2 通信配置

Agent-to-Agent通信需要显式启用配置：

{
  "tools": {
    "agentToAgent": {
      "enabled": true,  // 必须显式启用
      "allow": ["home", "work"],  // 允许通信的Agent列表
      "maxPingPongTurns": 3  // 最大乒乓轮次（0-5）
    }
  }
}

2.2 Sub-agent的通信模式

2.2.1 通告机制

Sub-agent通过通告步骤报告结果：

1. Sub-agent运行完成后，在子智能体会话中运行通告步骤
2. 如果子智能体回复 ANNOUNCE_SKIP，则不发布任何内容
3. 否则，通告回复通过后续的 agent 调用发布到请求者的聊天渠道
4. 通告消息被规范化为稳定模板，包含状态、结果、统计信息

2.2.2 工具限制

默认情况下，Sub-agent获得除会话工具外的所有工具，但可以通过配置限制：

{
  "tools": {
    "subagents": {
      "tools": {
        "deny": ["gateway", "cron"],  // 拒绝特定工具
        // 如果设置了allow，则变为仅允许模式
        // "allow": ["read", "exec", "process"]
      }
    }
  }
}

3. 权限与隔离机制

3.1 工作区隔离

每个Agent拥有独立的工作区，防止文件系统冲突：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace"
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work"
      }
    ]
  }
}

3.2 认证隔离

认证配置文件是每Agent独立的：

• 每个Agent从自己的位置读取：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• 主Agent凭证不会自动共享
• 切勿在Agent之间重用 agentDir（这会导致认证/会话冲突）

3.3 沙箱隔离

OpenClaw支持多层次的沙箱隔离：

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "sandbox": {
          "mode": "off"  // 个人Agent无沙箱
        }
      },
      {
        "id": "family",
        "sandbox": {
          "mode": "all",     // 始终沙箱隔离
          "scope": "agent",  // 每Agent一个容器
          "docker": {
            "setupCommand": "apt-get update && apt-get install -y git curl"
          }
        },
        "tools": {
          "allow": ["read"],  // 仅read工具
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

4. 路由与绑定机制

4.1 消息路由

入站消息通过绑定路由到Agent，规则是确定性 的，最具体的优先：

1. peer 匹配（精确私信/群组/频道id）
2. guildId（Discord）
3. teamId（Slack）
4. 渠道的 accountId 匹配
5. 渠道级匹配（accountId: "*"）
6. 回退到默认Agent

4.2 绑定配置示例

{
  "bindings": [
    {
      "agentId": "home",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    },
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "biz"
      }
    },
    // 特定群组路由到work Agent
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal",
        "peer": {
          "kind": "group",
          "id": "1203630...@g.us"
        }
      }
    }
  ]
}

5. 实际应用场景

5.1 并行任务处理

# 主Agent启动多个Sub-agent并行处理
subagent1 = sessions_spawn(
    task="分析用户数据",
    agentId="data-analyzer",
    model="anthropic/claude-sonnet-4-5"  # 使用便宜模型
)

subagent2 = sessions_spawn(
    task="生成报告",
    agentId="report-generator",
    model="anthropic/claude-sonnet-4-5"
)

# 主Agent继续处理其他任务，不阻塞

5.2 分层权限管理

{
  "agents": {
    "list": [
      {
        "id": "admin",
        "sandbox": { "mode": "off" },
        "tools": { "allow": ["*"] }  // 完全访问
      },
      {
        "id": "guest",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "web_search"],
          "deny": ["exec", "write", "edit"]
        }
      }
    ]
  }
}

5.3 多渠道路由

{
  "agents": {
    "list": [
      {
        "id": "chat",
        "model": "anthropic/claude-sonnet-4-5"  // 快速日常聊天
      },
      {
        "id": "deep",
        "model": "anthropic/claude-opus-4-5"  // 深度工作
      }
    ]
  },
  "bindings": [
    { "agentId": "chat", "match": { "channel": "whatsapp" } },
    { "agentId": "deep", "match": { "channel": "telegram" } },
    // 特定私信路由到深度Agent
    {
      "agentId": "deep",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "dm", "id": "+15551234567" }
      }
    }
  ]
}

6. 安全考虑

6.1 工具权限控制

OpenClaw提供细粒度的工具控制：

• 全局工具策略
• 每Agent工具策略
• 按模型提供商的工具策略

6.2 认证安全

• 认证凭证按Agent隔离
• 支持凭证复制但不推荐
• 沙箱隔离防止凭证泄露

6.3 资源限制

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxConcurrent": 8,  // 最大并发Sub-agent数
        "archiveAfterMinutes": 60  // 自动归档时间
      }
    }
  }
}

7. 最佳实践

7.1 Agent设计原则

1. 单一职责：每个Agent应有明确的职责范围
2. 最小权限：按需授予工具权限
3. 资源隔离：使用独立的工作区和认证
4. 错误边界：Sub-agent失败不应影响主Agent

7.2 通信设计

1. 异步优先：使用Sub-agent进行耗时任务
2. 结果聚合：Sub-agent完成后聚合结果
3. 超时控制：设置合理的运行超时
4. 资源监控：监控并发数和资源使用

7.3 安全配置

1. 默认拒绝：默认关闭Agent-to-Agent通信
2. 显式允许：仅允许必要的通信路径
3. 沙箱隔离：对不受信任的Agent使用沙箱
4. 定期审计：定期检查工具使用情况

8. 总结

OpenClaw的Agent-Subagent架构提供了强大的多智能体支持：

1. 灵活的通信机制：支持同步/异步、直接/间接通信
2. 严格的权限隔离：工作区、认证、工具的多层隔离
3. 智能的路由系统：基于渠道、账户、对等方的精确路由
4. 丰富的应用场景：从并行处理到分层权限管理

这种架构使得OpenClaw能够支持从简单的个人助手到复杂的企业级多智能体系统，同时保持安全性和可扩展性。

---

关键要点：

• Agent是完全隔离的"大脑"，拥有独立的工作区和认证
• Sub-agent用于并行任务处理，通过通告机制报告结果
• 通信需要显式配置，默认是隔离的
• 权限控制支持全局、每Agent、按模型提供商的多层次配置
• 路由系统支持精确的消息分发
• 沙箱隔离提供了额外的安全层

通过合理设计Agent-Subagent架构，可以构建出既强大又安全的AI助手系统。