跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

執行多個_隔離_代理：每個代理都有自己的工作區、狀態目錄 (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 下。
驗證設定檔是每代理的。每個代理都會從自己的以下位置讀取： 
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
sessions_history 在這裡也是較安全的跨工作階段回憶路徑：它會傳回有界限且經清理的檢視，而不是原始逐字稿傾印。Assistant 回憶會在修訂/截斷前移除思考標籤、<relevant-memories> 鷹架、純文字工具呼叫 XML 酬載（包含 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls>，以及被截斷的工具呼叫區塊）、降級的工具呼叫鷹架、外洩的 ASCII/全形模型控制 token，以及格式錯誤的 MiniMax 工具呼叫 XML。
切勿在多個代理之間重複使用 agentDir（這會造成驗證/工作階段衝突）。當代理沒有本機設定檔時，可以讀取預設/主要代理的驗證設定檔，但 OpenClaw 不會將 OAuth 重新整理 token 複製到次要代理儲存區。如果你想要獨立的 OAuth 帳號，請從該代理登入；如果你手動複製認證，請只複製可攜式靜態 api_key 或 token 設定檔。
Skills 會從每個代理工作區以及 ~/.openclaw/skills 等共享根目錄載入，然後在設定時依有效代理 Skills 允許清單篩選。使用 agents.defaults.skills 作為共享基準，並使用 agents.list[].skills 作為每代理替換。請參閱 Skills：每代理與共享 和 Skills：代理 Skills 允許清單。 Gateway 可以並排託管一個代理（預設）或多個代理。
工作區注意事項：每個代理的工作區是預設 cwd，不是嚴格的沙箱。相對路徑會在工作區內解析，但除非啟用沙箱，否則絕對路徑可以到達其他主機位置。請參閱沙箱。

​
路徑（快速對照）

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

​
快速開始

1

建立每個代理工作區

使用精靈或手動建立工作區：
openclaw agents add coding
openclaw agents add social
每個代理都會取得自己的工作區，其中包含 SOUL.md、AGENTS.md 和選用的 USER.md，以及專用的 agentDir 和位於 ~/.openclaw/agents/<agentId> 下的工作階段儲存區。
2

建立頻道帳號

在你偏好的頻道上為每個代理建立一個帳號：
  • Discord：每個代理一個 bot，啟用 Message Content Intent，複製每個 token。
  • Telegram：每個代理透過 BotFather 建立一個 bot，複製每個 token。
  • WhatsApp：為每個帳號連結各自的電話號碼。
openclaw channels login --channel whatsapp --account work
請參閱頻道指南：Discord、Telegram、WhatsApp。
3

新增代理、帳號與繫結

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

重新啟動並驗證

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

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

使用多個代理時，每個 agentId 都會成為完全隔離的 persona：
  • 不同電話號碼/帳號（每頻道 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 帳號全域的（配對/允許清單），不是每代理。
  • 對於共享群組，請將群組繫結到一個代理，或使用廣播群組。

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

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

peer 比對

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

parentPeer 比對

討論串繼承。
3

guildId + roles

Discord 角色路由。
4

guildId

Discord。
5

teamId

Slack。
6

頻道的 accountId 比對

每帳號後援。
7

頻道層級比對

accountId: "*"。
8

預設代理

後援至 agents.list[].default，否則使用第一個清單項目，預設：main。
  • 如果多個繫結在同一層級相符，設定順序中的第一個會勝出。
  • 如果繫結設定多個比對欄位（例如 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 帳號都會對應到唯一的 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。
  • Token 位於 channels.discord.accounts.<id>.token（預設帳號可使用 DISCORD_BOT_TOKEN）。
{
  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）。
啟動 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: "1203630...@g.us" },
      },
    },
  ],

  // 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",
        },
      },
    },
  },
}

​
常見模式

依 channel 分流：將 WhatsApp 路由到快速的日常代理，將 Telegram 路由到 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: "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 規則。

​
每代理 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
        },
      },
    ],
  },
}
setupCommand 位於 sandbox.docker 底下，並在容器建立時執行一次。當解析後的 scope 是 "shared" 時，會忽略每代理的 sandbox.docker.* 覆寫。
優點：
  • 安全隔離：限制不受信任代理的工具。
  • 資源控制：將特定代理置於 sandbox，同時讓其他代理保留在主機上。
  • 彈性政策：每個代理使用不同權限。
tools.elevated 是全域且以 sender 為基準；無法針對每個代理設定。如果你需要每代理邊界，請使用 agents.list[].tools 拒絕 exec。若要針對群組指定目標，請使用 agents.list[].groupChat.mentionPatterns，讓 @mentions 清楚對應到目標代理。
詳情與範例請參閱多代理 sandbox 和工具。

​
相關