[OpenClaw 文档]代理--多代理

2026年 5月 16日 OpenClaw SE_You

本文档汇总了 OpenClaw 官方文档站代理 > 多代理 子模块下的全部 2 篇内容，源自 docs.openclaw.ai/zh-CN。

📑 本文目录（2 篇）

📄 多智能体路由

原文：https://docs.openclaw.ai/zh-CN/concepts/multi-agent

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

这里的智能体是完整的按人格划分的作用域：工作区文件、凭证配置、模型注册表和会话存储。agentDir 是磁盘上的状态目录，用于在 ~/.openclaw/agents/<agentId>/ 保存这个按智能体划分的配置。绑定会把一个渠道账号（例如 Slack 工作区或 WhatsApp 号码）映射到其中一个智能体。

什么是“一个智能体”？

智能体是一个完整划定作用域的大脑，拥有自己的：

工作区（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格规则）。
状态目录（agentDir），用于凭证配置、模型注册表和按智能体划分的配置。
会话存储（聊天历史 + 路由状态），位于 ~/.openclaw/agents/<agentId>/sessions 下。

凭证配置是按智能体划分的。每个智能体都会从自己的以下位置读取：

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

sessions_history 在这里也是更安全的跨会话回忆路径：它返回有边界、经过清理的视图，而不是原始转录全文转储。助手回忆会先剥离思考标签、<relevant-memories> 脚手架、纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 和被截断的工具调用块）、降级后的工具调用脚手架、泄露的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML，然后再进行遮蔽/截断。

不要在多个智能体之间复用 agentDir（这会导致凭证/会话冲突）。当智能体没有本地配置时，可以透传读取默认/主智能体的凭证配置，但 OpenClaw 不会把 OAuth 刷新令牌克隆到次级智能体存储中。如果你想使用独立的 OAuth 账号，请从该智能体登录；如果你手动复制凭据，只复制可移植的静态 api_key 或 token 配置。

Skills 会从每个智能体工作区以及 ~/.openclaw/skills 等共享根目录加载，然后在配置了有效的智能体技能允许列表时进行过滤。使用 agents.defaults.skills 设置共享基线，使用 agents.list[].skills 设置按智能体替换。参见 Skills：按智能体 vs 共享和 Skills：智能体技能允许列表。

Gateway 网关可以托管一个智能体（默认）或多个智能体并排运行。

工作区注意事项：每个智能体的工作区是默认 cwd，不是硬性沙箱。相对路径会在工作区内解析，但除非启用沙箱隔离，否则绝对路径可以访问主机上的其他位置。参见沙箱隔离。

路径（速查）

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

智能体助手

使用智能体向导添加新的隔离智能体：

openclaw agents add work

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

使用以下命令验证：

openclaw agents list --bindings

快速开始

使用向导，或手动创建工作区：

```bash
openclaw agents add coding
openclaw agents add social
```

每个智能体都会获得自己的工作区，其中包含 `SOUL.md`、`AGENTS.md` 和可选的 `USER.md`，并且在 `~/.openclaw/agents/<agentId>` 下拥有专用的 `agentDir` 和会话存储。

在你偏好的渠道上为每个智能体创建一个账号：

- Discord：每个智能体一个机器人，启用 Message Content Intent，复制每个令牌。
- Telegram：通过 BotFather 为每个智能体创建一个机器人，复制每个令牌。
- WhatsApp：为每个账号关联一个电话号码。

```bash
openclaw channels login --channel whatsapp --account work
```

参见渠道指南：[Discord](/zh-CN/channels/discord)、[Telegram](/zh-CN/channels/telegram)、[WhatsApp](/zh-CN/channels/whatsapp)。

在 agents.list 下添加智能体，在 channels.<channel>.accounts 下添加渠道账号，并使用 bindings 将它们连接起来（示例如下）。

bash openclaw gateway restart openclaw agents list --bindings openclaw channels status --probe

多个智能体 = 多个人、多个个性

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

不同的电话号码/账号（按渠道 accountId）。
不同的个性（按智能体划分的工作区文件，例如 AGENTS.md 和 SOUL.md）。
独立的凭证 + 会话（除非明确启用，否则不会串话）。

这允许多人共享一台 Gateway 网关服务器，同时让他们的 AI“大脑”和数据保持隔离。

跨智能体 QMD 记忆搜索

如果一个智能体需要搜索另一个智能体的 QMD 会话转录，请在 agents.list[].memorySearch.qmd.extraCollections 下添加额外集合。只有当每个智能体都应该继承相同的共享转录集合时，才使用 agents.defaults.memorySearch.qmd.extraCollections。

{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

额外集合路径可以在智能体之间共享，但当路径位于智能体工作区外部时，集合名称会保持显式。工作区内的路径仍然按智能体划定作用域，因此每个智能体都会保留自己的转录搜索集。

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

你可以在保持一个 WhatsApp 账号的同时，把不同的 WhatsApp 私信路由到不同智能体。通过 peer.kind: "direct" 按发送者 E.164（如 +15551234567）匹配。回复仍然来自同一个 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 账号全局的（配对/允许列表），不是按智能体划分。
对于共享群组，请把群组绑定到一个智能体，或使用广播群组。

路由规则（消息如何选择智能体）

绑定是确定性的，并且最具体者优先：

精确私信/群组/渠道 ID。

线程继承。

Discord 角色路由。

Discord。

Slack。

按账号回退。

accountId: "*"。

回退到 agents.list[].default，否则使用列表中的第一项，默认值：main。

- 如果多个绑定在同一层级匹配，配置顺序中的第一个胜出。
- 如果一个绑定设置了多个匹配字段（例如 peer + guildId），所有指定字段都必须满足（AND 语义）。

- 省略 accountId 的绑定只匹配默认账号。
- 使用 accountId: "*" 作为跨所有账号的渠道级回退。
- 如果你之后为同一个智能体添加带显式账号 ID 的相同绑定，OpenClaw 会把现有的仅渠道绑定升级为账号作用域，而不是复制一个绑定。

多个账号/电话号码

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

如果你希望在省略 accountId 时使用渠道级默认账号，请设置 channels.<channel>.defaultAccount（可选）。未设置时，OpenClaw 会回退到 default（如果存在），否则使用按排序后的第一个已配置账号 ID。

支持这种模式的常见渠道包括：

whatsapp、telegram、discord、slack、signal、imessage
irc、line、googlechat、mattermost、matrix、nextcloud-talk
zalo、zalouser、nostr、feishu

概念

agentId：一个“大脑”（工作区、按智能体划分的凭证、按智能体划分的会话存储）。
accountId：一个渠道账号实例（例如 WhatsApp 账号 "personal" 与 "biz"）。
binding：按 (channel, accountId, peer) 以及可选的 guild/team ID，将入站消息路由到某个 agentId。
直接聊天会折叠到 agent:<agentId>:<mainKey>（按智能体划分的“main”；session.mainKey）。

平台示例

每个 Discord 机器人账号都映射到唯一的 accountId。将每个账号绑定到一个智能体，并为每个机器人保留允许列表。

```json5
{
  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 },
              },
            },
          },
        },
      },
    },
  },
}
```

- 邀请每个 bot 加入 guild，并启用 Message Content Intent。
- token 存放在 `channels.discord.accounts.<id>.token` 中（默认账户可以使用 `DISCORD_BOT_TOKEN`）。

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

- 使用 BotFather 为每个 agent 创建一个 bot，并复制每个 token。
- token 存放在 `channels.telegram.accounts.<id>.botToken` 中（默认账户可以使用 `TELEGRAM_BOT_TOKEN`）。

在启动 Gateway 网关前先关联每个账户：

```bash
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
```

`~/.openclaw/openclaw.json` (JSON5):

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

常见模式

按 channel 拆分：将 WhatsApp 路由到快速的日常 agent，将 Telegram 路由到 Opus agent。

```json5
{
  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" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}
```

说明：

- 如果一个 channel 有多个账户，请向 binding 添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 若要将单个私信/群组路由到 Opus，同时让其余内容继续留在 chat 上，请为该 peer 添加 `match.peer` binding；peer 匹配始终优先于 channel 范围的规则。

让 WhatsApp 继续使用快速 agent，但将一个私信路由到 Opus：

```json5
{
  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", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}
```

peer binding 始终优先，因此请把它们放在 channel 范围规则的上方。

将一个专用家庭 agent 绑定到单个 WhatsApp 群组，并配置 mention 门控和更严格的工具策略：

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

说明：

- 工具允许/拒绝列表是**工具**，不是 Skills。如果一个 skill 需要运行二进制文件，请确保允许 `exec`，且该二进制文件存在于沙箱中。
- 对于更严格的门控，请设置 `agents.list[].groupChat.mentionPatterns`，并让该 channel 的群组允许列表保持启用。

每个 agent 的沙箱和工具配置

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

{
  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 下，并在容器创建时运行一次。当解析后的 scope 为 "shared" 时，会忽略每个 agent 的 sandbox.docker.* 覆盖项。

优势：

安全隔离：限制不受信任的 agent 可用的工具。
资源控制：对特定 agent 使用沙箱，同时让其他 agent 保持在宿主机上运行。
灵活策略：为每个 agent 设置不同权限。

tools.elevated 是全局的，并且基于发送者；它不能按 agent 配置。如果你需要每个 agent 的边界，请使用 agents.list[].tools 来拒绝 exec。对于群组定向，请使用 agents.list[].groupChat.mentionPatterns，这样 @mentions 就能清晰映射到目标 agent。

请参阅多 Agent 沙盒和工具了解详细示例。

📄 在线状态

原文：https://docs.openclaw.ai/zh-CN/concepts/presence

OpenClaw “在线状态”是一个轻量级、尽力而为的视图，用于展示：

Gateway 网关本身，以及
连接到 Gateway 网关的客户端（mac 应用、WebChat、CLI 等）

在线状态主要用于渲染 macOS 应用的实例标签页，并提供快速的运维可见性。

在线状态字段（显示的内容）

在线状态条目是结构化对象，包含如下字段：

instanceId（可选，但强烈建议）：稳定的客户端身份（通常为 connect.client.instanceId）
host：便于人工识别的主机名
ip：尽力获取的 IP 地址
version：客户端版本字符串
deviceFamily / modelIdentifier：硬件提示信息
mode：ui、webchat、cli、backend、probe、test、node、……
lastInputSeconds：“距离上次用户输入的秒数”（如果已知）
reason：self、connect、node-connected、periodic、……
ts：最后更新时间戳（自纪元以来的毫秒数）

生产者（在线状态来自哪里）

在线状态条目由多个来源生成并合并。

1) Gateway 网关自身条目

Gateway 网关始终会在启动时填充一个“自身”条目，因此即使尚未有任何客户端连接，UI 也能显示 Gateway 网关主机。

2) WebSocket 连接

每个 WS 客户端都以一个 connect 请求开始。握手成功后，Gateway 网关会为该连接插入或更新一个在线状态条目。

为什么一次性 CLI 命令不会显示

CLI 经常为短暂的一次性命令建立连接。为了避免刷屏实例列表，client.mode === "cli" 不会转换为在线状态条目。

3) `system-event` 信标

客户端可以通过 system-event 方法发送更丰富的周期性信标。mac 应用使用它来报告主机名、IP 和 lastInputSeconds。

4) 节点连接（角色：node）

当节点通过 Gateway 网关 WebSocket 使用 role: node 连接时，Gateway 网关会为该节点插入或更新一个在线状态条目（流程与其他 WS 客户端相同）。

合并 + 去重规则（为什么 `instanceId` 很重要）

在线状态条目存储在一个单一的内存映射中：

条目按在线状态键作为键。
最佳键是一个稳定的 instanceId（来自 connect.client.instanceId），它可以在重启后保持不变。
键不区分大小写。

如果客户端在没有稳定 instanceId 的情况下重新连接，它可能会显示为重复行。

TTL 和有界大小

在线状态是有意设计为短暂的：

TTL：超过 5 分钟的条目会被清理
最大条目数：200（最旧的条目先丢弃）

这会让列表保持新鲜，并避免无界内存增长。

远程/隧道注意事项（环回 IP）

当客户端通过 SSH 隧道 / 本地端口转发连接时，Gateway 网关可能会看到远程地址为 127.0.0.1。为了避免覆盖客户端报告的有效 IP，环回远程地址会被忽略。

消费者

macOS 实例标签页

macOS 应用会渲染 system-presence 的输出，并根据最后一次更新的时间应用一个小型状态指示器（活跃/空闲/过期）。

调试提示

要查看原始列表，请对 Gateway 网关调用 system-presence。
如果看到重复项：
确认客户端在握手中发送稳定的 client.instanceId
确认周期性信标使用相同的 instanceId
检查连接派生的条目是否缺少 instanceId（此时重复项是预期行为）

[OpenClaw 文档]代理--多代理

📄 多智能体路由

什么是“一个智能体”？

路径（速查）

单智能体模式（默认）

智能体助手

快速开始

多个智能体 = 多个人、多个个性

跨智能体 QMD 记忆搜索

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

路由规则（消息如何选择智能体）

多个账号/电话号码

概念

平台示例

常见模式

每个 agent 的沙箱和工具配置

相关内容

📄 在线状态

在线状态字段（显示的内容）

生产者（在线状态来自哪里）

1) Gateway 网关自身条目

2) WebSocket 连接

为什么一次性 CLI 命令不会显示

3) `system-event` 信标

4) 节点连接（角色：node）

合并 + 去重规则（为什么 `instanceId` 很重要）

TTL 和有界大小

远程/隧道注意事项（环回 IP）

消费者

macOS 实例标签页

调试提示

相关内容

[OpenClaw 文档]代理--多代理

📄 多智能体路由

什么是“一个智能体”？

路径（速查）

单智能体模式（默认）

智能体助手

快速开始

多个智能体 = 多个人、多个个性

跨智能体 QMD 记忆搜索

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

路由规则（消息如何选择智能体）

多个账号/电话号码

概念

平台示例

常见模式

每个 agent 的沙箱和工具配置

相关内容

📄 在线状态

在线状态字段（显示的内容）

生产者（在线状态来自哪里）

1) Gateway 网关自身条目

2) WebSocket 连接

为什么一次性 CLI 命令不会显示

3) system-event 信标

4) 节点连接（角色：node）

合并 + 去重规则（为什么 instanceId 很重要）

TTL 和有界大小

远程/隧道注意事项（环回 IP）

消费者

macOS 实例标签页

调试提示

相关内容

3) `system-event` 信标

合并 + 去重规则（为什么 `instanceId` 很重要）