多代理路?

目标：多?*隔离?*代理（独立的工作?+ agentDir + 会话），外加一个运行网关中的多个通道账户（例如两?WhatsApp）。入站通过绑定路由到代理?

什么是”一个代??

代理是一个完整作用域的大脑，拥有自己的：

  • **工作?*（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、角色规则）?
  • **状态目?*（agentDir），用于认证配置、模型注册表和每个代理的配置?
  • 会话存储（聊天历?+ 路由状态），位?~/.openclaw/agents/<agentId>/sessions?

认证配置**按代?*。每个代理从自己的位置读取：

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

主要代理凭证不会自动共享。切勿跨代理重用 agentDir（会导致认证/会话冲突）。如果你想共享凭证，请将 auth-profiles.json 复制到其他代理的 agentDir 中?

技能通过每个工作区的 skills/ 文件夹按代理提供，共享技能可?~/.openclaw/skills 获取。请参阅技能：按代理与共享?

网关可以托管一?*代理（默认）?*多个代理并排运行?

工作区注意： 每个代理的工作区?默认 cwd*，而不是硬沙盒。相对路径在工作区内解析，但如果启用沙盒，绝对路径可以到达其他主机位置。请参阅沙盒?

路径（快速映射）

  • 配置：~/.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

快速开?

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

openclaw agents add coding
openclaw agents add social

每个代理获得自己的带?SOUL.md、AGENTS.md 和可?USER.md 的工作区，外加专?agentDir 和位?~/.openclaw/agents/<agentId> 下的会话存储?

在首选通道上为每个代理创建一个账户：

  • Discord：每个代理一个机器人，启用消息内容意图，复制每个令牌?
  • Telegram：通过 BotFather 为每个代理创建一个机器人，复制每个令牌?
  • WhatsApp：链接每个账户的电话号码?
openclaw channels login --channel whatsapp --account work

请参阅通道指南：Discord、Telegram、WhatsApp?

?agents.list 下添加代理，?channels.<channel>.accounts 下添加通道账户，并使用 bindings 连接它们（示例如下）?

<Step title=“重启并验?>

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

多个代理 = 多个身份、多个性格

使用多个代理时，每个 agentId 成为**完全隔离的角?*?

  • 不同的电话号?账户（每个通道 accountId）?
  • 不同的性格（每个代理的工作区文件，?AGENTS.md ?SOUL.md）?
  • 独立的认?+ 会话（除非明确启用，否则不会交叉）?

这允许多人共享一个网关服务器，同时保持他们的 AI”大脑”和数据隔离?

一?WhatsApp 号码、多个身份（DM 拆分?

你可以将不同?WhatsApp DM 路由到不同的代理，同时保持在一?WhatsApp 账户上。按发送?E.164 匹配（如 +15551234567），使用 peer.kind: "direct"。回复仍然来自同一?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"],
    },
  },
}

说明?

  • DM 访问控制?*每个 WhatsApp 账户全局**的（配对/白名单），不是按代理的?
  • 对于共享群组，将群组绑定到一个代理或使用广播群组?

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

绑定?*确定?的，**最具体的获??

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

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

重要的账户作用域细节?

  • 省略 accountId 的绑定仅匹配默认账户?
  • 使用 accountId: "*" 作为跨所有账户的通道级回退?
  • 如果你稍后为同一代理添加带有显式账户 ID 的相同绑定，OpenClaw 会将现有通道级绑定升级为账户作用域，而不是重复它?

多个账户/电话号码

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

概念

  • agentId?一个大?（工作区、按代理认证、按代理会话存储）?
  • accountId：一个通道账户实例（例?WhatsApp 账户 "personal" 对比 "biz"）?
  • binding：通过 (channel, accountId, peer) 可选地通过 guild/team 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.<id>.token（默认账户可以使?DISCORD_BOT_TOKEN）?

每个代理?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 为每个代理创建一个机器人并复制每个令牌?
  • 令牌位于 channels.telegram.accounts.<id>.botToken（默认账户可以使?TELEGRAM_BOT_TOKEN）?

每个代理?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",
      },
    ],
  },

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

    // 可选的?peer 覆盖（示例：将特定群组发送到 work 代理）?
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // 默认关闭：代理间消息必须明确启用 + 白名单?
  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 路由到快速的日常代理，将 Telegram 路由?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: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

说明?

  • 如果一个通道有多个账户，请将 accountId 添加到绑定中（例?{ channel: "whatsapp", accountId: "personal" }）?
  • 要将单个 DM/群组路由?Opus，同时将其他保留?chat 上，请添加该 peer ?match.peer 绑定；peer 匹配始终优于通道级规则?

示例：同一通道，一?peer ?Opus

?WhatsApp 保留在快速代理上，但将一?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 群组的家庭代?

将专用家庭代理绑定到单个 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]" },
      },
    },
  ],
}

说明?

  • 工具允许/拒绝列表?工具*，而不是技能。如果技能需要运行二进制文件，请确保 exec 被允许且二进制文件存在于沙盒中?
  • 对于更严格的门控，请设置 agents.list[].groupChat.mentionPatterns 并保持通道的群组白名单启用?

每个代理的沙盒和工具配置

?v2026.1.6 开始，每个代理可以有自己的沙盒和工具限制：

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // 个人代理无沙?
        },
        // 无工具限?- 所有工具可?
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // 始终沙盒?
          scope: "agent",  // 每个代理一个容?
          docker: {
            // 容器创建后的一次性设置（可选）
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // 仅读取工?
          deny: ["exec", "write", "edit", "apply_patch"],    // 拒绝其他
        },
      },
    ],
  },
}

注意：setupCommand 位于 sandbox.docker 下，在容器创建时运行一次。当解析的作用域?"shared" 时，忽略每个代理?sandbox.docker.* 覆盖?

*优势?

  • *安全隔离? 为不受信任的代理限制工具
  • *资源控制? 沙盒化特定代理，同时将其他保留在主机?
  • 灵活的策略： 每个代理不同的权?

注意：tools.elevated ?*全局**的且基于发件人；它不能按代理配置? 如果你需要按代理的边界，使用 agents.list[].tools 拒绝 exec? 对于群组定位，使?agents.list[].groupChat.mentionPatterns，以?@提及能干净地映射到目标代理?

请参阅多代理沙盒和工具获取详细示例?