Multi-Agent 路由
目标：在一个运行中的 Gateway 里管理多个隔离的 Agent（独立的 Workspace + agentDir + Session），以及多个 Channel 账号（比如两个 WhatsApp 账号）。通过绑定规则将收到的消息路由到对应的 Agent。
什么是”一个 Agent”？
一个 Agent 是一个完整独立的”大脑”，拥有自己的：
- Workspace（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、人格规则）。
- 状态目录（
agentDir）用于存放认证配置、模型注册表和 Agent 专属配置。 - Session 存储（聊天历史 + 路由状态）位于
~/.openclaw/agents/<agentId>/sessions。
认证配置是 按 Agent 隔离的。每个 Agent 从自己的配置文件读取：
~/.openclaw/agents/<agentId>/agent/auth-profiles.json主 Agent 的凭证不会自动共享。永远不要在多个 Agent 之间复用 agentDir（会导致认证/Session 冲突）。如果你想共享凭证，手动复制 auth-profiles.json 到另一个 Agent 的 agentDir。
Skill 也是按 Agent 隔离的，通过每个 Workspace 的 skills/ 文件夹管理，共享的 Skill 可以放在 ~/.openclaw/skills。详见 Skill：按 Agent 隔离 vs 共享。
Gateway 可以托管一个 Agent（默认）或多个 Agent 并行运行。
Workspace 说明： 每个 Agent 的 Workspace 是默认工作目录，不是硬性沙箱。相对路径会在 Workspace 内解析，但绝对路径可以访问主机其他位置，除非启用了沙箱。详见 Sandboxing。
路径速查表
- 配置文件：
~/.openclaw/openclaw.json（或OPENCLAW_CONFIG_PATH） - 状态目录：
~/.openclaw（或OPENCLAW_STATE_DIR） - Workspace：
~/.openclaw/workspace（或~/.openclaw/workspace-<agentId>） - Agent 目录：
~/.openclaw/agents/<agentId>/agent（或agents.list[].agentDir） - Session 存储：
~/.openclaw/agents/<agentId>/sessions
单 Agent 模式（默认）
如果你什么都不配置，OpenClaw 会运行单个 Agent：
agentId默认为main。- Session 的键名格式为
agent:main:<mainKey>。 - Workspace 默认为
~/.openclaw/workspace（如果设置了OPENCLAW_PROFILE，则为~/.openclaw/workspace-<profile>）。 - 状态目录默认为
~/.openclaw/agents/main/agent。
Agent 助手命令
用 Agent 向导添加一个新的隔离 Agent：
openclaw agents add work然后添加 bindings（或让向导帮你做）来路由收到的消息。
验证配置：
openclaw agents list --bindings多个 Agent = 多个人、多种人格
使用多个 Agent 时，每个 agentId 都是一个完全隔离的人格：
- 不同的手机号/账号（每个 Channel 的
accountId）。 - 不同的人格（通过每个 Agent 的 Workspace 文件如
AGENTS.md和SOUL.md定义）。 - 独立的认证 + Session（除非明确启用，否则不会互相干扰）。
这让多个人可以共享一个 Gateway 服务器，同时保持各自的 AI “大脑”和数据隔离。
一个 WhatsApp 号，多个人（DM 分流）
你可以将不同的 WhatsApp 私信路由到不同的 Agent，同时只用一个 WhatsApp 账号。通过发送者的 E.164 号码（如 +15551234567）匹配，配合 peer.kind: "dm"。回复仍然来自同一个 WhatsApp 号（没有按 Agent 区分的发送者身份）。
重要细节：私聊会合并到 Agent 的 main session key，所以真正的隔离需要每人一个 Agent。
示例：
{
agents: {
list: [
{ id: "alex", workspace: "~/.openclaw/workspace-alex" },
{ id: "mia", workspace: "~/.openclaw/workspace-mia" },
],
},
bindings: [
{ agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
{ agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
],
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551230001", "+15551230002"],
},
},
}注意：
- DM 访问控制是按 WhatsApp 账号全局生效的（配对/白名单），不是按 Agent。
- 对于共享群组，把群组绑定到一个 Agent，或使用 广播群组。
路由规则（消息如何选择 Agent）
绑定规则是确定性的，最具体的规则优先：
peer匹配（精确的 DM/群组/频道 ID）guildId（Discord）teamId（Slack）- Channel 的
accountId匹配 - Channel 级别匹配（
accountId: "*"） - 回退到默认 Agent（
agents.list[].default，否则列表第一项，默认为main）
多个账号 / 手机号
支持多账号的 Channel（如 WhatsApp）用 accountId 来标识每个登录。每个 accountId 可以路由到不同的 Agent，这样一个服务器可以托管多个手机号而不会混淆 Session。
核心概念
agentId：一个”大脑”（Workspace、按 Agent 隔离的认证、按 Agent 隔离的 Session 存储）。accountId：一个 Channel 账号实例（如 WhatsApp 账号"personal"vs"biz"）。binding：通过(channel, accountId, peer)以及可选的 guild/team ID 将收到的消息路由到agentId。- 私聊会合并到
agent:<agentId>:<mainKey>（每个 Agent 的”main”；session.mainKey）。
示例：两个 WhatsApp → 两个 Agent
~/.openclaw/openclaw.json（JSON5 格式）：
{
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" } },
// 可选的按对话方覆盖（示例：把特定群组发给 work agent）。
{
agentId: "work",
match: {
channel: "whatsapp",
accountId: "personal",
peer: { kind: "group", id: "[email protected]" },
},
},
],
// 默认关闭：Agent 之间的消息传递必须明确启用 + 加入白名单。
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",
},
},
},
},
}示例：WhatsApp 日常聊天 + Telegram 深度工作
按 Channel 分流：把 WhatsApp 路由到快速的日常 Agent，Telegram 路由到 Opus Agent。
{
agents: {
list: [
{
id: "chat",
name: "Everyday",
workspace: "~/.openclaw/workspace-chat",
model: "anthropic/claude-sonnet-4-5",
},
{
id: "opus",
name: "Deep Work",
workspace: "~/.openclaw/workspace-opus",
model: "anthropic/claude-opus-4-5",
},
],
},
bindings: [
{ agentId: "chat", match: { channel: "whatsapp" } },
{ agentId: "opus", match: { channel: "telegram" } },
],
}注意：
- 如果一个 Channel 有多个账号，在绑定规则里加上
accountId（比如{ channel: "whatsapp", accountId: "personal" }）。 - 要把单个 DM/群组路由到 Opus 而其他保持在 chat，为那个对话方添加
match.peer绑定；peer 匹配总是优先于 Channel 级别规则。
示例：同一 Channel，单个对话方用 Opus
保持 WhatsApp 在快速 Agent，但把一个 DM 路由到 Opus：
{
agents: {
list: [
{
id: "chat",
name: "Everyday",
workspace: "~/.openclaw/workspace-chat",
model: "anthropic/claude-sonnet-4-5",
},
{
id: "opus",
name: "Deep Work",
workspace: "~/.openclaw/workspace-opus",
model: "anthropic/claude-opus-4-5",
},
],
},
bindings: [
{ agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
{ agentId: "chat", match: { channel: "whatsapp" } },
],
}Peer 绑定总是优先，所以把它们放在 Channel 级别规则上面。
家庭 Agent 绑定到 WhatsApp 群组
把一个专用的家庭 Agent 绑定到单个 WhatsApp 群组，配合提及触发和更严格的工具策略：
{
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: "[email protected]" },
},
},
],
}注意：
- 工具的 allow/deny 列表是工具，不是 Skill。如果 Skill 需要运行二进制文件，确保
exec被允许且二进制文件存在于 Sandbox 中。 - 要更严格的触发控制，设置
agents.list[].groupChat.mentionPatterns并为 Channel 保持群组白名单启用。
按 Agent 配置 Sandbox 和工具
从 v2026.1.6 开始，每个 Agent 可以有自己的 Sandbox 和工具限制：
{
agents: {
list: [
{
id: "personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: {
mode: "off", // 个人 Agent 不用沙箱
},
// 没有工具限制 - 所有工具可用
},
{
id: "family",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all", // 总是在沙箱中
scope: "agent", // 每个 Agent 一个容器
docker: {
// 可选的一次性设置，在容器创建后执行
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
tools: {
allow: ["read"], // 只允许 read 工具
deny: ["exec", "write", "edit", "apply_patch"], // 拒绝其他
},
},
],
},
}注意：setupCommand 位于 sandbox.docker 下，在容器创建时运行一次。当解析后的 scope 是 "shared" 时，按 Agent 的 sandbox.docker.* 覆盖会被忽略。
好处：
- 安全隔离：为不受信任的 Agent 限制工具
- 资源控制：为特定 Agent 启用沙箱，其他保持在主机上
- 灵活策略：每个 Agent 不同的权限
注意：tools.elevated 是全局的且基于发送者；不能按 Agent 配置。如果你需要按 Agent 设置边界，用 agents.list[].tools 拒绝 exec。对于群组定向，用 agents.list[].groupChat.mentionPatterns 让 @提及 清晰地映射到目标 Agent。
详见 Multi-Agent Sandbox & 工具 获取详细示例。