本页介绍 OpenClaw 的多 Agent 路由系统：在一个 Gateway 进程中运行多个完全隔离的 Agent（独立 workspace、Auth Profile、会话存储）。包含 Binding 路由规则（peer > guild > account > channel）、多 WhatsApp 号、Discord/Telegram 多 bot、以及沙箱与工具权限的 per-Agent 配置。

多 Agent 路由（Multi-Agent Routing）

目标：在一个 Gateway 进程中运行多个隔离 Agent（独立 workspace + agentDir + 会话），以及多个渠道账号（如两个 WhatsApp 号），通过 Binding 路由入站消息到对应 Agent。

什么是"一个 Agent"？

Agent 是一个完整隔离的"大脑"，拥有独立的：

• Workspace（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格规则）
• 状态目录（agentDir）：Auth Profile、模型注册表、per-agent 配置
• 会话存储：聊天历史 + 路由状态（~/.openclaw/agents/<agentId>/sessions）

Auth Profile 是 per-agent 的，每个 agent 从自己的文件读取：

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

不要跨 agent 复用 agentDir，会导致 Auth/会话冲突。需要共享凭据时，将 auth-profiles.json 复制到另一个 agent 的 agentDir。

路径速查

路径	用途
~/.openclaw/openclaw.json	主配置文件
~/.openclaw	状态目录（OPENCLAW_STATE_DIR 可覆盖）
~/.openclaw/workspace	默认 workspace
~/.openclaw/agents/<id>/agent	Agent 状态目录
~/.openclaw/agents/<id>/sessions	会话存储

快速开始

# 1. 创建 Agent（wizard 引导）
openclaw agents add coding
openclaw agents add social

# 2. 配置渠道账号（每个 Agent 一个账号）
openclaw channels login --channel whatsapp --account work

# 3. 重启并验证
openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

路由规则（如何选择 Agent）

Binding 是确定性的，最具体者优先：

1. peer 匹配（精确 DM/群组/频道 ID）
2. parentPeer 匹配（线程继承）
3. guildId + roles（Discord 角色路由）
4. guildId（Discord）
5. teamId（Slack）
6. accountId + channel 匹配
7. channel 级匹配（accountId: "*"）
8. 回退到默认 agent（agents.list[].default，否则第一条，默认 main）

同层级有多个匹配时，配置中排在前面的优先。

平台配置示例

Discord 多 bot

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "coding", workspace: "~/.openclaw/workspace-coding" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
  ],
  channels: {
    discord: {
      accounts: {
        default: { token: "DISCORD_BOT_TOKEN_MAIN" },
        coding: { token: "DISCORD_BOT_TOKEN_CODING" },
      },
    },
  },
}

Telegram 多 bot

{
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
  ],
  channels: {
    telegram: {
      accounts: {
        default: { botToken: "123456:ABC...", dmPolicy: "pairing" },
        alerts: { botToken: "987654:XYZ...", dmPolicy: "allowlist", allowFrom: ["tg:123456789"] },
      },
    },
  },
}

WhatsApp 多号码

# 先连接两个号码
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
  channels: {
    whatsapp: { accounts: { personal: {}, biz: {} } },
  },
}

一个号码，不同联系人路由到不同 Agent

{
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
}

WhatsApp 日常 + Telegram 深度工作

{
  agents: {
    list: [
      { id: "chat", model: "anthropic/claude-sonnet-4-6", workspace: "~/.openclaw/workspace-chat" },
      { id: "opus", model: "anthropic/claude-opus-4-6", workspace: "~/.openclaw/workspace-opus" },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

Per-Agent 沙箱与工具配置

{
  agents: {
    list: [
      {
        id: "personal",
        sandbox: { mode: "off" },
        // 无工具限制
      },
      {
        id: "family",
        sandbox: { mode: "all", scope: "agent" },
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit", "apply_patch"],
        },
      },
    ],
  },
}

跨 Agent 的 QMD 记忆搜索

若需让一个 agent 搜索另一个 agent 的 QMD 会话记录，在该 agent 配置下添加 extraCollections：

{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // 相对 workspace 解析 → 集合名 "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

workspace 外的路径需要显式指定集合名；workspace 内的路径保持 agent 作用域，每个 agent 拥有独立的会话搜索集合。

相关

• 渠道路由
• 子 Agent
• ACP Agents
• 会话隔离
• Presence（在线状态）

常见问题

Q: 每个 Agent 能用不同的模型吗？

A: 可以。在 agents.list[].model 指定每个 agent 的主模型，也可以单独配置 fallbacks。

Q: 多个 Agent 能共享同一个 WhatsApp 账号吗？

A: 可以，但 DM 会话会都路由到一个 agent（per-agent "main session key"）。若需要真正隔离，每个用户绑定一个独立 agent。

Q: Agent 间能互相发消息吗？

A: 需要显式启用：tools.agentToAgent.enabled: true，并在 allow 列表中声明允许通信的 agent ID。