Multi-agent

多代理路由

Status: active

執行多個_隔離_代理：每個代理都有自己的工作區、狀態目錄 (agentDir) 和工作階段歷史記錄，並且可在同一個執行中的 Gateway 內使用多個頻道帳號（例如兩個 WhatsApp）。傳入訊息會透過繫結路由到正確的代理。

這裡的 agent 是完整的每個 persona 範圍：工作區檔案、驗證設定檔、模型登錄檔和工作階段儲存區。agentDir 是磁碟上的狀態目錄，保存此每代理設定，位置為 ~/.openclaw/agents/<agentId>/。binding 會將頻道帳號（例如 Slack 工作區或 WhatsApp 號碼）對應到其中一個代理。

什麼是「一個代理」？

agent 是一個完整限定範圍的大腦，擁有自己的：

工作區（檔案、AGENTS.md/SOUL.md/USER.md、本機筆記、persona 規則）。
狀態目錄 (agentDir)，用於驗證設定檔、模型登錄檔和每代理設定。
工作階段儲存區（聊天歷史 + 路由狀態），位於 ~/.openclaw/agents/<agentId>/sessions 下。

驗證設定檔是每代理的。每個代理都會從自己的以下位置讀取：

text

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

Skills 會從每個代理工作區以及 ~/.openclaw/skills 等共享根目錄載入，然後在設定時依有效代理 Skills 允許清單篩選。使用 agents.defaults.skills 作為共享基準，並使用 agents.list[].skills 作為每代理替換。請參閱 Skills：每代理與共享和 Skills：代理 Skills 允許清單。

Gateway 可以並排託管一個代理（預設）或多個代理。

路徑（快速對照）

設定：~/.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。

代理輔助工具

使用代理精靈新增隔離的代理：

bash

openclaw agents add work

然後新增 bindings（或讓精靈執行）以路由傳入訊息。

使用以下指令驗證：

bash

openclaw agents list --bindings

快速開始

建立每個代理工作區

使用精靈或手動建立工作區：

bash

openclaw agents add codingopenclaw agents add social

每個代理都會取得自己的工作區，其中包含 SOUL.md、AGENTS.md 和選用的 USER.md，以及專用的 agentDir 和位於 ~/.openclaw/agents/<agentId> 下的工作階段儲存區。

建立頻道帳號

在你偏好的頻道上為每個代理建立一個帳號：

Discord：每個代理一個 bot，啟用 Message Content Intent，複製每個 token。
Telegram：每個代理透過 BotFather 建立一個 bot，複製每個 token。
WhatsApp：為每個帳號連結各自的電話號碼。

bash

openclaw channels login --channel whatsapp --account work

請參閱頻道指南：Discord、Telegram、WhatsApp。

新增代理、帳號與繫結

在 agents.list 下新增代理，在 channels.<channel>.accounts 下新增頻道帳號，並使用 bindings 將它們連接起來（範例如下）。

重新啟動並驗證

bash

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

多個代理 = 多個人、多種人格

使用多個代理時，每個 agentId 都會成為完全隔離的 persona：

不同電話號碼/帳號（每頻道 accountId）。
不同人格（每代理工作區檔案，例如 AGENTS.md 和 SOUL.md）。
分離的驗證 + 工作階段（除非明確啟用，否則不會互相串話）。

這讓多個人可以共享一個 Gateway 伺服器，同時保持其 AI「大腦」和資料隔離。

跨代理 QMD 記憶搜尋

如果某個代理應該搜尋另一個代理的 QMD 工作階段逐字稿，請在 agents.list[].memorySearch.qmd.extraCollections 下新增額外集合。只有當每個代理都應繼承相同的共享逐字稿集合時，才使用 agents.defaults.memorySearch.qmd.extraCollections。

json5

{  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 號碼，多個人（DM 分流）

你可以在維持一個 WhatsApp 帳號的同時，將不同 WhatsApp DM 路由到不同代理。使用 peer.kind: "direct" 依傳送者 E.164（例如 +15551234567）比對。回覆仍會來自同一個 WhatsApp 號碼（沒有每代理傳送者身分）。

範例：

json5

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

注意事項：

DM 存取控制是每個 WhatsApp 帳號全域的（配對/允許清單），不是每代理。
對於共享群組，請將群組繫結到一個代理，或使用廣播群組。

路由規則（訊息如何選擇代理）

繫結是確定性的，且最具體者優先：

peer 比對

精確的 DM/群組/頻道 ID。

parentPeer 比對

討論串繼承。

guildId + roles

Discord 角色路由。

guildId

Discord。

teamId

Slack。

頻道的 accountId 比對

每帳號後援。

頻道層級比對

accountId: "*"。

預設代理

後援至 agents.list[].default，否則使用第一個清單項目，預設：main。

平手決定與 AND 語意

如果多個繫結在同一層級相符，設定順序中的第一個會勝出。
如果繫結設定多個比對欄位（例如 peer + guildId），所有指定欄位都是必要的（AND 語意）。

帳號範圍詳細資料

省略 accountId 的繫結只會比對預設帳號。
使用 accountId: "*" 作為跨該頻道所有帳號的頻道範圍後援。
如果你稍後為同一代理新增具有明確帳號 ID 的相同繫結，OpenClaw 會將現有的僅頻道繫結升級為帳號限定範圍，而不是重複建立。

多個帳號 / 電話號碼

支援多個帳號的頻道（例如 WhatsApp）會使用 accountId 來識別每個登入。每個 accountId 都可以路由到不同代理，因此一台伺服器可以託管多個電話號碼，而不混合工作階段。

如果你想在省略 accountId 時使用頻道範圍的預設帳號，請設定 channels.<channel>.defaultAccount（選用）。未設定時，OpenClaw 會在存在 default 時回退至 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 bot

每個 Discord bot 帳號都會對應到唯一的 accountId。將每個帳號繫結到一個代理，並為每個 bot 保留允許清單。

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）。

Telegram bots per agent

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 為每個代理建立一個 bot，並複製每個 token。
Token 位於 channels.telegram.accounts.<id>.botToken（預設帳號可使用 TELEGRAM_BOT_TOKEN）。

WhatsApp numbers per agent

啟動 gateway 前，先連結每個帳號：

bash

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

~/.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",      },    ],  },   // 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: "[email protected]" },      },    },  ],   // 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",        },      },    },  },}

常見模式

WhatsApp daily + Telegram deep work

依 channel 分流：將 WhatsApp 路由到快速的日常代理，將 Telegram 路由到 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: "chat", match: { channel: "whatsapp" } },    { agentId: "opus", match: { channel: "telegram" } },  ],}

注意事項：

如果某個 channel 有多個帳號，請在 binding 加入 accountId（例如 { channel: "whatsapp", accountId: "personal" }）。
若要將單一 DM/群組路由到 Opus，同時讓其餘內容保留在 chat，請為該 peer 加入 match.peer binding；peer match 永遠優先於 channel-wide 規則。

Same channel, one peer to Opus

將 WhatsApp 保留在快速代理上，但將一個 DM 路由到 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-wide 規則上方。

Family agent bound to a WhatsApp group

將專用的家庭代理綁定到單一 WhatsApp 群組，並使用 mention gating 和更嚴格的工具政策：

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: "[email protected]" },      },    },  ],}

注意事項：

工具允許/拒絕清單是工具，不是 Skills。如果某個 skill 需要執行二進位檔，請確認 exec 已被允許，且該二進位檔存在於 sandbox 中。
若要更嚴格 gating，請設定 agents.list[].groupChat.mentionPatterns，並保持該 channel 的群組允許清單啟用。

每代理 sandbox 和工具設定

每個代理都可以有自己的 sandbox 和工具限制：

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

優點：

安全隔離：限制不受信任代理的工具。
資源控制：將特定代理置於 sandbox，同時讓其他代理保留在主機上。
彈性政策：每個代理使用不同權限。

詳情與範例請參閱多代理 sandbox 和工具。

多代理路由

什麼是「一個代理」？

路徑（快速對照）

單代理模式（預設）

代理輔助工具

快速開始

建立每個代理工作區

建立頻道帳號

新增代理、帳號與繫結

重新啟動並驗證

多個代理 = 多個人、多種人格

跨代理 QMD 記憶搜尋

一個 WhatsApp 號碼，多個人（DM 分流）

路由規則（訊息如何選擇代理）

peer 比對

parentPeer 比對

guildId + roles

guildId

teamId

頻道的 accountId 比對

頻道層級比對

預設代理

多個帳號 / 電話號碼

概念

平台範例

常見模式

WhatsApp daily + Telegram deep work

Same channel, one peer to Opus

Family agent bound to a WhatsApp group

每代理 sandbox 和工具設定

相關

Molty