OpenClaw 群組設定指南：5 分鐘內完成權限控管

OpenClaw 能夠在 Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp 與 Zalo 等多種通訊平台上，以一致的方式處理群組對話。

初學者入門 (2 分鐘)

OpenClaw 是直接「寄生」在你的個人通訊帳號上運作的，系統中並不存在一個獨立的 WhatsApp 機器人使用者。只要你身處於某個群組中，OpenClaw 就能夠看見該群組的訊息並進行回應。

預設行為如下：

群組預設為受限狀態 (groupPolicy: "allowlist")。
回覆訊息時需要標記（mention），除非你明確停用了標記限制。

翻譯：只有在白名單中的發送者，才能透過標記 OpenClaw 來觸發它的回應。

簡而言之

DM 存取權由 *.allowFrom 控制。

群組存取權由 *.groupPolicy 加上白名單 (*.groups, *.groupAllowFrom) 控制。

回覆觸發由標記限制 (requireMention, /activation) 控制。

快速流程（群組訊息的處理邏輯）：

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

內容可見度與白名單

群組安全涉及兩項不同的控制機制：

觸發授權：誰可以觸發代理程式（透過 groupPolicy、groups、groupAllowFrom 以及頻道特定的白名單）。
內容可見度：哪些補充內容會被注入到模型中（例如回覆文字、引用、串連歷史紀錄、轉寄的元數據）。

預設情況下，OpenClaw 會優先考慮正常的聊天行為，並盡量保持接收到的內容原樣。這意味著白名單主要決定了誰可以觸發動作，而不是針對每一則引用或歷史片段的通用遮蔽邊界。

目前的行為取決於頻道類型：

部分頻道已經針對特定路徑的補充內容應用了基於發送者的過濾（例如 Slack 串連種子、Matrix 回覆/串連查詢）。
其他頻道仍會將引用/回覆/轉寄的內容原樣傳遞。

強化方向（規劃中）：

contextVisibility: "all"（預設）保持目前接收到的原始行為。
contextVisibility: "allowlist" 過濾補充內容，僅允許白名單內的發送者。
contextVisibility: "allowlist_quote" 是 allowlist 的延伸，額外允許一則明確的引用/回覆。

在這些強化模型於各個頻道一致實作之前，請預期不同平台之間會存在行為差異。

Group message flow

如果你想達成…

目標	設定方式
允許所有群組，但僅在 @標記時回覆	`groups: { "*": { requireMention: true } }`
停用所有群組回覆	`groupPolicy: "disabled"`
僅限特定群組	`groups: { "<group-id>": { ... } }` (不使用 `"*"` 鍵)
僅限你本人在群組中觸發	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Session keys

群組 session 使用 agent:<agentId>:<channel>:group:<id> 作為 session keys（房間/頻道則使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 論壇主題會在群組 ID 後加上 :topic:<threadId>，確保每個主題都有獨立的 session。
直接對話（DM）使用主 session（若有設定則按發送者區分）。
群組 session 會跳過心跳檢測（Heartbeats）。

模式：個人 DM + 公開群組（單一代理程式）

沒錯，如果你的「個人」流量是 DM，而「公開」流量是群組，這種模式運作得很好。

原因：在單一代理模式下，DM 通常會進入 main session key (agent:main:main)，而群組總是使用 非 main 的 session keys (agent:main:<channel>:group:<id>)。如果你啟用 mode: "non-main" 的沙盒模式，這些群組 session 會在設定的沙盒後端執行，而你的主要 DM session 則保留在主機上。如果你沒有選擇其他後端，Docker 將作為預設後端。

這為你提供了一個代理「大腦」（共享工作區 + 記憶體），但有兩種執行姿態：

DM：完整工具（主機）。
群組：沙盒 + 受限工具。

如果你需要真正分開的工作區/角色（「個人」與「公開」絕不能混用），請使用第二個代理程式 + 綁定。請參閱 Multi-Agent Routing。

範例（DM 在主機上，群組在沙盒中且僅限訊息傳遞工具）：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

想要「群組只能看到資料夾 X」而不是「完全無法存取主機」嗎？請保持 workspaceAccess: "none" 並僅將白名單路徑掛載到沙盒中：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

相關連結：

設定鍵與預設值：Gateway configuration
偵錯工具為何被封鎖：Sandbox vs Tool Policy vs Elevated
掛載細節：Sandboxing

AI Setup Assistant

顯示標籤

UI 標籤會優先使用 displayName（若有的話），並以 <channel>:<token> 的格式呈現。請注意，#room 是保留給聊天室或頻道使用的；群組對話則會使用 g-<slug> 格式（全小寫，空格轉換為 -，並保留 #@+._- 等符號）。

群組政策

你可以透過設定來控制每個頻道如何處理群組或聊天室訊息，確保只有你允許的來源能發送訊息。

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

政策	行為
`"open"`	群組會繞過白名單；但提及限制（mention-gating）仍然適用。
`"disabled"`	完全封鎖所有群組訊息。
`"allowlist"`	僅允許符合已設定白名單的群組或聊天室。

注意事項：

groupPolicy 與提及限制（需要 @mentions 的功能）是分開的。
WhatsApp、Telegram、Signal、iMessage、Microsoft Teams 與 Zalo：請使用 groupAllowFrom（備用方案為明確的 allowFrom）。
私訊配對核准（*-allowFrom 儲存項目）僅適用於私訊存取；群組發送者授權必須明確設定於群組白名單中。
Discord：白名單使用 channels.discord.guilds.<id>.channels。
Slack：白名單使用 channels.slack.channels。
Matrix：白名單使用 channels.matrix.groups。建議優先使用房間 ID 或別名；加入房間名稱的查詢為盡力而為，執行時會忽略無法解析的名稱。使用 channels.matrix.groupAllowFrom 來限制發送者；同時也支援針對個別房間的 users 白名單。
群組私訊（Group DMs）是分開控制的（channels.discord.dm.*、channels.slack.dm.*）。
Telegram 白名單可比對使用者 ID（例如 "123456789"、"telegram:123456789"、"tg:123456789"）或使用者名稱（"@alice" 或 "alice"）；前綴不區分大小寫。
預設值為 groupPolicy: "allowlist"；如果你的群組白名單為空，群組訊息將會被封鎖。
執行時安全性：當供應商區塊完全缺失（即 channels.<provider> 不存在時），群組政策會退回到預設的關閉模式（通常為 allowlist），而不會繼承 channels.defaults.groupPolicy。

快速心智模型（群組訊息的評估順序）：

groupPolicy（open/disabled/allowlist）
群組白名單（*.groups、*.groupAllowFrom、頻道專屬白名單）
提及限制（requireMention、/activation）

AI Setup Assistant

提及限制 (Mention gating)

OpenClaw 的提及限制功能讓群組訊息預設需要被提及才能觸發，除非你在特定群組中進行了覆蓋設定。這些預設值會根據不同的子系統存放在 *.groups."*" 路徑下。

當頻道支援回覆元數據時，回覆機器人訊息會被視為隱含的提及。在那些會公開引用元數據的頻道中，引用機器人訊息同樣可以被視為隱含的提及。目前內建支援此功能的頻道包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 以及 ZaloUser。

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

注意事項：

mentionPatterns 是不區分大小寫的正規表達式；無效的模式或不安全的巢狀重複形式將會被忽略。
提供明確提及功能的介面仍然有效；這些模式僅作為備用方案。
代理層級覆蓋：可使用 agents.list[].groupChat.mentionPatterns（當多個代理共享同一個群組時非常實用）。
只有在能夠偵測到提及（原生提及或已設定 mentionPatterns）時，提及限制才會強制執行。
Discord 的預設值存放在 channels.discord.guilds."*"（可在每個伺服器或頻道進行覆蓋）。
群組歷史記錄上下文在各個頻道間統一封裝，且僅包含 pending-only（因提及限制而被跳過的訊息）；請使用 messages.groupChat.historyLimit 設定全域預設值，並使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）進行覆蓋。設定為 0 即可停用。

群組與頻道工具限制 (Group/channel tool restrictions)

部分頻道配置支援限制在特定群組、聊天室或頻道中可使用的工具。這能讓你更精細地控管 OpenClaw 在不同環境下的操作權限。

tools：允許或拒絕整個群組的工具使用。
toolsBySender：針對群組內特定發送者的覆蓋設定。請使用明確的鍵值前綴：id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 以及 "*" 通用字元。舊版未加前綴的鍵值仍被接受，並會被視為 id: 進行匹配。

解析順序（越具體優先級越高）：

群組/頻道 toolsBySender 匹配
群組/頻道 tools
預設 ("*") toolsBySender 匹配
預設 ("*") tools

範例（Telegram）：

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

注意事項：

群組/頻道工具限制會與全域或代理層級的工具政策疊加執行（拒絕權限的設定優先級最高）。
部分頻道針對聊天室或頻道使用不同的巢狀結構（例如 Discord 的 guilds.*.channels.*、Slack 的 channels.*，以及 Microsoft Teams 的 teams.*.channels.*）。

AI Setup Assistant

群組白名單 (Group allowlists)

當你設定了 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 時，這些 key 會作為群組的白名單來運作。你可以使用 "*" 來允許所有群組，同時仍然可以設定預設的提及（mention）行為。

開發者常有的誤解是：DM 配對批准並不等同於群組授權。對於支援 DM 配對的頻道，配對儲存庫僅會解鎖 DM 功能。群組指令仍然需要來自設定白名單（例如 groupAllowFrom 或該頻道對應的設定備援）的明確群組發送者授權。

以下是常見的設定需求（可直接複製貼上）：

停用所有群組回覆

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

僅允許特定群組 (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

允許所有群組但強制要求提及 (明確設定)

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

僅擁有者能在群組中觸發 (WhatsApp)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

啟用設定 (僅限擁有者)

群組擁有者可以針對個別群組切換啟用狀態：

使用 /activation mention 指令。
使用 /activation always 指令。

擁有者身分是由 channels.whatsapp.allowFrom 決定（若未設定，則為機器人本身的 E.164 號碼）。請將指令作為獨立訊息發送。目前其他介面會忽略 /activation 指令。

Context fields

當你使用 OpenClaw 處理群組訊息時，系統會自動填充一系列的上下文欄位，幫助你的模型更精準地理解對話背景。這些欄位能讓你的機器人區分個人對話與群組互動，並根據群組屬性做出適當反應。

ChatType=group：標記當前訊息來源為群組。
GroupSubject：如果系統已知，會顯示群組名稱。
GroupMembers：如果系統已知，會列出群組成員。
WasMentioned：顯示提及過濾的結果。
Telegram 論壇主題還會包含 MessageThreadId 和 IsForum。

針對特定頻道的注意事項：

BlueBubbles 可以選擇在填充 GroupMembers 之前，從本地聯絡人資料庫中豐富未命名的 macOS 群組參與者資訊。此功能預設為關閉，且僅在正常的群組過濾流程完成後才會執行。

代理系統提示詞（system prompt）會在新的群組對話開始時包含一段群組介紹。它會提醒模型像人類一樣回應，避免使用 JSON 或 Markdown 表格，盡量減少空行並遵循正常的對話間距，同時避免輸入字面上的 \n 序列。

iMessage specifics

在使用 OpenClaw 處理 iMessage 訊息時，建議優先使用特定的聊天 ID 來進行路由或白名單設定，以確保訊息傳遞的準確性。

在進行路由或設定白名單時，請優先使用 chat_id:<id>。
若要列出聊天記錄，請使用以下 CLI 指令：

imsg chats --limit 20

群組回覆將始終發送回同一個 chat_id。

WhatsApp specifics

關於 WhatsApp 的特殊行為，例如歷史記錄注入（history injection）或提及處理細節，請參閱 Group messages 的詳細說明。這些設定能確保 OpenClaw 在處理 WhatsApp 群組時，能正確解析訊息來源並維持對話的連貫性。

AI Setup Assistant

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。