OpenClaw 🦞

多 Agent 路由

多 Agent 路由

目标：多个_隔离的_ agent（单独的工作空间 + agentDir + 会话），加上一个运行 Gateway 中的多个频道账户（例如两个 WhatsApp）。入站通过绑定路由到 agent。

什么是"一个 agent"？

一个agent是一个完全范围的 brain，拥有自己的：

  • 工作空间（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、角色规则）。
  • 状态目录（agentDir）用于认证配置文件、模型注册表和每 agent 配置。
  • 会话存储（聊天历史 + 路由状态）在 ~/.openclaw/agents/<agentId>/sessions 下。

认证配置文件是每 agent的。每个 agent 从自己的读取：

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

主 agent 凭据不自动共享。永远不要在 agent 之间重用 agentDir（它会导致认证/会话冲突）。如果你想共享凭据，将 auth-profiles.json 复制到另一个 agent 的 agentDir 中。

Skills 通过每个工作空间的 skills/ 文件夹每 agent，共享 skills 可从 ~/.openclaw/skills 获得。参见 Skills: per-agent vs shared。

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

工作空间说明： 每个 agent 的工作空间是默认 cwd，不是硬沙箱。相对路径在工作空间内解析，但绝对路径可以到达其他主机位置，除非启用沙箱。参见 Sandboxing。

路径（快速映射）

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

单 agent 模式（默认）

如果你什么都不做，OpenClaw 运行单个 agent：

  • agentId 默认为**main**。
  • 会话键控为 agent:main:<mainKey>。
  • 工作空间默认为 ~/.openclaw/workspace（或设置 OPENCLAW_PROFILE 时为 ~/.openclaw/workspace-<profile>）。
  • 状态默认为 ~/.openclaw/agents/main/agent。

Agent 助手

使用 agent 向导添加新的隔离 agent：

openclaw agents add work

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

验证：

openclaw agents list --bindings

快速入门

1

创建每个 agent 工作空间

使用向导或手动创建工作空间：

openclaw agents add coding
openclaw agents add social

每个 agent 获得自己的工作空间，带有 SOUL.md、AGENTS.md 和可选 USER.md，加上专用的 agentDir 和 ~/.openclaw/agents/<agentId> 下的会话存储。

2

创建频道账户

为你首选的频道为每个 agent 创建一个账户：

  • Discord：每个 agent 一个 bot，启用 Message Content Intent，复制每个令牌。
  • Telegram：通过 BotFather 为每个 agent 一个 bot，复制每个令牌。
  • WhatsApp：为每个账户链接每个电话号码。
openclaw channels login --channel whatsapp --account work

参见频道指南：Discord、Telegram、WhatsApp。

3

添加 agent、账户和绑定

在 agents.list 下添加 agent，在 channels.<channel>.accounts 下添加频道账户，并用 bindings 连接它们（下面的示例）。

4

重启并验证

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

多个 agent = 多个人，多个角色

使用多个 agent，每个 agentId 成为完全隔离的角色：

  • 不同的电话号码/账户（每频道 accountId）。
  • 不同的角色（每 agent 工作空间文件如 AGENTS.md 和 SOUL.md）。
  • 单独的认证 + 会话（除非显式启用，否则无交叉对话）。

这让多个人共享一个 Gateway 服务器，同时保持他们的 AI "brains" 和数据隔离。

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

你可以路由不同的 WhatsApp DM到不同的 agent，同时保持在一个 WhatsApp 账户上。匹配发送者 E.164（如 +15551234567）与 peer.kind: "direct"。回复仍然来自同一个 WhatsApp 号码（无每 agent 发送者身份）。

重要细节：直接聊天折叠到 agent 的主会话键，因此真正的隔离需要每人一个 agent。

示例：

{
  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"],
    },
  },
}

注意：

  • DM 访问控制是每 WhatsApp 账户全局（配对/允许列表），不是每 agent。
  • 对于共享群组，将群组绑定到一个 agent 或使用 Broadcast groups。

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

绑定是确定性的和最具体获胜：

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

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

重要账户范围细节：

  • 省略 accountId 的绑定仅匹配默认账户。
  • 使用 accountId: "*" 作为跨所有账户的频道范围回退。
  • 如果你后来为同一 agent 添加带有显式账户 id 的相同绑定，OpenClaw 将现有仅频道绑定升级为账户范围，而不是复制它。

多个账户/电话号码

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

如果你想在省略 accountId 时拥有频道范围的默认账户，设置 channels.<channel>.defaultAccount（可选）。未设置时，如果存在则 OpenClaw 回退到 default，否则第一个配置的账户 id（排序）。

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

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

概念

  • agentId：一个 "brain"（工作空间、每 agent 认证、每 agent 会话存储）。
  • accountId：一个频道账户实例（例如 WhatsApp 账户 "personal" vs "biz"）。
  • binding：通过 (channel, accountId, peer) 路由入站消息到 agentId，可选 guild/team ids。
  • 直接聊天折叠到 agent:<agentId>:<mainKey>（每 agent "main"；session.mainKey）。

平台示例

每 agent Discord bots

每个 Discord bot 账户映射到唯一的 accountId。将每个账户绑定到 agent 并保持每个 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: {
      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 },
              },
            },
          },
        },
      },
    },
  },
}

注意：

  • 邀请每个 bot 到 guild 并启用 Message Content Intent。
  • 令牌存在于 channels.discord.accounts.<id>.token（默认账户可以使用 DISCORD_BOT_TOKEN）。

每 agent Telegram bots

{
  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 创建一个 bot 并复制每个令牌。
  • 令牌存在于 channels.telegram.accounts.<id>.botToken（默认账户可以使用 TELEGRAM_BOT_TOKEN）。

每 agent WhatsApp 号码

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

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",
      },
    ],
  },

  // 确定性路由：第一个匹配获胜（最具体优先）。
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // 可选每 peer 覆盖（示例：发送特定群组到 work agent）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // 默认关闭：agent-to-agent 消息必须显式启用 + 允许列表。
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // 可选覆盖。默认：~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // 可选覆盖。默认：~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

示例：WhatsApp 日常聊天 + Telegram 深度工作

按频道拆分：路由 WhatsApp 到快速日常 agent，Telegram 到 Opus agent。

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

注意：

  • 如果你为频道有多个账户，在绑定中添加 accountId（例如 { channel: "whatsapp", accountId: "personal" }）。
  • 要将单个 DM/群组路由到 Opus 而将其余保留在 chat 上，为该 peer 添加 match.peer 绑定；peer 匹配始终胜过频道范围规则。

示例：同一频道，一个 peer 到 Opus

保持 WhatsApp 在快速 agent 上，但路由一个 DM 到 Opus：

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

Peer 绑定始终获胜，因此将它们保持在频道范围规则之上。

绑定到 WhatsApp 群组的家庭 agent

将专用家庭 agent 绑定到单个 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: "120363999999999999@g.us" },
      },
    },
  ],
}

注意：

  • 工具允许/拒绝列表是工具，不是 skills。如果 skill 需要运行二进制文件，确保 exec 允许且二进制文件存在于沙箱中。
  • 对于更严格的门控，设置 agents.list[].groupChat.mentionPatterns 并保持频道启用群组允许列表。

每 Agent 沙箱和工具配置

从 v2026.1.6 开始，每个 agent 可以有自己的沙箱和工具限制：

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // 个人 agent 无沙箱
        },
        // 无工具限制 - 所有工具可用
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-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"],    // 拒绝其他
        },
      },
    ],
  },
}

注意：setupCommand 存在于 sandbox.docker 下，在容器创建时运行一次。 当解析的范围是 "shared" 时，每 agent sandbox.docker.* 覆盖被忽略。

好处：

  • 安全隔离：为不受信任的 agent 限制工具
  • 资源控制：沙箱特定 agent，同时保持其他在主机上
  • 灵活策略：每 agent 不同权限

注意：tools.elevated 是全局和基于发送者的；不可每 agent 配置。 如果你需要每 agent 边界，使用 agents.list[].tools 拒绝 exec。 对于群组定位，使用 agents.list[].groupChat.mentionPatterns 以便 @mentions 清晰映射到预期的 agent。

参见 Multi-Agent Sandbox & Tools 了解详细示例。