引言

随着 AI 智能体（Agent）在企业场景中的广泛应用，单一智能体已难以满足复杂业务需求。如何在同一基础设施上运行多个独立的 AI 智能体，并让它们协同工作，成为现代 AI 架构设计的核心挑战。

OpenClaw 的多智能体路由（Multi-Agent Routing）系统正是为解决这一问题而生。本文将深入解析其架构设计、核心概念与最佳实践，帮助读者构建企业级的多智能体协作基础设施。

什么是"一个智能体"？

在 OpenClaw 的语境中，一个智能体（Agent） 是一个完全独立、自包含的"大脑"，拥有以下核心资源：

1. 独立工作空间（Workspace）

每个智能体拥有专属的目录结构：

1
2
3
4
5
6

~/.openclaw/workspace-<agentId>/
├── AGENTS.md      # 智能体行为规范
├── SOUL.md        # 人格与个性定义
├── USER.md        # 用户信息
├── TOOLS.md       # 工具使用说明
└── ...            # 其他工作文件

这些文件定义了智能体的"身份"——它如何思考、如何回应、拥有哪些工具能力。

2. 独立状态目录（AgentDir）

1
2
3
4

~/.openclaw/agents/<agentId>/agent/
├── auth-profiles.json    # 认证配置（各频道账号）
├── models.json           # 模型注册表
└── config/               # 智能体专属配置

关键原则：认证信息是按智能体隔离的。一个智能体的 Telegram 账号不会自动共享给另一个智能体。如需共享，必须显式复制 auth-profiles.json。

3. 独立会话存储（Session Store）

1
2
3
4

~/.openclaw/agents/<agentId>/sessions/
├── agent:<agentId>:<mainKey>      # 主会话
├── agent:<agentId>:<channel>:...  # 频道特定会话
└── ...

每个智能体的对话历史完全隔离。用户与 “Alex” 智能体的聊天记录，不会出现在 “Mia” 智能体的会话中。

多智能体架构：从单到多

单智能体模式（默认）

如果不进行任何配置，OpenClaw 以单智能体模式运行：

1
2
3
4
5

# 默认配置
agentId: main
workspace: ~/.openclaw/workspace
agentDir: ~/.openclaw/agents/main/agent
sessions: agent:main:<mainKey>

多智能体模式

通过配置 agents.list，可以在同一网关（Gateway）上运行多个智能体：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

{
  agents: {
    list: [
      { 
        id: "main", 
        workspace: "~/.openclaw/workspace-main",
        // agentDir 默认为 ~/.openclaw/agents/main/agent
      },
      { 
        id: "coding", 
        workspace: "~/.openclaw/workspace-coding",
        agentDir: "~/.openclaw/agents/coding/agent"
      },
      { 
        id: "social", 
        workspace: "~/.openclaw/workspace-social" 
      }
    ]
  }
}

关键要点：

  • 每个智能体必须拥有唯一的 agentId
  • 每个智能体应该有独立的 workspace
  • 永远不要复用 agentDir（会导致认证/会话冲突）

消息路由：如何决定哪个智能体处理消息？

多智能体系统的核心挑战是消息路由——当一条消息到达时，如何决定哪个智能体来处理它？

绑定（Bindings）机制

OpenClaw 使用 bindings 配置来定义路由规则：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
  bindings: [
    // 示例 1：将特定 WhatsApp 私聊路由到特定智能体
    {
      agentId: "alex",
      match: { 
        channel: "whatsapp", 
        peer: { kind: "direct", id: "+15551230001" } 
      }
    },
    // 示例 2：将特定 Discord 服务器路由到特定智能体
    {
      agentId: "coding",
      match: { 
        channel: "discord", 
        guildId: "123456789012345678" 
      }
    },
    // 示例 3：将特定 Telegram 账号路由到特定智能体
    {
      agentId: "social",
      match: { 
        channel: "telegram", 
        accountId: "social_bot" 
      }
    }
  ]
}

路由优先级规则

当有多个绑定匹配时，OpenClaw 按照从具体到一般的优先级进行选择：

  1. peer 匹配（精确的私聊/群组 ID）
  2. parentPeer 匹配（线程继承）
  3. guildId + roles（Discord 角色路由）
  4. guildId（Discord 服务器）
  5. teamId（Slack 团队）
  6. accountId（频道账号匹配）
  7. 频道级匹配（accountId: "*"）
  8. 回退到默认智能体（agents.list[].default，或第一个列表项，默认 main）

重要细节：如果同一层级有多个匹配，配置文件中先出现的绑定优先。

实际应用场景

场景一：团队协作中的多角色智能体

假设一个开发团队需要以下智能体：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  agents: {
    list: [
      { id: "oncall", workspace: "~/.openclaw/workspace-oncall" },      // 值班响应
      { id: "reviewer", workspace: "~/.openclaw/workspace-reviewer" },   // 代码审查
      { id: "docs", workspace: "~/.openclaw/workspace-docs" }           // 文档维护
    ]
  },
  bindings: [
    // 告警群组 -> Oncall 智能体
    {
      agentId: "oncall",
      match: { 
        channel: "slack", 
        peer: { kind: "channel", id: "C1234567890" }  // #alerts 频道
      }
    },
    // PR 评论 -> Reviewer 智能体
    {
      agentId: "reviewer",
      match: { 
        channel: "github", 
        peer: { kind: "thread", parentId: "repo/pr/*" }
      }
    },
    // 文档相关讨论 -> Docs 智能体
    {
      agentId: "docs",
      match: { 
        channel: "discord", 
        guildId: "987654321098765432",
        parentPeer: { kind: "category", id: "documentation" }
      }
    }
  ]
}

场景二：个人多身份管理

一个人管理多个社交媒体身份：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  agents: {
    list: [
      { id: "personal", workspace: "~/.openclaw/workspace-personal" },
      { id: "creator", workspace: "~/.openclaw/workspace-creator" },     // 内容创作者身份
      { id: "consultant", workspace: "~/.openclaw/workspace-consultant" }  // 顾问身份
    ]
  },
  bindings: [
    // 私人 WhatsApp -> Personal
    {
      agentId: "personal",
      match: { 
        channel: "whatsapp", 
        accountId: "personal",
        peer: { kind: "direct", id: "+1555*" }  // 匹配所有私聊
      }
    },
    // Twitter DM -> Creator
    {
      agentId: "creator",
      match: { 
        channel: "x",  // X (Twitter)
        accountId: "creator_handle"
      }
    },
    // LinkedIn 消息 -> Consultant
    {
      agentId: "consultant",
      match: { 
        channel: "linkedin",
        peer: { kind: "direct", id: "*@company.com" }  // 企业邮箱域名
      }
    }
  ]
}

最佳实践与注意事项

✅ 应该做的

  1. 明确划分智能体职责

    • 每个智能体应该有清晰的职责边界
    • 通过 SOUL.md 和 AGENTS.md 明确智能体的"人格"和"行为准则"

  2. 使用具体的绑定规则

    • 优先使用 peer 精确匹配而非通配符
    • 利用 guildId、teamId 等层级结构组织路由

  3. 保持工作空间隔离

    • 绝不共享 agentDir 或会话存储
    • 每个智能体有自己的工具配置和认证信息

  4. 配置回退策略

    • 显式设置 default 智能体
    • 确保总有智能体能处理未匹配的消息

❌ 不应该做的

  1. 避免智能体职责重叠

    • 不要让多个智能体处理同一类消息
    • 这会导致响应冲突和用户体验混乱

  2. 不要使用过于宽泛的匹配规则

    • accountId: "*" 应该作为最后的兜底方案
    • 过于宽泛的规则会捕获意料之外的消息

  3. 不要手动修改会话存储

    • 直接操作 ~/.openclaw/agents/<agentId>/sessions 可能导致数据损坏
    • 使用官方 CLI 工具进行管理

  4. 不要在生产环境频繁切换路由规则

    • 路由变化可能导致会话中断
    • 提前规划好路由策略再部署

故障排查

智能体没有收到消息

  1. 检查绑定规则

    1

    openclaw agents list --bindings

    确认绑定规则的 match 条件是否匹配实际消息来源

  2. 验证频道账号状态

    1

    openclaw channels status --probe

    确保频道账号在线且能够接收消息

  3. 检查 allowlist/denylist 确认消息发送者不在被阻止列表中，或在允许列表中

消息被路由到错误的智能体

  1. 查看路由日志

    1

    openclaw logs --follow | grep "routing"

    观察实际的路由决策过程

  2. 调整绑定优先级 在配置文件中，将更具体的绑定规则放在前面

  3. 使用负向匹配 某些场景下，使用排除规则比包含规则更清晰

智能体间会话泄漏

  1. 确认工作空间隔离 检查不同智能体的 workspace 和 agentDir 路径是否确实不同

  2. 验证会话键 查看 ~/.openclaw/agents/<agentId>/sessions/ 目录结构 确认会话键格式为 agent:<agentId>:<key>

  3. 重启 Gateway

    1

    openclaw gateway restart

    某些配置更改需要重启才能生效

总结与展望

OpenClaw 的多智能体路由系统为构建复杂的 AI 应用提供了坚实的基础。通过清晰的职责划分、灵活的路由规则和严格的隔离机制，开发者可以：

  • 在同一基础设施上运行多个独立的 AI 智能体
  • 根据不同的场景和需求动态路由消息
  • 确保数据隔离和安全性
  • 灵活扩展和管理复杂的 AI 应用

随着 AI 技术的不断发展，多智能体协作将成为企业级 AI 应用的标配。OpenClaw 的这一架构设计，为未来的 AI 生态系统奠定了坚实的技术基础。

本文基于 OpenClaw 官方文档创作，旨在帮助开发者理解和应用多智能体路由技术。如需了解更多细节，请参考 OpenClaw 官方文档。