多智能体路由

在一个 Gateway 网关进程中运行多个相互_隔离_的智能体，每个智能体都有自己的工作区、状态目录（agentDir）和由 SQLite 支持的会话历史记录，以及多个渠道账户（例如两个 WhatsApp 号码）。入站消息通过绑定路由到正确的智能体。

智能体是每个人格角色的完整作用域：工作区文件、身份验证配置文件、模型注册表和会话存储。绑定将渠道账户（Slack 工作区、WhatsApp 号码等）映射到其中一个智能体。

什么是一个智能体

每个智能体都有自己的：

• 工作区：文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格角色规则。
• 状态目录（agentDir）：身份验证配置文件、模型注册表、每智能体配置。
• 会话存储：~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 中的聊天历史记录和路由状态。

身份验证配置文件按智能体隔离，从以下位置读取：

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

Skills 从每个智能体工作区以及 ~/.openclaw/skills 等共享根目录加载，然后根据智能体的有效技能允许列表进行筛选。使用 agents.defaults.skills 设置共享基线，使用 agents.entries.*.skills 设置每智能体替代项（显式条目会替代默认值，而不是与其合并）。请参阅 Skills：每智能体与共享 Skills和 Skills：智能体允许列表。

插件拥有的存储遵循该插件的配置；添加第二个智能体 不会自动拆分所有全局插件存储。例如，当人格角色不能共享 已编译的 wiki 知识时，请配置 Memory Wiki 每智能体保管库。

路径

单智能体模式（默认）

如果未进行任何配置，OpenClaw 会运行一个智能体：

• agentId 默认为 main。
• 会话键为 agent:main:<mainKey>（默认 mainKey 为 main）。
• 工作区默认为 ~/.openclaw/workspace（当 OPENCLAW_PROFILE 设置为 default 以外的值时，为 workspace-<profile>）。
• 状态默认为 ~/.openclaw/agents/main/agent。

智能体辅助工具

添加新的隔离智能体：

openclaw agents add work

标志：--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>（可重复使用）、--non-interactive（需要 --workspace）。

添加 bindings 以路由入站消息（向导会询问是否代为执行），然后验证：

openclaw agents list --bindings

快速开始

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

多个智能体、多个角色人格

每个已配置的 agentId 都是核心智能体状态的独立人格角色边界：

• 每个渠道使用不同账户（按 accountId）。
• 不同人格（通过每智能体 AGENTS.md/SOUL.md）。
• 身份验证和会话彼此分离，仅通过显式功能或插件配置启用跨智能体访问。

这样，多个人就可以共享一个 Gateway 网关，同时保持核心智能体状态彼此分离。

每智能体 Memory Wiki 保管库

Memory Wiki 默认使用一个全局保管库。要使支持智能体的 已编译知识与营销智能体的知识分离，请将 plugins.entries.memory-wiki.config.vault.scope 设置为 agent：

{  plugins: {    entries: {      "memory-wiki": {        enabled: true,        config: {          vault: {            scope: "agent",            path: "~/.openclaw/wiki",          },        },      },    },  },}

配置的路径是父目录。OpenClaw 会追加规范化的 智能体 ID，从而生成 ~/.openclaw/wiki/support 和 ~/.openclaw/wiki/marketing 等路径。配置多个智能体时，智能体作用域的 CLI 和 Gateway 网关操作 需要显式指定智能体。有关桥接 筛选、迁移和信任边界的详情，请参阅 Memory Wiki 每智能体保管库。

跨智能体 QMD 记忆搜索

要允许一个智能体搜索另一个智能体的 QMD 会话对话记录，请在 agents.entries.*.memory.search.qmd.extraCollections 下添加额外集合。当所有智能体都应共享相同集合时，请使用 memory.search.qmd.extraCollections。

{  agents: {    defaults: {      workspace: "~/workspaces/main",    },    entries: {      main: {        workspace: "~/workspaces/main",        memory: {          search: {            qmd: {              extraCollections: [{ path: "notes" }], // 在工作区内解析 -> 名为 "notes-main" 的集合            },          },        },      },      family: { workspace: "~/workspaces/family" },    },  },  memory: {    backend: "qmd",    search: {      qmd: {        extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],      },    },    qmd: { includeDefaultMemory: false },  },}

额外集合路径可以在智能体之间共享，但当路径位于智能体工作区之外时，其 name 仍需显式指定。工作区内的路径仍按智能体划分作用域，因此每个智能体都保留自己的对话记录搜索集。

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

在一个 WhatsApp 账户上，通过使用 peer.kind: "direct" 匹配发送者 E.164（+15551234567），将不同的 WhatsApp 私信路由到不同的智能体。回复仍从同一个 WhatsApp 号码发出——不存在每智能体发送者身份。

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

私信访问控制（配对/允许列表）按 WhatsApp 账户全局生效，而不是按智能体生效。对于共享群组，请将群组绑定到一个智能体，或使用广播群组。

路由规则

绑定是确定性的，并以最具体的匹配为准。有关完整的层级顺序（精确对端、父对端、对端通配符、服务器 + 角色、服务器、团队、账户、渠道、默认智能体），请参阅渠道路由。这里有几项值得特别说明的规则：

• 如果同一层级内有多个绑定匹配，则配置顺序中的第一个绑定获胜。
• 如果绑定设置了多个匹配字段（例如 peer + guildId），则所有指定字段都必须匹配（AND 语义）。
• 省略 accountId 的绑定只匹配默认账户，而不是所有账户。使用 accountId: "*" 设置渠道范围的回退，或使用 accountId: "<name>" 指定一个账户。再次添加同一绑定并显式指定账户 ID，会升级现有的仅渠道绑定，而不是创建重复绑定。

多个账户/电话号码

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

设置 channels.<channel>.defaultAccount，以选择省略 accountId 时使用的账户。未设置时，如果存在 default，OpenClaw 将回退到该账户；否则使用配置的第一个账户 ID（排序后）。

支持多个账户的渠道：discord、feishu、googlechat、imessage、irc、line、mattermost、matrix、nextcloud-talk、nostr、signal、slack、telegram、whatsapp、zalo、zalouser。

概念

• agentId：一个“大脑”（工作区、每个智能体的身份验证、每个智能体的会话存储）。
• accountId：一个渠道账户实例（例如 WhatsApp 账户 personal 与 biz）。
• binding：根据 (channel, accountId, peer) 将入站消息路由到 agentId，并可选择使用服务器/团队 ID。
• 直接聊天会归并到 agent:<agentId>:<mainKey>（每个智能体的“主”会话；参见 session.mainKey）。

平台示例

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "coding", workspace: "~/.openclaw/workspace-coding" },    ],  },  bindings: [    { agentId: "main", match: { channel: "discord", accountId: "default" } },    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },  ],  channels: {    discord: {      groupPolicy: "allowlist",      accounts: {        default: {          token: "DISCORD_BOT_TOKEN_MAIN",          guilds: {            "123456789012345678": {              channels: {                "222222222222222222": { allow: true, requireMention: false },              },            },          },        },        coding: {          token: "DISCORD_BOT_TOKEN_CODING",          guilds: {            "123456789012345678": {              channels: {                "333333333333333333": { allow: true, requireMention: false },              },            },          },        },      },    },  },}

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },    ],  },  bindings: [    { agentId: "main", match: { channel: "telegram", accountId: "default" } },    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },  ],  channels: {    telegram: {      accounts: {        default: {          botToken: "123456:ABC...",          dmPolicy: "pairing",        },        alerts: {          botToken: "987654:XYZ...",          dmPolicy: "allowlist",          allowFrom: ["tg:123456789"],        },      },    },  },}

openclaw channels login --channel whatsapp --account personalopenclaw channels login --channel whatsapp --account biz

{  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" } },     // 可选的单个对端覆盖规则（示例：将特定群组发送给工作智能体）。    {      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: {          // 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // 可选覆盖。默认值：~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

常见模式

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

{  agents: {    list: [      {        id: "chat",        name: "Everyday",        workspace: "~/.openclaw/workspace-chat",        model: "anthropic/claude-sonnet-4-6",      },      {        id: "opus",        name: "Deep Work",        workspace: "~/.openclaw/workspace-opus",        model: "anthropic/claude-opus-4-6",      },    ],  },  bindings: [    {      agentId: "opus",      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

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

按智能体配置沙箱和工具

每个智能体都可以有自己的沙箱和工具限制：

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // 个人智能体不使用沙箱        },        // 无工具限制——所有工具均可用      },      {        id: "family",        workspace: "~/.openclaw/workspace-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"],    // 拒绝其他工具        },      },    ],  },}

这样可以实现：

• 安全隔离：限制不可信智能体可使用的工具。
• 资源控制：对特定智能体进行沙箱隔离，同时让其他智能体在主机上运行。
• 灵活策略：为不同智能体设置不同权限。

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

相关内容

• ACP 智能体 — 运行外部编码工具框架
• 渠道路由 — 消息如何路由到智能体
• 在线状态 — 智能体的在线状态和可用性
• 会话 — 会话隔离和路由
• 子智能体 — 启动后台智能体运行