多代理路由

目标:在一个运行的网关中实现多个_隔离的_代理(独立的工作区 + 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 获取。参见技能:每个代理 vs 共享。

网关可以托管一个代理(默认)或多个代理并行运行。

工作区注意事项: 每个代理的工作区是默认工作目录,而不是严格的沙箱。相对路径在工作区内解析,但绝对路径可以访问其他主机位置,除非启用了沙箱。参见沙箱。

路径(快速映射)

配置: ~/.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。

代理助手

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

bash

openclaw agents add work

然后添加 bindings(或让向导执行)以路由入站消息。

验证:

bash

openclaw agents list --bindings

多个代理 = 多个人、多个个性

使用多个代理,每个 agentId 成为一个完全隔离的角色:

不同的电话号码/账户(每个渠道 accountId)。
不同的个性(每个代理的工作区文件,如 AGENTS.md 和 SOUL.md)。
独立的认证 + 会话(除非明确启用,否则不会交叉)。

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

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

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

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

示例:

json5

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-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 账户全局的(配对/白名单),而不是每个代理。
对于共享群组,将群组绑定到一个代理或使用广播群组。

路由规则(消息如何选择代理)

绑定是确定性的,最具体的优先:

peer 匹配(精确的 DM/群组/渠道 id)
guildId(Discord)
teamId(Slack)
渠道的 accountId 匹配
渠道级别匹配(accountId: "*")
回退到默认代理(agents.list[].default,否则为列表第一项,默认: main)

多个账户/电话号码

支持多个账户的渠道(例如 WhatsApp)使用 accountId 来识别每个登录。每个 accountId 可以路由到不同的代理,因此一个服务器可以托管多个电话号码而不会混淆会话。

概念

agentId: 一个"大脑"(工作区、每个代理的认证、每个代理的会话存储)。
accountId: 一个渠道账户实例(例如 WhatsApp 账户 "personal" vs "biz")。
binding: 通过 (channel, accountId, peer) 将入站消息路由到 agentId,可选地包含 guild/team id。
直接聊天折叠到 agent:<agentId>:<mainKey>(每个代理的"主"; session.mainKey)。

示例:两个 WhatsApp → 两个代理

~/.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",
      },
    ],
  },

  // 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 路由到快速的日常代理,将 Telegram 路由到 Opus 代理。

json5

{
  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-5",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

注意:

如果一个渠道有多个账户,请在绑定中添加 accountId(例如 { channel: "whatsapp", accountId: "personal" })。
要将单个 DM/群组路由到 Opus,同时保持其他在 chat 上,为该对等方添加 match.peer 绑定;对等方匹配总是优先于渠道范围的规则。

示例:相同渠道,一个对等方到 Opus

将 WhatsApp 保持在快速代理上,但将一个 DM 路由到 Opus:

json5

{
  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-5",
      },
    ],
  },
  bindings: [
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

对等方绑定总是优先,所以将它们放在渠道范围规则之上。

绑定到 WhatsApp 群组的家庭代理

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

json5

{
  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: "120363999999999999@g.us" },
      },
    },
  ],
}

注意:

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

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

从 v2026.1.6 开始,每个代理可以拥有自己的沙箱和工具限制:

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-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 下,在容器创建时运行一次。当解析的范围是 "shared" 时,每个代理的 sandbox.docker.* 覆盖会被忽略。

优势:

安全隔离: 为不受信任的代理限制工具
资源控制: 沙箱特定代理,同时保持其他代理在主机上
灵活策略: 每个代理不同的权限

注意: tools.elevated 是全局的且基于发送者;它不能按代理配置。如果您需要每个代理的边界,使用 agents.list[].tools 拒绝 exec。对于群组定位,使用 agents.list[].groupChat.mentionPatterns,这样 @提及可以清晰地映射到目标代理。

参见多代理沙箱和工具以获取详细示例。

多代理路由 ​

什么是"一个代理"? ​

路径(快速映射) ​

单代理模式(默认) ​

代理助手 ​

多个代理 = 多个人、多个个性 ​

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

路由规则(消息如何选择代理) ​

多个账户/电话号码 ​

概念 ​

示例:两个 WhatsApp → 两个代理 ​

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

示例:相同渠道,一个对等方到 Opus ​

绑定到 WhatsApp 群组的家庭代理 ​

每个代理的沙箱和工具配置 ​

多代理路由

什么是"一个代理"?

路径(快速映射)

单代理模式(默认)

代理助手

多个代理 = 多个人、多个个性

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

路由规则(消息如何选择代理)

多个账户/电话号码

概念

示例:两个 WhatsApp → 两个代理

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

示例:相同渠道,一个对等方到 Opus

绑定到 WhatsApp 群组的家庭代理

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