【OpenClaw】多 Agent 配置指南

OpenClaw 多 Agent 配置指南

声明：本文由 AI 辅助生成，内容基于 OpenClaw 官方文档整理。

什么是多 Agent？

多 Agent = 多个完全隔离的 AI 大脑运行在同一个 Gateway 上。

每个 Agent 拥有：

独立的工作区（workspace）—— 自己的 SOUL.md、USER.md、AGENTS.md
独立的状态目录（agentDir）—— 自己的认证配置、模型注册表
独立的会话存储（sessions）—— 自己的聊天历史和路由状态

类比：多 Agent 就像在一台服务器上运行多个虚拟机，每个虚拟机有自己的硬盘、内存和系统配置。

核心概念

agentId：Agent 的唯一标识符，如 "main", "work", "family"
accountId：渠道账号实例，如 "personal", "biz"（不同 WhatsApp 号码）
binding：路由规则，将消息导向特定 Agent
workspace：Agent 的工作目录，如 ~/.openclaw/workspace-work
agentDir：Agent 的状态目录，如 ~/.openclaw/agents/work/agent

快速开始：4 步开启多 Agent

步骤 1：创建 Agent 工作区

使用向导或手动创建：

# 使用向导创建（推荐）
openclaw agents add coding
openclaw agents add social
 
# 验证
openclaw agents list --bindings

每个 Agent 会自动获得：

独立的 workspace（~/.openclaw/workspace-<agentId>）
独立的 agentDir（~/.openclaw/agents/<agentId>/agent）
默认配置文件（SOUL.md、AGENTS.md 等）

步骤 2：创建渠道账号

为每个 Agent 配置独立的渠道账号：

Discord：每个 Agent 一个 Bot

# 在 Discord Developer Portal 创建 Bot，启用 Message Content Intent
# 复制 Bot Token 到配置文件

Telegram：每个 Agent 一个 Bot

# 通过 BotFather 创建 Bot，复制 Bot Token

WhatsApp：每个 Agent 一个手机号

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

步骤 3：配置 Agent 和绑定

编辑 ~/.openclaw/openclaw.json：

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "主助理",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
      },
      {
        id: "work",
        name: "工作助理",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    ],
  },
  
  // 路由规则：最具体的匹配优先
  bindings: [
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
    { agentId: "main", match: { channel: "whatsapp", accountId: "personal" } },
  ],
  
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      },
    },
  },
}

步骤 4：重启并验证

# 重启 Gateway
openclaw gateway restart
 
# 验证 Agent 列表和绑定
openclaw agents list --bindings
 
# 验证渠道状态
openclaw channels status --probe

配置示例：多种场景

场景 1：不同 WhatsApp 号码对应不同 Agent

{
  agents: {
    list: [
      { id: "home", workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

效果：

personal 号码的消息 → home Agent
biz 号码的消息 → work Agent

场景 2：同一 WhatsApp 号码，不同 DM 路由到不同 Agent

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

效果：

+15551230001 发来的消息 → alex Agent
+15551230002 发来的消息 → mia Agent

场景 3：WhatsApp 聊天 + Telegram 深度工作

{
  agents: {
    list: [
      {
        id: "chat",
        name: "日常助理",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "深度工作",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

效果：

WhatsApp 消息 → chat Agent（快速回复）
Telegram 消息 → opus Agent（深度推理）

场景 4：家庭 Agent 绑定到 WhatsApp 群组

{
  agents: {
    list: [
      {
        id: "family",
        name: "家庭助理",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot"],
        },
        tools: {
          allow: ["read", "exec"],
          deny: ["write", "edit", "cron"],
        },
      },
    ],
  },
  
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}

效果：

仅在该群组中响应 @family 提及
工具权限受限（只读 + 执行）

路由规则：优先级详解

Binding 是确定性的，最具体的匹配优先：

peer（精确 DM/群组/频道 ID）—— 最高优先级
parentPeer（线程继承）
guildId + roles（Discord 角色）
guildId（Discord 服务器）
teamId（Slack 团队）
accountId（渠道账号）
accountId: ”*“（渠道范围）
默认 Agent（agents.list[].default 或第一个 Agent）

关键：如果多个 Binding 在同一层级匹配，配置顺序靠前的优先。

沙箱与工具权限配置

场景：个人 Agent 无沙箱 + 家庭 Agent 严格沙箱

{
  agents: {
    list: [
      {
        id: "main",
        name: "个人助理",
        workspace: "~/.openclaw/workspace",
        sandbox: { mode: "off" },  // 无沙箱，完整工具访问
      },
      {
        id: "family",
        name: "家庭助理",
        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", "browser"],
        },
      },
    ],
  },
}

效果：

main Agent：运行在宿主机，所有工具可用
family Agent：运行在 Docker 容器中，仅允许 read 工具

常见问题

Q: 多个 Agent 会共享认证信息吗？

不会。 每个 Agent 有独立的 auth-profiles.json：

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

如需共享，请手动复制该文件到另一个 Agent 的 agentDir。

Q: 如何让一个 Agent 访问另一个 Agent 的会话历史？

配置 memorySearch.qmd.extraCollections：

{
  agents: {
    list: [
      {
        id: "main",
        memorySearch: {
          qmd: {
            extraCollections: [
              { path: "~/.openclaw/agents/family/sessions", name: "family-sessions" },
            ],
          },
        },
      },
    ],
  },
}

Q: 如何调试路由问题？

# 查看路由日志
tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|binding"
 
# 验证绑定
openclaw agents list --bindings
 
# 测试渠道连接
openclaw channels status --probe

Q: Agent 没有被沙箱化，即使设置了 `mode: "all"`？

检查是否有全局配置覆盖：

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },  // 这会覆盖所有 Agent
    },
    list: [
      {
        id: "family",
        sandbox: { mode: "all" },  // 必须显式设置
      },
    ],
  },
}

总结

多 Agent 的本质 = 在一个 Gateway 上运行多个完全隔离的 AI 实例，通过 Binding 规则将消息路由到对应的 Agent。

关键步骤：

创建 Agent 工作区（openclaw agents add）
配置渠道账号（每个 Agent 对应一个账号）
编写 Binding 规则（路由逻辑）
重启并验证（openclaw gateway restart）

核心原则：

每个 Agent 是独立的“大脑”
Binding 决定消息流向
最具体的匹配优先

创建时间：2026-04-10
_标签：#OpenClaw agent 配置路由

小M-Quartz

探索

【OpenClaw】多 Agent 配置指南

什么是多 Agent？

核心概念

快速开始：4 步开启多 Agent

步骤 1：创建 Agent 工作区

步骤 2：创建渠道账号

步骤 3：配置 Agent 和绑定

步骤 4：重启并验证

配置示例：多种场景

场景 1：不同 WhatsApp 号码对应不同 Agent

场景 2：同一 WhatsApp 号码，不同 DM 路由到不同 Agent

场景 3：WhatsApp 聊天 + Telegram 深度工作

场景 4：家庭 Agent 绑定到 WhatsApp 群组

路由规则：优先级详解

沙箱与工具权限配置

场景：个人 Agent 无沙箱 + 家庭 Agent 严格沙箱

常见问题

Q: 多个 Agent 会共享认证信息吗？

Q: 如何让一个 Agent 访问另一个 Agent 的会话历史？

Q: 如何调试路由问题？

Q: Agent 没有被沙箱化，即使设置了 `mode: "all"`？

相关资源

总结

关系图谱

反向链接

小M-Quartz

探索

【OpenClaw】多 Agent 配置指南

什么是多 Agent？

核心概念

快速开始：4 步开启多 Agent

步骤 1：创建 Agent 工作区

步骤 2：创建渠道账号

步骤 3：配置 Agent 和绑定

步骤 4：重启并验证

配置示例：多种场景

场景 1：不同 WhatsApp 号码对应不同 Agent

场景 2：同一 WhatsApp 号码，不同 DM 路由到不同 Agent

场景 3：WhatsApp 聊天 + Telegram 深度工作

场景 4：家庭 Agent 绑定到 WhatsApp 群组

路由规则：优先级详解

沙箱与工具权限配置

场景：个人 Agent 无沙箱 + 家庭 Agent 严格沙箱

常见问题

Q: 多个 Agent 会共享认证信息吗？

Q: 如何让一个 Agent 访问另一个 Agent 的会话历史？

Q: 如何调试路由问题？

Q: Agent 没有被沙箱化，即使设置了 mode: "all"？

相关资源

总结

关系图谱

反向链接

Q: Agent 没有被沙箱化，即使设置了 `mode: "all"`？