多智能体路由

在一个运行的 Gateway(网关) 中运行多个 隔离的 智能体——每个智能体都有自己的工作区、状态目录（agentDirGateway(网关)）和会话历史记录——以及多个渠道账户（例如两个 WhatsApp）。入站消息通过绑定路由到正确的智能体。

此处的 智能体（agent） 是完整的、针对特定人设的范围：工作区文件、身份验证配置文件、模型注册表和会话存储。agentDir 是磁盘上的状态目录，用于在 ~/.openclaw/agents/<agentId>/SlackWhatsApp 保存此针对特定智能体的配置。绑定（binding） 将渠道账户（例如 Slack 工作区或 WhatsApp 号码）映射到这些智能体之一。

什么是“一个智能体”？

智能体（agent） 是一个具有完整范围的“大脑”，拥有自己的：

工作区（Workspace）（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
状态目录（State directory）（agentDir），用于存放身份验证配置文件、模型注册表和针对特定智能体的配置。
会话存储（Session store）（聊天历史记录 + 路由状态），位于 ~/.openclaw/agents/<agentId>/sessions 下。

身份验证配置文件是 针对特定智能体（per-agent） 的。每个智能体从自己的以下位置读取：

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

Skills 会从每个 agent 的工作区以及共享根目录（例如 ~/.openclaw/skills）加载，然后在配置时根据有效的 agent Skills 允许列表进行过滤。使用 agents.defaults.skills 作为共享基线，使用 agents.list[].skills 进行每个 agent 的替换。请参阅 Skills: per-agent vs shared 和 Skills: agent skill allowlists。

Gateway 可以并排托管一个代理（默认）或多个代理。

路径（快速地图）

配置：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）
状态目录：~/.openclaw（或 OPENCLAW_STATE_DIR）
工作区：~/.openclaw/workspace（或 ~/.openclaw/workspace-<agentId>）
代理目录：~/.openclaw/agents/<agentId>/agent（或 agents.list[].agentDir）
会话：~/.openclaw/agents/<agentId>/sessions

单代理模式（默认）

如果您不进行任何操作，OpenClaw 将运行单个代理：

agentId 默认为 main。
会话的键为 agent:main:<mainKey>。
工作区默认为 ~/.openclaw/workspace（或在设置了 OPENCLAW_PROFILE 时为 ~/.openclaw/workspace-<profile>）。
状态默认为 ~/.openclaw/agents/main/agent。

代理助手

使用代理向导添加一个新的隔离代理：

openclaw agents add work

然后添加 bindings （或者让向导来完成）以路由传入消息。

使用以下命令验证：

openclaw agents list --bindings

快速开始

创建每个代理工作区
使用向导或手动创建工作区：
Terminal window
```
openclaw agents add coding
openclaw agents add social
```
每个代理都有自己的工作区，包含 SOUL.md、AGENTS.md 和可选的 USER.md，以及位于 `~/.openclaw/agents/
下的专用agentDir` 和会话存储。
创建渠道账号
在您偏好的渠道上为每个 agent 创建一个账号：
- Discord：每个 agent 一个 bot，启用 Message Content Intent，复制每个 token。
- Telegram：通过 BotFather 为每个 agent 创建一个 bot，复制每个 token。
- WhatsApp：将每个电话号码链接到一个账号。
Terminal window
```
openclaw channels login --channel whatsapp --account work
```Discord

请参阅渠道指南：[Discord](/en/channels/discordTelegram)、[Telegram](/en/channels/telegramWhatsApp)、[WhatsApp](/en/channels/whatsapp)。
```
添加代理、账号和绑定
在 agents.list 下添加代理，在 `channels.
.accounts下添加渠道账号，并使用bindings` 将它们连接起来（示例如下）。

重启并验证

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

多个代理 = 多个人物，多种个性

使用多个代理时，每个 agentId 都会变成一个完全隔离的人物设定：

不同的电话号码/账号（针对每个渠道 accountId）。
不同的个性（每个代理的工作区文件，如 AGENTS.md 和 SOUL.md）。
独立的认证 + 会话（除非明确启用，否则不会相互串扰）。

这允许多个人共享一个 Gateway(网关) 服务器，同时保持他们的 AI “大脑”和数据相互隔离。

跨代理 QMD 记忆搜索

如果一个代理应该搜索另一个代理的 QMD 会话记录，请在 agents.list[].memorySearch.qmd.extraCollections 下添加额外的集合。仅当每个代理都应继承相同的共享记录集合时，才使用 agents.defaults.memorySearch.qmd.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" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

额外的集合路径可以在代理之间共享，但当路径位于代理工作区之外时，集合名称保持显式。工作区内的路径仍属于代理作用域，因此每个代理保留自己的记录搜索集。

一个 WhatsApp 号码，多个人（私信拆分）

您可以在保持一个 WhatsApp 账户的同时，将不同的 WhatsApp 私信路由到不同的代理。使用 peer.kind: "direct"WhatsApp 匹配发送者 E.164（例如 WhatsAppWhatsApp+15551234567）。回复仍来自同一个 WhatsApp 号码（没有每个代理的发送者身份）。

示例：

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" },
    ],
  },
  bindings: [
    {
      agentId: "alex",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },
    },
    {
      agentId: "mia",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },
    },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

注意事项：

私信访问控制是每个 WhatsApp 账户的全局设置（配对/允许列表），而不是针对每个代理的。
对于共享群组，请将群组绑定到一个 agent，或使用 Broadcast groups。

路由规则（消息如何选择代理）

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

peer match
精确的私信/群组/渠道 id。
parentPeer match
线程继承。
guildId + roles
Discord 角色路由。
guildId
Discord。
teamId
Slack。
accountId match for a 渠道
每个账户的后备选项。
渠道级匹配
accountId: "*"。
默认代理
回退到 agents.list[].default，否则回退到列表中的第一个条目，默认值：main。

决胜局与 AND 语义

如果在同一层级有多个绑定匹配，则配置顺序中靠前的那个获胜。
如果一个绑定设置了多个匹配字段（例如 peer + guildId），则所有指定的字段都是必需的（AND 语义）。

Account-scope detail

省略 accountId 的绑定仅匹配默认账号，不匹配所有账号。
使用 accountId: "*" 作为跨所有账号的渠道范围回退。
使用 `accountId: ”

“`OpenClaw 来匹配特定账号。 - 如果您稍后使用显式账号 id 为同一 agent 添加相同的绑定，OpenClaw 会将现有的仅渠道绑定升级为账号范围绑定，而不是复制它。

多个账号 / 电话号码

支持多个账户的渠道（例如 WhatsApp）使用 accountId 来标识每次登录。每个 accountId 都可以路由到不同的代理，因此一台服务器可以托管多个电话号码而不会混淆会话。

如果您希望在省略 accountId 时有一个全渠道的默认账户，请设置 channels.<channel>.defaultAccount（可选）。如果未设置，OpenClaw 将回退到 default（如果存在），否则回退到第一个配置的账户 id（已排序）。

支持此模式的常见渠道包括：

whatsapp，telegram，discord，slack，signal，imessage
irc，line，googlechat，mattermost，matrix，nextcloud-talk
zalo，zalouser，nostr，feishu

概念

agentId：一个“大脑”（工作区、每个代理的身份验证、每个代理的会话存储）。
accountId：一个渠道账户实例（例如 WhatsApp 账户 "personal" 对比 "biz"）。
binding：根据 (channel, accountId, peer) 以及可选的公会/团队 ID 将传入消息路由到 agentId。
直接聊天会合并为 agent:<agentId>:<mainKey>（每个代理的“主”通道；session.mainKey）。

平台示例

每个代理的 Discord 机器人

每个 Discord 机器人账户都映射到一个唯一的 accountId。将每个账户绑定到一个代理，并为每个机器人维护允许列表。

{
  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: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "DISCORD_BOT_TOKEN_MAIN",
          guilds: {
            "123456789012345678": {
              channels: {
                "222222222222222222": { allow: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "DISCORD_BOT_TOKEN_CODING",
          guilds: {
            "123456789012345678": {
              channels: {
                "333333333333333333": { allow: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}

邀请每个机器人加入公会并启用消息内容意图。
令牌位于 `channels.discord.accounts.

.token中（默认账户可以使用DISCORD_BOT_TOKEN`）。

每个 agent 的 Telegram 机器人

{
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },
    ],
  },
  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"],
        },
      },
    },
  },
}

使用 BotFather 为每个 agent 创建一个机器人，并复制每个 token。
Token 存放在 `channels.telegram.accounts.

.botToken中（默认账户可以使用TELEGRAM_BOT_TOKEN）。 - 对于同一个 Telegram 群组中的多个机器人，请邀请每个机器人并 @提及应该回答的机器人。 - 为每个群组机器人禁用 BotFather 的隐私模式，然后重新添加机器人，以便 Telegram 应用该设置。 - 允许使用 channels.telegram.groups的群组，或者仅将groupPolicy: “open”用于受信任的群组部署。 - 将发送者用户 ID 放入groupAllowFrom中。群组和超级群组 ID 属于channels.telegram.groups，而不属于 groupAllowFrom。 - 通过 accountId` 进行绑定，以便每个机器人路由到其自己的 agent。

每个 agent 的 WhatsApp 号码

在启动网关之前链接每个账户：

openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

~/.openclaw/openclaw.json (JSON5):

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    ],
  },

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

常见模式

按渠道拆分：将 WhatsApp 路由到一个快速的日常 agent，将 Telegram 路由到一个 Opus agent。

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

说明：

这些示例使用 accountId: "*"，因此如果您稍后添加账户，绑定仍将有效。
要将单个私信/群组路由到 Opus，同时将其余部分保留在聊天上，请为该对等方添加 match.peer 绑定；对等方匹配始终优先于全渠道规则。

将 WhatsApp 保留在快速 agent 上，但将一个私信路由到 Opus：

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    {
      agentId: "opus",
      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },
  ],
}

对等方绑定始终优先，因此请将它们放在全渠道规则之上。

将专用的家庭代理绑定到单个 WhatsApp 群组，并设置提及门控和更严格的工具策略：

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: [
            "exec",
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],
}