多代理路由

在一個閘道程序中執行多個彼此_隔離_的代理程式，每個代理程式都有自己的工作區、狀態目錄（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 等共用根目錄載入，再依代理程式的有效 Skill 允許清單篩選。使用 agents.defaults.skills 設定共用基準，使用 agents.entries.*.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.entries.*.memory.search.qmd.extraCollections 下新增額外集合。當所有代理程式都應共用相同集合時，請使用 memory.search.qmd.extraCollections。

{  agents: {    defaults: {      workspace: "~/workspaces/main",    },    entries: {      main: {        workspace: "~/workspaces/main",        memory: {          search: {            qmd: {              extraCollections: [{ path: "notes" }], // 在工作區內解析 -> 名為 "notes-main" 的集合            },          },        },      },      family: { workspace: "~/workspaces/family" },    },  },  memory: {    backend: "qmd",    search: {      qmd: {        extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],      },    },    qmd: { includeDefaultMemory: false },  },}

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

一個 WhatsApp 號碼、多人使用（私訊分流）

透過 peer.kind: "direct" 比對傳送者的 E.164（+15551234567），即可在同一個 WhatsApp 帳號上，將不同的 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)，以及選用的公會／團隊 ID，將傳入訊息路由至 agentId。
• 直接聊天會歸併至 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: "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" } },     // 選用的個別對話對象覆寫（範例：將特定群組傳送至工作代理程式）。    {      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: "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", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

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

{  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: "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 代理程式 — 執行外部程式設計框架
• 頻道路由 — 訊息如何路由至代理程式
• 上線狀態 — 代理程式的上線狀態與可用性
• 工作階段 — 工作階段隔離與路由
• 子代理程式 — 產生背景代理程式執行作業