多代理路由

在單一閘道程序中執行多個彼此_隔離_的代理，每個代理都有自己的工作區、狀態目錄（agentDir）及以 SQLite 為後端的工作階段歷程，並可搭配多個頻道帳號（例如兩個 WhatsApp 號碼）。傳入訊息會透過繫結路由至正確的代理。

代理是每個角色的完整範圍：工作區檔案、驗證設定檔、模型登錄檔及工作階段儲存區。繫結會將頻道帳號（Slack 工作區、WhatsApp 號碼等）對應至其中一個代理。

什麼是一個代理

每個代理都有自己的：

• 工作區：檔案、AGENTS.md/SOUL.md/USER.md、本機筆記、角色規則。
• 狀態目錄（agentDir）：驗證設定檔、模型登錄檔、每個代理的設定。
• 工作階段儲存區：位於 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 的聊天歷程與路由狀態。

驗證設定檔各代理獨立，讀取自：

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

Skills 會從各代理的工作區及 ~/.openclaw/skills 等共用根目錄載入，接著依代理實際生效的 Skills 允許清單進行篩選。使用 agents.defaults.skills 設定共用基準，並使用 agents.list[].skills 設定每個代理的替代項目（明確設定的項目會取代預設值，而不會合併）。請參閱 Skills：各代理與共用 Skills及 Skills：代理允許清單。

由外掛擁有的儲存空間會遵循該外掛的設定；新增第二個代理 不會自動分割所有全域外掛儲存區。例如，當不同角色不得共用已編譯的 Wiki 知識時，請設定 Memory Wiki 各代理資料保險箱。

路徑

單一代理模式（預設）

若你未進行任何設定，OpenClaw 會執行一個代理：

• agentId 預設為 main。
• 工作階段鍵為 agent:main:<mainKey>（mainKey 預設為 main）。
• 工作區預設為 ~/.openclaw/workspace（當 OPENCLAW_PROFILE 設為 default 以外的值時，則為 workspace-<profile>）。
• 狀態預設位於 ~/.openclaw/agents/main/agent。

代理輔助工具

新增一個隔離的代理：

openclaw agents add work

旗標：--workspace <dir>、--model <id>、--agent-dir <dir>、--bind <channel[:accountId]>（可重複使用）、--non-interactive（需要 --workspace）。

新增 bindings 以路由傳入訊息（精靈會詢問是否要代你執行），接著驗證：

openclaw agents list --bindings

快速開始

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

多個代理、多種角色

每個已設定的 agentId 都是核心代理狀態中彼此獨立的角色邊界：

• 各頻道使用不同帳號（依 accountId 區分）。
• 不同的個性（每個代理各自擁有 AGENTS.md/SOUL.md）。
• 驗證與工作階段彼此分離；只有透過明確功能或外掛設定，才會啟用跨代理存取。

如此一來，多人便可共用一個閘道，同時將核心代理狀態彼此分離。

各代理的 Memory Wiki 資料保險箱

Memory Wiki 預設使用一個全域資料保險箱。若要讓支援代理的 已編譯知識與行銷代理分開，請將 plugins.entries.memory-wiki.config.vault.scope 設為 agent：

{  plugins: {    entries: {      "memory-wiki": {        enabled: true,        config: {          vault: {            scope: "agent",            path: "~/.openclaw/wiki",          },        },      },    },  },}

設定的路徑是父目錄。OpenClaw 會附加正規化後的 代理 ID，產生如 ~/.openclaw/wiki/support 和 ~/.openclaw/wiki/marketing 的路徑。設定多個代理時，代理範圍的命令列介面與閘道操作需要 明確指定代理。關於橋接 篩選、遷移與信任邊界的詳細資訊，請參閱 Memory Wiki 各代理資料保險箱。

跨代理 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" }], // 在工作區內解析 -> 名為 "notes-main" 的集合          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

額外集合路徑可由多個代理共用，但當路徑位於代理工作區之外時，其 name 仍須明確指定。工作區內的路徑維持代理範圍，讓每個代理保有自己的逐字記錄搜尋集合。

一個 WhatsApp 號碼，多位使用者（私訊分流）

在同一個 WhatsApp 帳號上，藉由比對傳送者的 E.164（+15551234567）與 peer.kind: "direct"，將不同的 WhatsApp 私訊路由至不同代理。回覆仍會從同一個 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"],    },  },}

私訊存取控制（配對／允許清單）是每個 WhatsApp 帳號的全域設定，而非每個代理各自設定。對於共用群組，請將群組繫結至一個代理，或使用廣播群組。

路由規則

繫結是確定性的，並以最具體的比對為優先。完整的層級順序（精確對等端、父對等端、對等端萬用字元、伺服器＋角色、伺服器、團隊、帳號、頻道、預設代理）請參閱頻道路由。以下是幾項值得特別說明的規則：

• 若同一層級內有多個繫結相符，設定順序中的第一個會勝出。
• 若一個繫結設定多個比對欄位（例如 peer + guildId），所有指定欄位都必須相符（AND 語意）。
• 未指定 accountId 的繫結只會比對預設帳號，而非所有帳號。頻道範圍的後援請使用 accountId: "*"，特定帳號則使用 accountId: "<name>"。再次新增相同繫結並明確指定帳號 ID 時，會升級現有的僅限頻道繫結，而非建立重複項目。

多個帳號／電話號碼

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

設定 channels.<channel>.defaultAccount，以選擇省略 accountId 時使用的帳號。若未設定，OpenClaw 會優先使用 default（若存在）；否則使用排序後的第一個已設定帳號 ID。

支援多個帳號的頻道：discord、feishu、googlechat、imessage、irc、line、mattermost、matrix、nextcloud-talk、nostr、signal、slack、telegram、whatsapp、zalo、zalouser。

概念

• agentId：一個「大腦」（工作區、各代理程式的驗證、各代理程式的工作階段儲存區）。
• accountId：一個頻道帳號執行個體（例如 WhatsApp 帳號 personal 與 biz）。
• binding：依據 (channel, accountId, peer) 將傳入訊息路由至 agentId，並可選擇性納入 guild/team ID。
• 私訊會彙整至 agent:<agentId>:<mainKey>（各代理程式的「主要」工作階段；請參閱 session.mainKey）。

平台範例

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

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

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

{  agents: {    list: [      {        id: "home",        default: true,        name: "家庭",        workspace: "~/.openclaw/workspace-home",        agentDir: "~/.openclaw/agents/home/agent",      },      {        id: "work",        name: "工作",        workspace: "~/.openclaw/workspace-work",        agentDir: "~/.openclaw/agents/work/agent",      },    ],  },   // 確定性路由：第一個相符項目優先（最具體的項目排在最前面）。  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // 選用的個別對話方覆寫（範例：將特定群組傳送至工作代理程式）。    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // 預設關閉：必須明確啟用代理程式間訊息，並將其加入允許清單。  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",        },      },    },  },}

常見模式

{  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", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

{  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: "opus",      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

{  agents: {    list: [      {        id: "family",        name: "家庭",        workspace: "~/.openclaw/workspace-family",        identity: { name: "家庭機器人" },        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: "120363999999999999@g.us" },      },    },  ],}

各代理程式的沙箱與工具設定

每個代理程式都可以有自己的沙箱與工具限制：

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // 個人代理程式不使用沙箱        },        // 不限制工具——所有工具皆可使用      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        sandbox: {          mode: "all",     // 一律在沙箱中執行          scope: "agent",  // 每個代理程式使用一個容器          docker: {            // 容器建立後可選擇執行一次性的設定            setupCommand: "apt-get update && apt-get install -y git curl",          },        },        tools: {          allow: ["read"],                    // 僅允許讀取工具          deny: ["exec", "write", "edit", "apply_patch"],    // 拒絕其他工具        },      },    ],  },}

這會提供：

• 安全隔離：限制不受信任代理程式可使用的工具。
• 資源控制：讓特定代理程式在沙箱中執行，同時讓其他代理程式保留在主機上。
• 彈性政策：為每個代理程式設定不同權限。

如需詳細範例，請參閱多代理程式沙箱與工具。

相關內容

• ACP 代理程式 — 執行外部程式設計框架
• 頻道路由 — 訊息如何路由至代理程式
• 上線狀態 — 代理程式的上線狀態與可用性
• 工作階段 — 工作階段隔離與路由
• 子代理程式 — 產生背景代理程式執行作業