多 Agent 路由

目标：在一个运行的 Gateway 中管理多个_隔离_的 agent（独立工作区 + agentDir + 会话）以及多个通道账户（比如两个 WhatsApp 号码）。入站消息通过绑定规则路由到对应的 agent。

什么是”一个 agent”？

一个 agent 是一个完全独立的大脑，拥有自己的：

工作区（文件、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：按 agent 与共享。

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

工作区说明： 每个 agent 的工作区是默认工作目录，不是硬性沙箱。相对路径在工作区内解析，但绝对路径可以访问主机上的其他位置——除非启用了沙箱。详见沙箱。

路径速查

配置：~/.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。
会话 key 格式为 agent:main:<mainKey>。
工作区默认为 ~/.openclaw/workspace（设置了 OPENCLAW_PROFILE 时为 ~/.openclaw/workspace-<profile>）。
状态默认为 ~/.openclaw/agents/main/agent。

Agent 辅助工具

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

openclaw agents add work

然后添加 bindings（或让向导来做）把入站消息路由到该 agent。

验证：

openclaw agents list --bindings

快速上手

第 1 步：创建每个 agent 的工作区

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

openclaw agents add coding
openclaw agents add social

每个 agent 都有自己的工作区（含 SOUL.md、AGENTS.md 和可选的 USER.md），以及 ~/.openclaw/agents/<agentId> 下的专用 agentDir 和会话存储。

第 2 步：创建通道账户

为每个 agent 在你选择的通道上创建一个账户：

Discord：每个 agent 一个机器人，启用 Message Content Intent，复制各自的 token。
Telegram：每个 agent 通过 BotFather 创建一个机器人，复制各自的 token。
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”大脑”和数据完全隔离。

一个 WhatsApp 号码，多人使用（私聊拆分）

你可以把不同的 WhatsApp 私聊路由到不同的 agent，同时保持在一个 WhatsApp 账户上。用发送者的 E.164 格式（如 +15551234567）配合 peer.kind: "direct" 匹配。回复仍然从同一个 WhatsApp 号码发出（没有按 agent 区分发送者身份）。

重要细节：私聊会合并到 agent 的 main 会话 key，所以真正的隔离需要每人一个 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"],
    },
  },
}

注意：

私聊访问控制是整个 WhatsApp 账户全局的（配对/白名单），不是按 agent。
对于共享群组，把群组绑定到一个 agent，或使用广播群组。

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

绑定是确定性的，最具体的匹配优先：

peer 匹配（精确的私聊/群组/频道 ID）
parentPeer 匹配（线程继承）
guildId + roles（Discord 角色路由）
guildId（Discord）
teamId（Slack）
accountId 匹配通道
通道级匹配（accountId: "*"）
回退到默认 agent（agents.list[].default，否则列表第一个，默认：main）

如果同一层级有多个绑定匹配，配置中靠前的优先。如果一个绑定设置了多个匹配字段（比如 peer + guildId），所有指定字段都必须满足（AND 语义）。

账户作用域的重要细节：

省略 accountId 的绑定只匹配默认账户。
用 accountId: "*" 作为跨所有账户的通道级回退。
如果你后来为同一个 agent 添加了带显式 account id 的相同绑定，OpenClaw 会把已有的仅通道绑定升级为带账户作用域的，而不是创建重复项。

多账户/多手机号

支持多账户的通道（如 WhatsApp）使用 accountId 标识每次登录。每个 accountId 可以路由到不同的 agent，这样一台服务器可以托管多个手机号而不会混淆会话。

如果你想在省略 accountId 时有一个通道级的默认账户，设置 channels.<channel>.defaultAccount（可选）。不设置时，OpenClaw 回退到 default（如果存在），否则使用第一个配置的 account id（按排序）。

支持此模式的常见通道：

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

概念

agentId：一个”大脑”（工作区、认证、会话存储）。
accountId：一个通道账户实例（如 WhatsApp 账户 "personal" vs "biz"）。
binding：把入站消息按 (channel, accountId, peer) 以及可选的 guild/team ID 路由到 agentId。
私聊合并到 agent:<agentId>:<mainKey>（每个 agent 的”main”；session.mainKey）。

平台示例

Discord 每 agent 一个机器人

每个 Discord 机器人账户对应一个唯一的 accountId。把每个账户绑定到一个 agent，每个机器人保持独立的白名单。

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

注意：

把每个机器人邀请到 guild 并启用 Message Content Intent。
Token 存放在 channels.discord.accounts.<id>.token（默认账户可以用 DISCORD_BOT_TOKEN）。

Telegram 每 agent 一个机器人

{
  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.<id>.botToken（默认账户可以用 TELEGRAM_BOT_TOKEN）。

WhatsApp 每 agent 一个号码

启动 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" } },

    // 可选的按对等方覆盖（示例：把某个群组发送到 work agent）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // 默认关闭：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" }）。
要把单个私聊/群组路由到 Opus 而其余保持在 chat 上，添加一个带 match.peer 的绑定；peer 匹配始终优先于通道级规则。

示例：同一通道，一个对等方用 Opus

WhatsApp 保持快速 agent，但把一个私聊路由到 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 绑定始终优先，所以把它放在通道级规则上面。

绑定家庭 agent 到 WhatsApp 群组

把一个专用的家庭 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: "[email protected]" },
      },
    },
  ],
}

注意：

工具的 allow/deny 列表针对的是工具，不是 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 下，在容器创建时执行一次。当解析后的 scope 为 "shared" 时，每 agent 的 sandbox.docker.* 覆盖会被忽略。

好处：

安全隔离：为不可信的 agent 限制工具
资源控制：只对特定 agent 启用沙箱，其他保持在主机上
灵活策略：每个 agent 不同的权限

注意：tools.elevated 是全局的，基于发送者；不能按 agent 配置。如果需要按 agent 设置边界，使用 agents.list[].tools 来拒绝 exec。对于群组定向，使用 agents.list[].groupChat.mentionPatterns 让 @提及准确映射到目标 agent。

详见多 Agent 沙箱与工具。