多 Agent 协作：一个 Gateway 跑多个专家

OpenClaw 多agent 架构可以在一个 Gateway 进程里跑多个相互隔离的 agent：每个 agent 有自己的工作区、状态目录（agentDir）和基于 SQLite 的会话历史，还能同时挂多个渠道账号（比如两个 WhatsApp 号码）。入站消息靠 binding 路由到正确的 agent。

适用场景

• 你想要一个「工作 Claw」和一个「生活 Claw」，persona、记忆、凭据互不干扰。
• 你手里有多个同类渠道账号——两个 WhatsApp 号码、两个 Slack workspace——想各接一个专家。
• 团队共用一套部署，不同成员或业务线各配一个专属 agent。

先区分概念：本页讲的是按渠道账号路由的多 agent。仓库里另有 subagents 与 agent-send 工具文档，属于 agent 之间的另一种配合方式。

准备

• 读完场景实战：选择你的路线，确认多 agent 是你要的路线。
• 有一个已经跑起来的 Gateway——多 agent 不需要第二个进程。
• 想清楚分工：哪个渠道账号归哪个 agent，每个专家的 persona 规则写进各自的 AGENTS.md/SOUL.md。

跟我做：三步跑起多个专家

第 1 步：用 openclaw agents add 建多个专家 agent

为什么给每个专家单独建一个 agent？因为一个 agent 就是一个完整的 persona 作用域，自带三样东西：

• 工作区：文件、AGENTS.md/SOUL.md/USER.md、本地笔记、persona 规则。
• 状态目录 agentDir：auth profiles、模型注册表、每 agent 配置，默认在 ~/.openclaw/agents/<agentId>/agent。
• 会话库：聊天历史与路由状态，存于 <agentDir>/openclaw-agent.sqlite，默认布局下即 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。

给每个专家跑一次 agents add——示例建「生活 Claw」和「工作 Claw」：

openclaw agents add home
openclaw agents add work

常用旗标：--role <role>（套用角色模板）、--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>（可重复，创建时顺手把 binding 建好）；--non-interactive 需搭配 --workspace，除非指定了 --role。

你应该看到：每个 agent 得到自己的工作区（含 SOUL.md、AGENTS.md，可选 USER.md）、独立的 agentDir 和会话库，agent 文件默认落在 ~/.openclaw/agents/<agentId> 下。创建向导还会问你要不要现在就加 binding——可以先跳过，下一步手写。

第 2 步：用 binding 把渠道账号接到对应 agent

binding 只决定「这条消息归哪个 agent」——它不创建渠道账号，也不授予访问权，所以先把账号配好，再绑。一个 Gateway 可以挂多个账号，比如两个 WhatsApp 号码分别绑到两个专家。

先给每个 agent 准备一个渠道账号：

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

再在 ~/.openclaw/openclaw.json（JSON5）里把 agent 和账号接起来：agents.entries 列出 agent，bindings 声明路由。

{
  agents: {
    entries: {
      home: {
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      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" } },
  ],
}

账号级和会话级 binding 的差别，按需选：

• 账号级：只写 channel + accountId，整个账号的消息都归这个 agent。accountId: "*" 是渠道级兜底；省略 accountId 只匹配该渠道的默认账号。
• 会话级：加 match.peer（kind 取 direct/group/channel，用渠道的稳定 peer ID，别用显示名），只把某一个对话路由给专家。
• 优先级：具体会话、群组匹配赢过账号级和渠道兜底；同一层级内按配置顺序先到先得。

你应该看到：合法的 binding 改动在默认 hybrid 热重载模式下自动生效；若 gateway.reload.mode 为 off，要重启 Gateway 才生效。指向渠道从不接受的账号的 binding 不会起作用。

第 3 步：发消息验证路由与隔离

配置写了不等于路由对了——先用命令核对名册和绑定，再用真实消息各验一遍：

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

然后从每个绑定账号各发一条消息，确认三件事：消息进了正确的 agent；各自的会话历史独立；persona 规则各自生效。

你应该看到：agents list --bindings 列出 agent 名册和「渠道账号 → agent」的绑定关系，channels status --probe 显示各账号在线。如果没有任何 binding 匹配、又没有可用的默认归属，路由会报 AGENT_SELECTION_REQUIRED，提示你补一条 binding。三件事都通过，你的多个专家就在同一个 Gateway 里各就各位了。

检查点

• 永不复用 agentDir。两个 agent 指向同一目录，会造成 auth 与 session 状态冲突。
• OAuth 有继承行为：副 agent 的本地 OAuth 凭据过期或刷新失败时，OpenClaw 会读继承主的同 profile 凭据、采用更新的那个 token，且不把 refresh token 复制进副 agent 的存储。要完全独立的 OAuth 账号，就从那个 agent 自己登录一次。
• 手动复制凭据只复制静态项：api_key/token 类 profile 可复制；OAuth refresh 材料默认不可移植，除非用 copyToAgents 显式选入。
• Skills 双路加载：每个 agent 从自己的工作区加载 Skills，也会读共享根（如 ~/.openclaw/skills）。

边界

• 多 agent 仍在同一个 Gateway 进程内，信任边界不变；模型与 agent harness 都是可换插件。
• 渠道能力以插件为准：微信插件仅支持私聊，群聊不支持，别把「绑微信群」算进方案。
• 会话历史提供的是有界的跨会话召回，不是无限记忆。

下一步

• 要账号与会话级的完整配置示例，去看官方 Agent bindings 文档（docs/concepts/agent-bindings.md）。
• 给某个专家加能力：Skills 上手：安装、使用与配置。
• 让专家记住长期上下文：记忆系统：让 Claw 记住你。
• 想让这套多 agent 专家阵容 7×24 常驻：下一页服务器部署：Docker/VPS 上 7×24 运行。