Multi-agent

多代理路由

執行多個_隔離_代理——每個代理都有自己的工作區、狀態目錄（agentDir）和工作階段歷史——以及多個頻道帳號（例如兩個 WhatsApp 帳號）於同一個執行中的 Gateway。傳入訊息會透過綁定路由到正確的代理。

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

什麼是「一個代理」？

代理是一個完整限定範圍的大腦，具有自己的：

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

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

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

代理輔助工具

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

openclaw agents add work

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

使用以下命令驗證：

openclaw agents list --bindings

快速開始

建立每個代理工作區

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

openclaw agents add coding
openclaw agents add social

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

建立頻道帳號

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

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

openclaw channels login --channel whatsapp --account work

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

新增代理、帳號和綁定

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

重新啟動並驗證

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

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

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

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

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

跨代理 QMD 記憶搜尋

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

{
  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 號碼（沒有每個代理各自的傳送者身分）。

範例：

{
  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
bluebubbles、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 保留允許清單。

{
  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。
權杖位於 channels.discord.accounts.<id>.token（預設帳戶可使用 DISCORD_BOT_TOKEN）。

每個 agent 使用不同的 Telegram bot

{
  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 為每個 agent 建立一個 bot，並複製各自的權杖。
權杖位於 channels.telegram.accounts.<id>.botToken（預設帳戶可使用 TELEGRAM_BOT_TOKEN）。

每個 agent 使用不同的 WhatsApp 號碼

啟動 Gateway 前，請先連結每個帳戶：

openclaw channels login --channel whatsapp --account personal
openclaw 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 日常 + Telegram 深度工作

依 channel 分流：將 WhatsApp 路由到快速的日常 agent，並將 Telegram 路由到 Opus agent。

{
  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 有多個帳戶，請在繫結中加入 accountId（例如 { channel: "whatsapp", accountId: "personal" }）。
若要將單一 DM/group 路由到 Opus，同時讓其餘都留在 chat，請為該 peer 新增 match.peer 繫結；peer 符合項目一律優先於整個 channel 的規則。

相同 channel，將一個 peer 路由到 Opus

讓 WhatsApp 保持使用快速 agent，但將一個 DM 路由到 Opus：

{
  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 繫結一律優先，因此請將它們放在整個 channel 規則上方。

繫結到 WhatsApp 群組的家庭 agent

將專用的家庭 agent 繫結到單一 WhatsApp 群組，並設定 mention 閘控與更嚴格的工具政策：

{
  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 中。
如需更嚴格的閘控，請設定 agents.list[].groupChat.mentionPatterns，並讓該 channel 的群組允許清單保持啟用。

每個 agent 的 sandbox 與工具設定

每個 agent 都可以有自己的 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
        },
      },
    ],
  },
}

優點：

安全隔離：限制不受信任 agent 的工具。
資源控制：將特定 agent 放入 sandbox，同時讓其他 agent 保持在主機上。
彈性政策：為每個 agent 設定不同權限。

詳細範例請參閱多 agent sandbox 與工具。

多代理路由

什麼是「一個代理」？

路徑（快速對照）

單一代理模式（預設）

代理輔助工具

快速開始

建立每個代理工作區

建立頻道帳號

新增代理、帳號和綁定

重新啟動並驗證

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

跨代理 QMD 記憶搜尋

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

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

peer 比對

parentPeer 比對

guildId + roles

guildId

teamId

頻道的 accountId 比對

頻道層級比對

預設代理

多個帳號 / 電話號碼

概念

平台範例

常見模式

WhatsApp 日常 + Telegram 深度工作

相同 channel，將一個 peer 路由到 Opus

繫結到 WhatsApp 群組的家庭 agent

每個 agent 的 sandbox 與工具設定

相關

Ask OpenClaw

# 什麼是「一個代理」？

# 路徑（快速對照）

# 單一代理模式（預設）

# 代理輔助工具

# 快速開始

建立每個代理工作區

建立頻道帳號

新增代理、帳號和綁定

重新啟動並驗證

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

# 跨代理 QMD 記憶搜尋

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

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

peer 比對

parentPeer 比對

guildId + roles

guildId

teamId

頻道的 accountId 比對

頻道層級比對

預設代理

# 多個帳號 / 電話號碼

# 概念

# 平台範例

# 常見模式

WhatsApp 日常 + Telegram 深度工作

相同 channel，將一個 peer 路由到 Opus

繫結到 WhatsApp 群組的家庭 agent

# 每個 agent 的 sandbox 與工具設定

# 相關

什麼是「一個代理」？

路徑（快速對照）

單一代理模式（預設）

代理輔助工具

快速開始

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

跨代理 QMD 記憶搜尋

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

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

多個帳號 / 電話號碼

概念

平台範例

常見模式

每個 agent 的 sandbox 與工具設定

相關