Multi-Agent Routing

目标：在一个运行中的 Gateway 内，支持多个隔离 agents（独立 workspace + agentDir + sessions），以及多个渠道账号（例如两个 WhatsApp）。入站消息会通过 bindings 被路由到某个 agent。

“一个 agent”是什么？

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

• Workspace（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、persona 规则）。
• State directory（agentDir），用于 auth profiles、model registry 与按 agent 的配置。
• Session store（聊天历史 + 路由状态），位于 ~/.openclaw/agents/<agentId>/sessions。

auth profiles 是 按 agent 隔离的。每个 agent 从自己的以下文件读取：

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

主 agent 的凭据不会自动共享。不要在多个 agents 之间复用 agentDir（会导致 auth/session 冲突）。如果你确实希望共享凭据，请把 auth-profiles.json 复制到另一个 agent 的 agentDir。

skills 也可以按 agent 使用各自 workspace 的 skills/ 文件夹；共享 skills 来自 ~/.openclaw/skills。 参见 Skills: per-agent vs shared。

Gateway 可以只托管 一个 agent（默认），也可以并排托管 多个 agents。

**Workspace 注意：**每个 agent 的 workspace 是默认 cwd，不是硬沙箱。相对路径会在 workspace 内解析，但如果未启用 sandboxing，绝对路径仍可访问主机的其他位置。参见 Sandboxing。

路径速查（quick map）

• Config：~/.openclaw/moltbot.json（或 openclaw_CONFIG_PATH）
• State dir：~/.openclaw（或 openclaw_STATE_DIR）
• Workspace：~/clawd（或 ~/clawd-<agentId>）
• Agent dir：~/.openclaw/agents/<agentId>/agent（或 agents.list[].agentDir）
• Sessions：~/.openclaw/agents/<agentId>/sessions

单 agent 模式（默认）

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

• agentId 默认是 main。
• Sessions 的 key 形如 agent:main:<mainKey>。
• Workspace 默认是 ~/clawd（若设置了 openclaw_PROFILE，则为 ~/clawd-<profile>）。
• State 默认是 ~/.openclaw/agents/main/agent。

Agent helper

用 agent wizard 添加一个新的隔离 agent：

moltbot agents add work

然后添加 bindings（或让 wizard 代劳）以路由入站消息。

验证：

moltbot agents list --bindings

多个 agents = 多个人，多种人格

在 多 agent 模式下，每个 agentId 都是一个完全隔离的 persona：

• 不同手机号/账号（按渠道的 accountId）。
• 不同人格（每个 agent 的 workspace files，如 AGENTS.md 与 SOUL.md）。
• 独立 auth + sessions（除非显式启用，否则不会互相串话）。

这允许多个人共享一台 Gateway 服务器，同时保持他们的 AI “大脑”与数据隔离。

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

你可以在同一个 WhatsApp 账号下，把不同 WhatsApp 私信（DM）路由到不同 agents。通过 peer.kind: "dm" 以及发送者的 E.164（例如 +15551234567）匹配。回复仍来自同一个 WhatsApp 号码（不会按 agent 改变发送者身份）。

重要细节：私聊会折叠到该 agent 的 main session key，因此想要真正隔离，通常需要每个人一个 agent。

示例：

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

备注：

• DM 访问控制对每个 WhatsApp 账号是全局的（pairing/allowlist），不是按 agent。
• 对共享群，绑定群到某个 agent，或使用 Broadcast groups。

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

Bindings 是确定性的，并遵循越具体越优先：

1. peer 匹配（精确 DM/group/channel id）
2. guildId（Discord）
3. teamId（Slack）
4. 某渠道的 accountId 匹配
5. 渠道级匹配（accountId: "*"）
6. 回退到默认 agent（agents.list[].default，否则列表第一项，默认：main）

多账号 / 多手机号

支持多账号的渠道（例如 WhatsApp）使用 accountId 标识每次登录。每个 accountId 都可以路由到不同 agent，因此一台服务器可以托管多个手机号而不混淆 sessions。

概念

• agentId：一个“大脑”（workspace、按 agent 的 auth、按 agent 的 session store）。
• accountId：一个渠道账号实例（例如 WhatsApp 账号 "personal" vs "biz"）。
• binding：用 (channel, accountId, peer)（可选 guild/team ids）把入站消息路由到某个 agentId。
• 私聊会折叠到 agent:<agentId>:<mainKey>（按 agent 的 “main”；session.mainKey）。

示例：两个 WhatsApp → 两个 agents

~/.openclaw/moltbot.json（JSON5）：

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        name: "Home",
        workspace: "~/clawd-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      {
        id: "work",
        name: "Work",
        workspace: "~/clawd-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: "1203630...@g.us" },
      },
    },
  ],

  // 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 日常 + Telegram 深度工作

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

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

备注：

• 若某渠道有多个账号，请在 binding 中加 accountId（例如 { channel: "whatsapp", accountId: "personal" }）。
• 想把单个 DM/group 路由到 Opus 而其余仍走 chat：为该 peer 增加 match.peer binding；peer 匹配永远优先于渠道级规则。

示例：同一渠道，把一个 peer 路由到 Opus

让 WhatsApp 默认走快 agent，但把一个 DM 路由到 Opus：

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

peer bindings 永远优先，因此请把它们放在渠道级规则之上。

绑定一个家庭 agent 到 WhatsApp 群

把一个专用家庭 agent 绑定到某个 WhatsApp 群，并设置 mention gating 与更严格的 tool policy：

{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/clawd-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", "gateway"]
        }
      }
    ]
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" }
      }
    }
  ]
}

备注：

• tool allow/deny 列表是针对 tools，不是 skills。如果某个 skill 需要执行二进制文件，请确保允许 exec，并且该二进制在 sandbox 中可用。
• 若需要更严格的触发条件，请设置 agents.list[].groupChat.mentionPatterns，并保持渠道的 group allowlists 启用。

按 agent 的 Sandbox 与工具配置

从 v2026.1.6 起，每个 agent 都可以有自己的 sandbox 与工具限制：

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/clawd-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/clawd-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}

注意：setupCommand 位于 sandbox.docker 下，并在容器创建时只运行一次。 当解析后的 scope 为 "shared" 时，按 agent 的 sandbox.docker.* 覆盖会被忽略。

收益：

• 安全隔离：限制不可信 agents 的工具权限
• 资源控制：只对部分 agents 做 sandbox，其余仍在 host 上运行
• 灵活策略：按 agent 设置不同权限

注意：tools.elevated 是全局且基于 sender 的；不能按 agent 配置。 如果你需要按 agent 的边界，请使用 agents.list[].tools 来 deny exec。 对群目标路由，请用 agents.list[].groupChat.mentionPatterns，让 @mentions 能稳定映射到预期 agent。

详见 Multi-Agent Sandbox & Tools。