跳转至

多智能体路由

在一个 Gateway 进程中运行多个 隔离的 agent,每个 agent 都有自己的工作区、状态目录(agentDir)以及基于 SQLite 的会话历史,还可以配置多个渠道账户(例如两个 WhatsApp 号码)。入站消息通过 bindings 路由到正确的 agent。

agent 是完整的 per-persona 作用域:工作区文件、认证 profile、模型注册表和会话存储。binding 将渠道账户(一个 Slack 工作区、一个 WhatsApp 号码等)映射到其中一个 agent。

如需查看包含账户和对话示例的专项设置指南,请参阅 Agent bindings。

什么是单个 agent

每个 agent 都有自己的:

  • 工作区:文件、AGENTS.md/SOUL.md/USER.md、本地笔记、persona 规则。
  • 状态目录(agentDir):认证 profile、模型注册表、按 agent 的配置。
  • 会话存储:<agentDir>/openclaw-agent.sqlite 中的聊天历史和路由状态。

认证 profile 按 agent 独立,从 <agentDir>/openclaw-agent.sqlite 读取。默认布局下,该路径解析为:

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

Note

sessions_history 是更安全的跨会话召回路径:它返回有界且经过脱敏的视图,而不是原始转录转储。它会去除思考块签名、工具结果负载详情、<relevant-memories> 脚手架、工具调用 XML 标签(<tool_call>、<function_call> 及其复数/降级形式)以及 MiniMax 工具调用 XML,然后按字节大小截断并限制输出。

Warning

切勿在多个 agent 之间复用 agentDir — 这会导致认证/会话状态冲突。当次级 agent 的本地 OAuth 凭据过期或其刷新失败时,OpenClaw 会读取到同一 profile id 的认证继承所有者的凭据,并采用其中最新的 token,而不会将刷新 token 复制到次级 agent 的存储中。如果你想要完全独立的 OAuth 账户,请从该 agent 登录。如果手动复制凭据,请只复制可移植的静态 api_key 或 token profile — OAuth 刷新材料默认不可移植(copyToAgents 可以显式选择某个 profile 纳入)。

技能从每个 agent 的工作区以及共享根目录(例如 ~/.openclaw/skills)加载,然后按生效的 agent 技能允许列表进行过滤。使用 agents.defaults.skills 作为共享基线,使用 agents.entries.*.skills 进行按 agent 的替换(显式条目会替换默认值,而不会合并)。请参阅 技能:按 agent 与共享 和 技能:agent 允许列表。

插件拥有的存储遵循该插件的配置;添加第二个 agent 不会自动拆分所有全局插件存储。例如,当 persona 不能共享编译后的 wiki 知识时,请配置 Memory Wiki 按 agent 的 vault。

Note

工作区说明:每个 agent 的工作区是默认 cwd,而不是硬沙箱。相对路径在工作区内解析,但绝对路径可以到达主机上的其他位置,除非启用了沙箱。请参阅 沙箱。

路径

项目 默认值 覆盖配置
配置 ~/.openclaw/openclaw.json OPENCLAW_CONFIG_PATH
状态目录 ~/.openclaw OPENCLAW_STATE_DIR
默认 agent 的工作区 <stateDir>/workspace(命名 profile 为 ~/.openclaw-<profile>/workspace) agents.entries.*.workspace,然后是 agents.defaults.workspace,或 OPENCLAW_WORKSPACE_DIR
其他 agent 的工作区 <stateDir>/workspace-<agentId>(或当 agents.defaults.workspace 已设置时为 <agents.defaults.workspace>/<agentId>) agents.entries.*.workspace
Agent 目录 ~/.openclaw/agents/<agentId>/agent agents.entries.*.agentDir
会话与转录 <agentDir>/openclaw-agent.sqlite agents.entries.*.agentDir
旧版/归档会话产物 ~/.openclaw/agents/<agentId>/sessions —

单 agent 模式(默认)

如果你不进行任何配置,OpenClaw 会运行一个 agent:

  • agentId 默认为 main。
  • 主会话键是 agent:main:main。
  • 工作区默认为 <stateDir>/workspace(默认安装为 ~/.openclaw/workspace,命名 profile 为 ~/.openclaw-<profile>/workspace)。
  • 状态默认为 ~/.openclaw/agents/main/agent。

Agent 辅助工具

添加一个新的隔离 agent:

openclaw agents add work

可用标志:--role <role>、--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>(可重复)、--non-interactive(除非提供了 role,否则需要 --workspace)。

添加 bindings 来路由入站消息(向导会帮你完成这一步),然后验证:

openclaw agents list --bindings

在 Control UI 中,/agents 下的 Agents 显示成员列表、当前工作状态和最近的聊天预览,Open chat 可打开每个 agent 的主会话。使用 Manage agents 在 /settings/agents 配置成员列表。

Settings → Agents 在 Gateway 发布新目录时会更新模型选项。刷新选项会保留您已选择的模型、回退模型和身份草稿。如果读取失败,编辑器会显示错误并保留之前的选项,直到后续更新成功。模型和回退模型的编辑保持正常的自动保存行为。

代理来源

OpenClaw 会记录每个已配置代理的创建方式:operator 用于 CLI、引导流程和 Gateway 请求;agent 用于系统代理请求创建的场景;claw 用于 Claw 安装添加的场景。代理创建的条目还会保留请求代理的 id。已配置的代理可以通过其 openclaw 工具请求 OpenClaw 创建另一个代理。系统代理会记录所输入的操作、向操作员显示请求代理的 id,并且仅在操作员批准后才创建代理。使用以下命令查看当前的创建层级:

openclaw agents list --tree

已删除的创建者仍保留为历史来源。如果创建者已不在配置名单中,其子节点将出现在树的根部。

团队预设

通过书面角色契约和定向委派创建一个小型团队:

openclaw agents team create --non-interactive
openclaw agent --agent coordinator --message "Research the options and draft a recommendation."

该预设会创建一个参谋长(coordinator)、研究员、写手和审阅者,每个角色都有自己的工作区和完整的身份。参谋长仍然是人类的联络人:它发现匹配的专家、分配有边界的工作、检查他们的产物,并汇报连贯的结果。专家将产物和证据返回给协调者,不再进一步委派。他们的运行程序存放在 AGENTS.md 中,因此也适用于不加载 SOUL.md 或 IDENTITY.md 的衍生会话。

捆绑的角色是 Claw 源,共享可移植的 CLAW.md 身份格式、SOUL.md 主体以及声明的工作区文件。agents add --role <role> 会加载其中一个源。启用实验性 Claws 界面后,从源代码检出中的等效源路径为 openclaw claws add docs/reference/templates/roles/<role>;请遵循 Claw 预览和同意流程。

您也可以从 Control UI 创建参谋长或完整团队:在侧边栏或 Agents 首页选择 New agent,然后在管理聊天中选择角色或小团队推荐。创建过程使用相同的角色模板,并等待您的批准。

相关的每代理委派片段如下:

```json5 validate=false { agents: { entries: { coordinator: { subagents: { allowAgents: ["researcher", "writer", "reviewer"], delegationMode: "prefer", }, }, researcher: { subagents: { allowAgents: [] } }, writer: { subagents: { allowAgents: [] } }, reviewer: { subagents: { allowAgents: [] } }, }, }, }

`"prefer"` 引导协调者委派合适的工作;这是提示引导,而非调度器。`allowAgents` 控制显式的生成目标。该预设保持 `agents.defaults.subagents` 和 `tools.*` 不变,因此现有的工具可用性和访问策略仍然生效。角色指令要求在进行外部发送、发布、购买、删除或生产变更之前获得人工批准。这些委派设置仍然作为配置中的团队接线存在。独立的 Claw 配置文件支持落地后,角色 Claws 将包含这些设置。

协调者是一个显式目标。团队创建仅在 `agents.defaults.systemAgent.agentId` 的所有者未设置时才将其设置为协调者;现有所有者会被保留并报告。在显式舰队中,这也为支持默认代理选择的操作指定了默认值。显式目标和[路由绑定](agent-bindings.md)具有更高优先级。

使用 `--prefix <p>` 为所有团队 id 添加命名空间,使用 `--coordinator <id>` 重命名协调者,使用 `--workspace-root <dir>` 为各个独立工作区选择父目录。所有 id 在创建前都会进行冲突检查。有关标志和示例,请参阅 [`agents team create`](../cli/agents.md#agents-team-create),或在[引导流程](../start/wizard.md#choose-one-agent-or-a-team)中使用团队选项。

## 快速开始 {#quick-start}

**1. 创建每个代理的工作区**

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

每个代理都有自己的工作区,包含 SOUL.md、AGENTS.md 和可选的 USER.md,以及专用的 agentDir 和会话存储。默认情况下,这些代理文件位于 ~/.openclaw/agents/<agentId> 下。

2. 创建频道账户

在您偏好的频道上为每个代理创建一个账户:

  • Discord:每个代理一个机器人,启用 Message Content Intent,复制每个令牌。
  • Telegram:通过 BotFather 为每个代理创建一个机器人,复制每个令牌。
  • WhatsApp:每个账户关联一个电话号码。
openclaw channels login --channel whatsapp --account work

参见频道指南:Discord、Telegram、WhatsApp。

3. 添加代理、账户和绑定

在 agents.entries 下添加代理,在 channels.<channel>.accounts 下添加频道账户,并通过 bindings 连接它们(示例见下文)。

4. 重启并验证

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

多代理、多角色

每个已配置的 agentId 都是核心代理状态的独立角色边界:

  • 每个频道使用不同的账户(按 accountId)。
  • 不同的人格(按代理的 AGENTS.md/SOUL.md)。
  • 独立的认证和会话,跨代理会话访问默认开启,由 tools.agentToAgent 管理。使用 tools.sessions.visibility 收窄会话可见性,使用 tools.agentToAgent.allow 限制代理对,或设置 tools.agentToAgent.enabled: false 以阻止普通的跨代理访问。请求者拥有的原生子代理和 ACP 子会话在 tree 或 all 可见性下仍然可访问;如需严格隔离,请使用独立的 Gateway。

这让多人可以共享同一个 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 跨智能体搜索路径已在 v2026.8.1 中与其余 QMD 后端一同移除。内置记忆不会搜索其他智能体的会话记录语料;每个智能体只搜索自身配置的记忆和符合条件的同智能体会话来源。当同一参考资料需要被多个智能体索引时,请将有意共享的 Markdown 放入显式共享的 memory.search.extraPaths 目录。完整的升级路径请参阅 从 QMD 迁移。

一个 WhatsApp 号码、多人使用(DM 分流)

通过在一个 WhatsApp 账号上匹配发送方 E.164(+15551234567)与 peer.kind: "direct",可将不同的 WhatsApp 私信路由到不同的智能体。回复仍然来自同一个 WhatsApp 号码——不存在按智能体区分的发送方身份。

Note

默认情况下,私聊会归并到智能体的主会话密钥中,因此真正的隔离需要一个人一个智能体。

私信访问控制(配对/白名单)是按 WhatsApp 账号全局生效的,而不是按智能体。对于共享群组,请将该群组绑定到某个智能体,或使用 广播群组。

{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "alex" },
      heartbeat: { agentId: "alex" },
      systemAgent: { agentId: "alex" },
    },
    entries: {
      alex: { workspace: "~/.openclaw/workspace-alex" },
      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" } },
    },
    { agentId: "alex", match: { channel: "whatsapp", accountId: "*" } },
  ],
  talk: { agentId: "alex" },
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

路由规则

绑定是确定性的,且最具体的匹配优先。完整的层级顺序(精确对端、父级对端、对端通配符、公会+角色、公会、团队、账号、频道、回退属主)请参阅 频道路由。这里有几条规则值得特别说明:

  • 如果同一层级内有多个绑定匹配,则配置顺序中靠前的绑定生效。
  • 当配置了多个智能体且没有显式属主时,未匹配任何绑定的消息不会被交给任意一个最先列出的智能体。配置的 agents.defaults.systemAgent.agentId、保留的传统属主或调用方提供的属主仍会接住这些未绑定的流量;只有当没有任何绑定匹配且不存在此类回退属主时,消息才会留在未分发状态。会保留入站消息以便重试的频道(例如 Telegram)可能会在某个绑定为该账号提供属主之后稍后投递该消息,但并不能保证一定投递。可重试消息一旦同时达到尝试次数上限和最小保留时间(默认 24 小时),就会进入死信状态;像 Telegram 这样的频道可以在启动时拒绝无属主账号,因此重新绑定只有在消息仍在排队且账号正在运行时才会投递该消息。
  • 如果绑定设置了多个匹配字段(例如 peer + guildId),则所有指定字段都必须匹配(AND 语义)。
  • 省略 accountId 的绑定只匹配默认账号,而不是所有账号。使用 accountId: "*" 作为频道级回退,或使用 accountId: "<name>" 指定单个账号。使用显式账号 ID 再次添加同一个绑定时,会升级现有的仅频道绑定,而不会重复添加。

对于现有的多智能体配置,openclaw doctor --fix 会将传统隐式默认路由显式化为频道级绑定,并在需要时添加显式的心跳、Custodian、Talk 和认证继承属主。它还会从单智能体配置中移除已退役的默认标记;唯一的智能体仍会隐式解析。运行时准入需要规范花名册,因此在使用传统标记直接替换二进制并启动之前,请先运行 Doctor。正常更新流程会运行候选 Doctor。

对于在主配置文件中直接定义、且没有传统 default: true 标记的多智能体花名册,Doctor 会为带键的 agents.entries 和较旧的 agents.list 花名册添加 agents.ownership: "explicit",包括在 --fix --non-interactive 情况下也一样。现有绑定和各接入面的属主保持不变。最后已知良好(last-known-good)恢复会在校验并恢复直接编写、无标记的花名册之前,应用相同的属主标记。Doctor 绝不会把较窄的会话绑定提升为账号级属主,也不会从其他账号或频道借用属主,不会在冲突的属主之间做选择,也不会指派其他无属主的接入面。

在传统 agents.list 迁移期间,未绑定的账号会保留其历史的首个智能体回退作为显式账号绑定,即使较窄的会话路由指定了其他智能体时也是如此。Doctor 在写入属主标记的同时记录该绑定。更新通道迁移和手动运行 Doctor 都需要原始花名册;如果花名册不可用,Doctor 会报告该原因并保持绑定不变。属主仍无法解析的账号会报告所需的绑定,并保持阻止状态而不会自动重启;其他账号和 Gateway 继续正常服务。

当迁移没有默认标记的旧版 agents.list 名册时,Doctor 还会将第一个代理继承的工作区固定到 agents.entries.<id>.workspace。其自定义指令和历史 memory/ 笔记仍保留在原始目录中。显式工作区仍为权威来源。如果之前的升级已经留下两个被编辑过的工作区,请选择预期的每个代理的工作区,并从备份中核对它们的内容;Doctor 不会合并目录。

多个账户 / 电话号码

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

设置 channels.<channel>.defaultAccount 以选择在省略 accountId 时使用的账户。未设置时,OpenClaw 会回退到 default(如果存在),否则使用第一个已配置的账户 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,并可选地通过 guild/team id。
  • 直接聊天默认折叠为 agent:<agentId>:main(每个代理的主会话)。

平台示例

这些示例显式选择渠道和服务的所有者。渠道绑定负责路由消息;systemAgent、heartbeat 和 talk.agentId 选择各自的所有者。当之前的所有者不是 main 时,authInheritance.agentId 会独立于渠道路由保留共享凭据源。

每个代理的 Discord 机器人

每个 Discord 机器人账户映射到一个唯一的 accountId。将每个账户绑定到一个代理,并为每个机器人保留允许列表。

{
  agents: {
    ownership: "explicit",
    defaults: {
      heartbeat: { agentId: "main" },
      systemAgent: { agentId: "main" },
    },
    entries: {
      main: { workspace: "~/.openclaw/workspace-main" },
      coding: { workspace: "~/.openclaw/workspace-coding" },
    },
  },
  bindings: [
    { agentId: "main", match: { channel: "discord", accountId: "default" } },
    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },
    { agentId: "main", match: { channel: "discord", accountId: "*" } },
  ],
  talk: { agentId: "main" },
  channels: {
    discord: {
      groupPolicy: "allowlist",
      accounts: {
        default: {
          token: "DISCORD_BOT_TOKEN_MAIN",
          guilds: {
            "123456789012345678": {
              channels: {
                "222222222222222222": { enabled: true, requireMention: false },
              },
            },
          },
        },
        coding: {
          token: "DISCORD_BOT_TOKEN_CODING",
          guilds: {
            "123456789012345678": {
              channels: {
                "333333333333333333": { enabled: true, requireMention: false },
              },
            },
          },
        },
      },
    },
  },
}
  • 将每个机器人邀请到服务器并启用 Message Content Intent。
  • Token 位于 channels.discord.accounts.<id>.token(默认账户可以使用 DISCORD_BOT_TOKEN)。
每个代理的 Telegram 机器人
{
  agents: {
    ownership: "explicit",
    defaults: {
      heartbeat: { agentId: "main" },
      systemAgent: { agentId: "main" },
    },
    entries: {
      main: { workspace: "~/.openclaw/workspace-main" },
      alerts: { workspace: "~/.openclaw/workspace-alerts" },
    },
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "default" } },
    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
    { agentId: "main", match: { channel: "telegram", accountId: "*" } },
  ],
  talk: { agentId: "main" },
  channels: {
    telegram: {
      accounts: {
        default: {
          botToken: "123456:ABC...",
          dmPolicy: "pairing",
        },
        alerts: {
          botToken: "987654:XYZ...",
          dmPolicy: "allowlist",
          allowFrom: ["tg:123456789"],
        },
      },
    },
  },
}
  • 使用 BotFather 为每个代理创建一个机器人,并复制每个 token。
  • Token 位于 channels.telegram.accounts.<id>.botToken(默认账户可以使用 TELEGRAM_BOT_TOKEN)。
  • 对于同一个 Telegram 群组中的多个机器人,邀请每个机器人并 @ 应该回复的那个。
  • 为每个群组机器人禁用 BotFather 隐私模式(/setprivacy -> Disable),然后移除并重新添加机器人,以便 Telegram 应用该设置。
  • 使用 channels.telegram.groups 允许群组,或仅在受信任的群组部署中使用 groupPolicy: "open"。
  • 将发送者用户 ID 放入 groupAllowFrom。群组 ID 和超级群组 ID 应放在 channels.telegram.groups 中,而不是 groupAllowFrom。
  • 按 accountId 绑定,以便每个机器人路由到其自己的代理。
每个代理的 WhatsApp 号码

在启动网关之前关联每个账户:

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

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

{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "home" },
      heartbeat: { agentId: "home" },
      systemAgent: { agentId: "home" },
    },
    entries: {
      home: {
        name: "Home",
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      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" },
      },
    },
    { agentId: "home", match: { channel: "whatsapp", accountId: "*" } },
  ],
  talk: { agentId: "home" },

  // On by default. Omitted/empty `allow` permits every agent pair;
  // list requester and target ids to restrict access, or set enabled: false to turn it off.
  tools: {
    agentToAgent: {
      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 路由到 Opus 代理。

{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "chat" },
      heartbeat: { agentId: "chat" },
      systemAgent: { agentId: "chat" },
    },
    entries: {
      chat: {
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      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: "*" } },
  ],
  talk: { agentId: "chat" },
}

这些示例使用 accountId: "*",以便日后添加账户时绑定仍然有效。若要将单个私聊/群组路由到 Opus,同时让其余部分保持在 chat 上,请为该对端添加一个 match.peer 绑定——对端匹配始终优先于渠道级规则。

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

{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "chat" },
      heartbeat: { agentId: "chat" },
      systemAgent: { agentId: "chat" },
    },
    entries: {
      chat: {
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      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: "*" } },
  ],
  talk: { agentId: "chat" },
}

对端绑定始终优先,因此请将其放在渠道级规则之上。

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

{
  agents: {
    entries: {
      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.entries.*.groupChat.mentionPatterns,并为此渠道保持启用群组允许列表。

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

每个代理都可以拥有自己的沙箱和工具限制:

{
  agents: {
    ownership: "explicit",
    defaults: {
      authInheritance: { agentId: "personal" },
      heartbeat: { agentId: "personal" },
      systemAgent: { agentId: "personal" },
    },
    entries: {
      personal: {
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off", // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      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
        },
      },
    },
  },
  talk: { agentId: "personal" },
}

Note

setupCommand 位于 sandbox.docker 下,并在容器创建时运行一次。当解析后的作用域为 "shared" 时,每个代理的 sandbox.docker.* 覆盖会被忽略。

这将为你提供:

  • 安全隔离:限制不受信任代理的工具。
  • 资源控制:对特定代理进行沙箱隔离,同时让其他代理保留在主机上。
  • 灵活策略:每个代理拥有不同的权限。

Note

tools.elevated 同时具有全局门控(tools.elevated.enabled/allowFrom)和每个代理的门控(agents.entries.*.tools.elevated.enabled/allowFrom)。每个代理的门控只能进一步限制全局门控——两者都必须允许某个发送者,提权命令才能运行。对于群组定向,请使用 agents.entries.*.groupChat.mentionPatterns,以便 @提及 能准确映射到目标代理。

有关详细示例,请参阅 多代理沙箱和工具。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw