Skip to main content

​
多 Agent 路由

目标：多个隔离的 Agent（独立工作区 + agentDir + 会话），加上多个频道账户（例如两个 WhatsApp）在一个运行的 Gateway 中。入站通过绑定路由到 Agent。

​
什么是”一个 Agent”？

一个 Agent 是一个完全限定的大脑，拥有自己的：
  • 工作区（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人设规则）。
  • 状态目录（agentDir），用于认证配置文件、模型注册表和每个 Agent 的配置。
  • 会话存储（聊天历史 + 路由状态）位于 ~/.openclaw/agents/<agentId>/sessions。
认证配置文件是每个 Agent的。每个 Agent 从自己的位置读取： 
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
主 Agent 凭证不会自动共享。永远不要跨 Agent 重用 agentDir （它会导致认证/会话冲突）。如果你想共享凭证， 将 auth-profiles.json 复制到另一个 Agent 的 agentDir 中。 Skills 通过每个工作区的 skills/ 文件夹按 Agent 划分，共享 skills 可从 ~/.openclaw/skills 获得。参见 Skills：每个 Agent 与共享。 Gateway 可以托管一个 Agent（默认）或并排托管多个 Agent。 工作区注意：每个 Agent 的工作区是默认 cwd，而不是硬 沙盒。相对路径在工作区内解析，但绝对路径可以 到达其他主机位置，除非启用了沙盒。参见 沙盒。

​
路径（快速映射）

  • 配置：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）
  • 状态目录：~/.openclaw（或 OPENCLAW_STATE_DIR）
  • 工作区：~/.openclaw/workspace（或 ~/.openclaw/workspace-<agentId>）
  • Agent 目录：~/.openclaw/agents/<agentId>/agent（或 agents.list[].agentDir）
  • 会话：~/.openclaw/agents/<agentId>/sessions

​
单 Agent 模式（默认）

如果你什么都不做，OpenClaw 运行单个 Agent：
  • agentId 默认为 main。
  • 会话键为 agent:main:<mainKey>。
  • 工作区默认为 ~/.openclaw/workspace（或当设置 OPENCLAW_PROFILE 时为 ~/.openclaw/workspace-<profile>）。
  • 状态默认为 ~/.openclaw/agents/main/agent。

​
Agent 助手

使用 Agent 向导添加新的隔离 Agent： 
openclaw agents add work
然后添加 bindings（或让向导完成）以路由入站消息。 使用以下命令验证： 
openclaw agents list --bindings

​
多个 Agent = 多个人、多种个性

使用多个 Agent，每个 agentId 成为一个完全隔离的人设：
  • 不同的电话号码/账户（每个频道 accountId）。
  • 不同的个性（每个 Agent 的工作区文件如 AGENTS.md 和 SOUL.md）。
  • 独立的认证 + 会话（除非显式启用，否则没有串扰）。
这让多个人共享一个 Gateway 服务器，同时保持他们的 AI “大脑”和数据隔离。

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

你可以将不同的 WhatsApp DM 路由到不同的 Agent，同时保持在一个 WhatsApp 账户上。使用发送者 E.164（如 +15551234567）匹配 peer.kind: "dm"。回复仍来自同一个 WhatsApp 号码（没有每个 Agent 的发送者身份）。 重要细节：直接聊天折叠到 Agent 的主会话键，因此真正的隔离需要每个人一个 Agent。 示例： 
{
  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 账户全局的（配对/允许列表），不是每个 Agent。
  • 对于共享群组，将群组绑定到一个 Agent 或使用广播群组。

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

绑定是确定性的，最具体的获胜：
  1. peer 匹配（精确的 DM/群组/频道 ID）
  2. guildId（Discord）
  3. teamId（Slack）
  4. 频道的 accountId 匹配
  5. 频道级匹配（accountId: "*"）
  6. 回退到默认 Agent（agents.list[].default，否则第一个列表条目，默认：main）

​
多个账户 / 电话号码

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

​
概念

  • agentId：一个”大脑”（工作区、每个 Agent 认证、每个 Agent 会话存储）。
  • accountId：一个频道账户实例（例如 WhatsApp 账户 "personal" 与 "biz"）。
  • binding：通过 (channel, accountId, peer) 和可选的公会/团队 ID 将入站消息路由到 agentId。
  • 直接聊天折叠到 agent:<agentId>:<mainKey>（每个 Agent “主”；session.mainKey）。

​
示例：两个 WhatsApp → 两个 Agent

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

    // 可选的每个对等覆盖（示例：将特定群组发送到工作 Agent）。
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // 默认关闭：Agent 到 Agent 的消息传递必须显式启用 + 允许列表。
  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 路由到快速日常 Agent，将 Telegram 路由到 Opus Agent。 
{
  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 保持在快速 Agent 上，但将一个 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-5",
      },
    ],
  },
  bindings: [
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}
对等绑定总是获胜，因此将它们保持在频道范围规则之上。

​
绑定到 WhatsApp 群组的家庭 Agent

将专用的家庭 Agent 绑定到单个 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: "120363999999999999@g.us" },
      },
    },
  ],
}
注意：
  • 工具允许/拒绝列表是工具，不是 skills。如果 skill 需要运行 二进制文件，确保 exec 被允许且二进制文件存在于沙盒中。
  • 对于更严格的门控，设置 agents.list[].groupChat.mentionPatterns 并保留 频道的群组允许列表启用。

​
每个 Agent 的沙盒和工具配置

从 v2026.1.6 开始，每个 Agent 可以有自己的沙盒和工具限制： 
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // 个人 Agent 没有沙盒
        },
        // 没有工具限制 - 所有工具可用
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // 始终沙盒化
          scope: "agent",  // 每个 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" 时，每个 Agent 的 sandbox.docker.* 覆盖被忽略。 好处：
  • 安全隔离：为不受信任的 Agent 限制工具
  • 资源控制：沙盒特定 Agent 同时保持其他在主机上
  • 灵活策略：每个 Agent 的不同权限
注意：tools.elevated 是全局的且基于发送者；它不是每个 Agent 可配置的。 如果你需要每个 Agent 的边界，使用 agents.list[].tools 拒绝 exec。 对于群组定位，使用 agents.list[].groupChat.mentionPatterns，以便 @提及干净地映射到预期的 Agent。 参见 多 Agent 沙盒和工具 以获取详细示例。