多智能体路由 (Multi-Agent Routing)

目标：在一个运行中的网关中支持多个独立的智能体（拥有独立的 workspace + agentDir + sessions），以及多个频道账号（例如两个 WhatsApp 账号）。入站消息通过“绑定 (bindings)”路由到指定的智能体。

什么是“一个智能体”？

一个智能体 (agent) 是一个完整作用域的“大脑”，拥有自己的：

工作区 (Workspace)：文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格规则。
状态目录 (agentDir)：用于存储身份验证配置文件 (auth profiles)、模型注册表和每个智能体的配置。
会话存储 (Session store)：位于 ~/.clawdbot/agents/<agentId>/sessions 下的聊天历史 + 路由状态。

身份验证配置文件是基于每个智能体的。每个智能体读取其专属的：

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

主智能体的凭据不会自动共享。切勿在多个智能体之间复用 agentDir（这会导致身份验证/会话冲突）。如果您想共享凭据，请将 auth-profiles.json 复制到另一个智能体的 agentDir 中。

技能通过每个工作区的 skills/ 文件夹实现每智能体化，同时 ~/.clawdbot/skills 中也提供共享技能。参见技能：每智能体 vs 共享。

网关可以承载一个智能体（默认）或多个并行的智能体。

工作区说明： 每个智能体的工作区是其默认的当前工作目录 (cwd)，并非严格的沙箱。相对路径在工作区内解析，但除非启用了沙箱功能，否则绝对路径可以访问宿主机的其他位置。参见沙箱 (Sandboxing).

路径 (快速映射)

配置：~/.clawdbot/clawdbot.json (或 CLAWDBOT_CONFIG_PATH)
状态目录：~/.clawdbot (或 CLAWDBOT_STATE_DIR)
工作区：~/clawd (或 ~/clawd-<agentId>)
智能体目录：~/.clawdbot/agents/<agentId>/agent (或 agents.list[].agentDir)
会话：~/.clawdbot/agents/<agentId>/sessions

单智能体模式 (默认)

如果您不进行任何操作，Clawdbot 将运行单个智能体：

agentId 默认为 main。
会话键被标识为 agent:main:<mainKey>。
工作区默认为 ~/clawd（当设置了 CLAWDBOT_PROFILE 时，默认为 ~/clawd-<profile>）。
状态默认为 ~/.clawdbot/agents/main/agent。

智能体辅助命令

使用智能体向导添加一个新的独立智能体：

clawdbot agents add work

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

通过以下命令验证：

clawdbot agents list --bindings

多个智能体 = 多个人、多种人格

通过多个智能体，每个 agentId 都会成为一个完全隔离的人格：

不同的电话号码/账号（基于每个频道的 accountId）。
不同的人格（基于每个智能体工作区文件，如 AGENTS.md 和 SOUL.md）。
独立的身份验证 + 会话（除非明确启用，否则互不干扰）。

这使得多个人可以共享一个网关服务器，同时保持各自 AI “大脑”和数据的独立性。

一个 WhatsApp 号码，多个人 (DM 分流)

您可以将不同的 WhatsApp 私聊 (DM) 路由到不同的智能体，同时保持使用同一个 WhatsApp 账号。通过匹配发送者的 E.164 号码（如 +15551234567）并设置 peer.kind: "dm" 来实现。回复仍将来自同一个 WhatsApp 号码（没有每智能体的发送者身份）。

重要细节：直接聊天会归拢到智能体的主会话键 (main session key)，因此真正的隔离需要每人一个智能体。

示例：

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

注意：

私聊访问控制是基于每个 WhatsApp 账号全局生效的（配对/允许列表），而不是基于每个智能体。
对于共享群组，请将群组绑定到一个智能体，或使用广播群组 (Broadcast groups)。

路由规则 (消息如何挑选智能体)

绑定是确定性的，且遵循最匹配者优先原则：

peer 匹配（精确的私聊/群组/频道 ID）
guildId (Discord)
teamId (Slack)
频道的 accountId 匹配
频道级匹配 (accountId: "*")
回退到默认智能体（agents.list[].default，否则为列表中的第一个条目，默认值为 main）

多个账号 / 电话号码

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

概念

agentId：一个“大脑”（工作区、每智能体身份验证、每智能体会话存储）。
accountId：一个频道账号实例（例如 WhatsApp 账号 "personal" 与 "biz"）。
binding：通过 (channel, accountId, peer) 以及可选的 guild/team ID 将入站消息路由到 agentId。
直接聊天归拢到 agent:<agentId>:<mainKey>（每智能体“主”会话；session.mainKey）。

示例：两个 WhatsApp → 两个智能体

~/.clawdbot/clawdbot.json (JSON5):

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

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

    // 可选的针对特定对端 (peer) 的覆盖（示例：将特定群组发送给工作智能体）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // 默认关闭：智能体间消息传递必须明确启用并加入允许列表。
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

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

示例：WhatsApp 日常聊天 + Telegram 深度工作 (Example: WhatsApp daily chat + Telegram deep work)

按频道分流：将 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" }）。
要将单个私聊/群组路由到 Opus，同时保持其余在 chat 上，请为该对端添加 match.peer 绑定；对端匹配始终优于频道级规则。

示例：相同频道，一个对端路由到 Opus (Example: same channel, one peer to Opus)

保持 WhatsApp 在快速智能体上，但将一个私聊路由到 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 群组的家庭智能体 (Family agent bound to a WhatsApp group)

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

注意：

工具允许/拒绝列表是针对工具 (tools)，而不是技能 (skills)。如果一个技能需要运行二进制文件，请确保 exec 被允许且该二进制文件存在于沙箱中。
为了实现更严格的门控，请设置 agents.list[].groupChat.mentionPatterns 并保持频道的群组允许列表开启。

每智能体沙箱和工具配置 (Per-Agent Sandbox and Tool Configuration)

从 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"],                    // 仅允许 read 工具
          deny: ["exec", "write", "edit", "apply_patch"],    // 拒绝其他工具
        },
      },
    ],
  },
}

注意：setupCommand 位于 sandbox.docker 下，并在容器创建时运行一次。当解析的作用域为 "shared" 时，每智能体 sandbox.docker.* 覆盖将被忽略。

优势：

安全隔离：限制不受信任智能体的工具。
资源控制：沙箱化特定智能体，同时保持其他智能体在宿主机上。
灵活策略：每个智能体拥有不同的权限。

注意：tools.elevated 是全局且基于发送者的；它不能按智能体配置。如果您需要按智能体划分边界，请使用 agents.list[].tools 来拒绝 exec。对于群组目标，请使用 agents.list[].groupChat.mentionPatterns，以便 @提及能清晰地映射到预期的智能体。

请参阅多智能体沙箱与工具 (Multi-Agent Sandbox & Tools) 了解详细示例。

多智能体路由 (Multi-Agent Routing)

什么是“一个智能体”？​

路径 (快速映射)​

单智能体模式 (默认)​

智能体辅助命令​

多个智能体 = 多个人、多种人格​

一个 WhatsApp 号码，多个人 (DM 分流)​

路由规则 (消息如何挑选智能体)​

多个账号 / 电话号码​

概念​

示例：两个 WhatsApp → 两个智能体​

示例：WhatsApp 日常聊天 + Telegram 深度工作 (Example: WhatsApp daily chat + Telegram deep work)​

示例：相同频道，一个对端路由到 Opus (Example: same channel, one peer to Opus)​

绑定到 WhatsApp 群组的家庭智能体 (Family agent bound to a WhatsApp group)​

每智能体沙箱和工具配置 (Per-Agent Sandbox and Tool Configuration)​