文档
Multi-Agent Routing

Multi-Agent Routing

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

什么是"一个代理"？

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

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

身份验证配置文件是每个代理的。每个代理从自己的配置读取：

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

主代理凭据不自动共享。永远不要跨代理重用 agentDir（它会导致身份验证/会话冲突）。如果您想共享凭据，请将 auth-profiles.json 复制到另一个代理的 agentDir。

技能是每个代理的，通过每个工作空间的 skills/ 文件夹，共享技能可从 ~/.moltbot/skills 获得。请参阅 技能：每个代理 vs 共享。

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

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

路径（快速映射）

  • 配置：~/.moltbot/moltbot.json（或 MOLTBOT_CONFIG_PATH）
  • 状态目录：~/.moltbot（或 MOLTBOT_STATE_DIR）
  • 工作空间：~/clawd（或 ~/clawd-<agentId>）
  • 代理目录：~/.moltbot/agents/<agentId>/agent（或 agents.list[].agentDir）
  • 会话：~/.moltbot/agents/<agentId>/sessions

单代理模式（默认）

如果您什么都不做，Moltbot 会运行一个代理：

  • agentId 默认为 main。
  • 会话键为 agent:main:<mainKey>。
  • 工作空间默认为 ~/clawd（或设置 MOLTBOT_PROFILE 时的 ~/clawd-<profile>）。
  • 状态默认为 ~/.moltbot/agents/main/agent。

代理助手

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

moltbot agents add work

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

使用以下命令验证：

moltbot agents list --bindings

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

使用多个代理，每个 agentId 都成为一个完全隔离的角色：

  • 不同的电话号码/帐户（每个通道 accountId）。
  • 不同的个性（每个代理工作空间文件，如 AGENTS.md 和 SOUL.md）。
  • 独立的身份验证 + 会话（除非明确启用，否则不会串扰）。

这让多个人可以共享一个网关服务器，同时保持他们的 AI"大脑"和数据隔离。

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

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

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

示例：

{
  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 帐户的全局（配对/允许列表），而不是每个代理。
  • 对于共享群组，将群组绑定到一个代理或使用 广播群组。

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

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

  1. peer 匹配（确切的 DM/群组/通道 id）
  2. guildId（Discord）
  3. teamId（Slack）
  4. 通道的 accountId 匹配
  5. 通道级匹配（accountId: "*"）
  6. 回退到默认代理（agents.list[].default，否则第一个列表条目，默认：main）

多个帐户 / 电话号码

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

概念

  • agentId：一个"大脑"（工作空间、每个代理的身份验证、每个代理的会话存储）。
  • accountId：一个通道帐户实例（例如 WhatsApp 帐户 "personal" vs "biz"）。
  • binding：通过 (channel, accountId, peer) 并可选的 guild/team id 将入站消息路由到 agentId。
  • 直接聊天折叠到 agent:<agentId>:<mainKey>（每个代理的"主"；session.mainKey）。

示例：两个 WhatsApp → 两个代理

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

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

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

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

  // 默认关闭：代理到代理消息必须明确启用 + 允许列表。
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

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

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

按通道分割：将 WhatsApp 路由到快速日常代理，将 Telegram 路由到 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: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

注意：

  • 如果您有多个通道的帐户，请在绑定中添加 accountId（例如 { channel: "whatsapp", accountId: "personal" }）。
  • 要在将单个 DM/群组路由到 Opus 的同时保持其余部分在聊天上，请为该对等方添加 match.peer 绑定；对等方匹配总是胜过通道范围的规则。

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

保持 WhatsApp 在快速代理上，但将一个 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" } }
  ]
}

对等方绑定总是获胜，因此将它们保持在通道范围的规则之上。

绑定到 WhatsApp 群组的家庭代理

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

{
  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"]
        }
      }
    ]
  },
  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: "~/clawd-personal",
        sandbox: {
          mode: "off",  // 个人代理无沙盒
        },
        // 无工具限制 - 所有工具可用
      },
      {
        id: "family",
        workspace: "~/clawd-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，以便 @mentions 清洁地映射到预期的代理。

有关详细示例，请参阅 多代理沙盒和工具。

Models CLIMulti-Agent Sandbox & Tools Configuration