群組

OpenClaw 會在支援群組的頻道中套用相同的群組規則，包括 Discord、iMessage、Matrix、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 和 Zalo。

對於應持續啟用，且除非代理明確傳送可見訊息，否則只提供安靜情境資訊的聊天室，請參閱環境聊天室事件。

初學者簡介（2 分鐘）

OpenClaw「存在」於你自己的訊息帳號中。它沒有獨立的 WhatsApp 機器人使用者：只要你在群組中，OpenClaw 就能看到該群組並在其中回覆。

預設行為：

• 群組受到限制（groupPolicy: "allowlist"）；在加入允許清單前，群組傳送者會遭到封鎖。
• 除非你停用該群組的提及閘控，否則回覆必須先提及代理。
• 最終回覆文字會自動發布到聊天室（visibleReplies: "automatic"）。

換句話說：允許清單中的傳送者可以透過提及 OpenClaw 來觸發它。

快速流程（群組訊息的處理方式）：

groupPolicy？disabled -> 捨棄groupPolicy？allowlist -> 群組是否獲准？否 -> 捨棄requireMention？yes -> 是否被提及？否 -> 僅儲存為情境資訊提及／回覆／命令／私訊 -> 使用者請求持續啟用的群組對話 -> 使用者請求，或在已設定時作為聊天室事件

可見回覆

對於一般群組／頻道請求，OpenClaw 預設使用 messages.groupChat.visibleReplies: "automatic"：最終助理文字會作為可見回覆發布到聊天室。

如果共享聊天室應讓代理透過呼叫 message(action=send) 自行決定何時發言，請使用 messages.groupChat.visibleReplies: "message_tool"。此模式最適合能可靠使用工具的模型（例如 GPT-5.6 Sol）。如果模型未呼叫工具，卻傳回具有實質內容的最終文字，OpenClaw 會將該文字保持為私密，而不會發布到聊天室。

對於無法可靠遵循僅限工具傳遞方式的模型或執行階段，請使用 "automatic"：一般最終文字會直接發布到聊天室，而代理仍可針對無法隨最終文字一併傳遞的檔案、圖片或其他附件呼叫 message(action=send)。

如果目前的工具原則不允許使用訊息工具，OpenClaw 會改用自動可見回覆，而不會無聲地隱藏回應。openclaw doctor 會針對此不一致情況發出警告。

對於直接聊天和其他任何來源事件，messages.visibleReplies: "message_tool" 會在全域套用相同的僅限工具行為；messages.groupChat.visibleReplies 仍是群組／頻道聊天室更具體的覆寫設定。內部 WebChat 的直接對話輪次預設會自動傳遞最終回覆，讓 Pi 和 Codex 採用相同的可見回覆合約。

僅限工具模式取代了過去在多數潛水模式對話輪次中強制模型回答 NO_REPLY 的模式。在僅限工具模式中，提示不會定義 NO_REPLY 合約；不產生任何可見內容，僅代表未呼叫訊息工具。

由外掛擁有的對話繫結是例外。外掛繫結討論串並接管傳入對話輪次後，外掛傳回的回覆就是可見的繫結回應；它不需要 message(action=send)。該回覆是外掛執行階段的輸出，而不是模型的私密最終文字。

直接群組請求仍會傳送輸入中指示器。啟用後，環境中的持續啟用聊天室事件仍會保持嚴格且安靜，除非代理呼叫訊息工具。

工作階段預設會隱藏詳細的工具／進度摘要。偵錯時，可使用 /verbose on（或 /verbose full）在目前工作階段中顯示這些摘要，並使用 /verbose off 恢復為僅顯示最終回覆的行為。詳細狀態以工作階段為單位，且在直接聊天、群組、頻道和論壇主題中的運作方式相同。

若要將未提及代理的持續啟用群組對話作為安靜的聊天室情境資訊，而不是使用者請求提交，請使用環境聊天室事件：

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

預設值為 unmentionedInbound: "user_request"。提及訊息、命令、中止請求和私訊仍會作為使用者請求。

若要要求群組／頻道請求的可見輸出必須透過訊息工具傳送：

{  messages: {    groupChat: {      visibleReplies: "message_tool",    },  },}

若要對每個來源聊天提出此要求：

{  messages: {    visibleReplies: "message_tool",  },}

儲存檔案後，閘道無須重新啟動即可載入 messages 設定變更。只有在停用設定重新載入功能（gateway.reload.mode: "off"）時才需要重新啟動。

命令對話輪次會略過 visibleReplies: "message_tool"，並一律以可見方式回覆：原生斜線命令（Discord、Telegram，以及其他支援原生命令的介面）與已授權的文字 /... 命令，都會將回應發布到來源聊天。在群組中，未授權的文字 /... 對話輪次仍僅能使用訊息工具；一般聊天對話輪次則遵循已設定的預設值。

情境資訊可見性與允許清單

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

• 觸發授權：誰可以觸發代理（groupPolicy、groups、groupAllowFrom、各頻道專用的允許清單）。
• 情境資訊可見性：哪些補充情境資訊會注入模型（回覆／引用文字、討論串歷史記錄、轉寄中繼資料）。

OpenClaw 預設會原樣保留收到的情境資訊：允許清單決定誰可以觸發動作，而不是模型可以看到哪些引用或歷史記錄片段。若也要篩選補充情境資訊，請設定 contextVisibility：

你可以為每個頻道（channels.<channel>.contextVisibility）、每個帳號（channels.<channel>.accounts.<accountId>.contextVisibility）或全域（channels.defaults.contextVisibility）設定此項目。會擷取補充情境資訊的頻道（Discord、Feishu、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp）會在建立傳入情境資訊時套用此原則；未知的原則組合會以關閉方式失敗並省略情境資訊。

如果你想要……

如需可重複使用的傳送者允許清單，請參閱存取群組。

工作階段鍵

• 群組工作階段使用 agent:<agentId>:<channel>:group:<id> 工作階段鍵（聊天室／頻道使用 agent:<agentId>:<channel>:channel:<id>）。
• Telegram 論壇主題會將 :topic:<threadId> 加入群組 ID，讓每個主題都有自己的工作階段。
• 直接聊天使用主要工作階段（如果已設定 session.dmScope，則使用各傳送者專屬工作階段）。
• 心跳偵測會在已設定的心跳偵測工作階段中執行（預設為代理的主要工作階段）；群組工作階段不會執行自己的心跳偵測。

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

可以——如果你的「個人」流量是私訊，而「公開」流量是群組，這種模式相當適合。

原因是：在單一代理模式中，私訊通常會進入主要工作階段鍵（agent:main:main），而群組一律使用非主要工作階段鍵（agent:main:<channel>:group:<id>）。如果你使用 mode: "non-main" 啟用沙箱，這些群組工作階段會在已設定的沙箱後端執行，而你的主要私訊工作階段仍會在主機上執行。如果你未選擇後端，預設會使用 Docker。

這樣可以讓你擁有一個代理「大腦」（共享工作區與記憶），但採用兩種執行方式：

• 私訊：完整工具（主機）
• 群組：沙箱 + 受限工具

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // 群組／頻道屬於非主要工作階段 -> 在沙箱中執行        scope: "session", // 最強隔離（每個群組／頻道各使用一個容器）        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // 如果 allow 非空，其他所有項目都會遭到封鎖（deny 仍具有優先權）。        allow: ["group:messaging", "group:sessions"],        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],      },    },  },}

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

相關資訊：

• 設定鍵與預設值：閘道設定
• 偵錯工具遭封鎖的原因：沙箱、工具原則與提高權限的差異
• 繫結掛載詳細資訊：沙箱化

顯示標籤

• 可用時，UI 標籤會使用 displayName，並格式化為 <channel>:<token>。
• #room 保留供聊天室／頻道使用；群組聊天使用 g-<slug>（小寫、空格 -> -、保留 #@+._-）。非常長且不透明的 ID 會縮短為穩定權杖，避免在 UI 中洩漏完整路由 ID。

群組原則

控制各頻道處理群組／聊天室訊息的方式：

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // 數字 Telegram 使用者 ID（設定程序會將 @username 解析為 ID）    },    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: { enabled: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { enabled: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

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

提及閘門（預設）

除非針對個別群組覆寫，否則群組訊息必須包含提及。預設值位於各子系統的 *.groups."*" 下。

當頻道提供回覆中繼資料時，回覆機器人的訊息會視為隱含提及；在提供引用中繼資料的頻道中，引用機器人的訊息也可視為提及。目前內建支援的情況包括：Discord、Microsoft Teams、QQ Bot、Slack、Telegram、WhatsApp，以及 Zalo Personal。

{  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 是正規表示式的備援觸發條件。當平台 未提供原生機器人提及，或希望讓 openclaw: 等純文字 也算作提及時，請使用這些模式。原生平台提及是獨立的： 當 Discord、Slack、Telegram、Matrix、Signal 或其他頻道可以確認訊息 明確提及機器人時，即使已設定的正規表示式模式遭到拒絕， 該原生提及仍會觸發。

預設情況下，只要頻道將提供者與對話資訊傳入提及偵測，已設定的提及模式就會套用。若要避免寬泛的模式在每個群組中喚醒代理程式，請使用 channels.<channel>.mentionPatterns 依頻道限制其範圍。

若某個頻道預設應停用正規表示式提及模式，請使用 mode: "deny"，然後透過 allowIn 為特定聊天室選擇啟用：

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

使用預設的 mode: "allow"（或省略 mode），讓正規表示式提及模式廣泛套用，然後在訊息吵雜的聊天室中使用 denyIn 關閉它們：

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

政策解析：

目前支援的範圍式正規表示式政策：

若該頻道支援多個帳號，帳號層級的頻道設定可在 channels.<channel>.accounts.<accountId>.mentionPatterns 下設定相同政策。對該帳號而言，帳號政策優先於頂層頻道政策。

群組／頻道工具限制（選用）

部分頻道設定支援限制特定群組／聊天室／頻道內可使用的工具。

• tools：允許／拒絕整個群組使用工具（allow、alsoAllow、deny；拒絕優先）。
• toolsBySender：群組內依傳送者設定的覆寫。請使用明確的鍵前綴：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName>，以及 "*" 萬用字元。頻道 ID 使用標準 OpenClaw 頻道 ID；teams 等別名會正規化為 msteams。仍接受舊版無前綴的鍵，但只會將其視為 id: 進行比對，並記錄淘汰警告。

解析順序（最具體者優先）：

範例（Telegram）：

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

群組允許清單

設定 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 時，這些鍵會作為群組允許清單。使用 "*" 可允許所有群組，同時仍可設定預設提及行為。

常見用途（複製／貼上）：

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

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

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

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

啟用（僅限擁有者）

群組擁有者可使用獨立訊息切換各群組的啟用模式：

• /activation mention
• /activation always

/activation 是核心中受擁有者限制的命令，且僅適用於群組聊天。擁有者是指符合 commands.ownerAllowFrom 的傳送者；頻道 allowFrom 清單只控制一般頻道與命令存取。對於會查閱已儲存模式的頻道（Google Chat、QQ Bot、Telegram、WhatsApp），該模式會覆寫該群組的 requireMention，而所有頻道的群組系統提示開場內容都會反映目前的模式。

上下欄位

群組傳入承載資料會設定：

• ChatType=group
• GroupSubject（若已知）
• GroupMembers（若已知）
• WasMentioned（提及閘控結果）
• Telegram 論壇主題也會包含 MessageThreadId 和 IsForum。

代理程式系統提示會在新群組工作階段的第一輪（以及 /activation 變更後）加入群組開場內容。它會提醒模型以真人方式回應、盡量減少空白行並遵循一般聊天間距，以及避免輸入字面上的 \n 序列。非 Telegram 群組也不建議使用 Markdown 表格；Telegram 的富文字指引則來自 Telegram 頻道提示。源自頻道的群組名稱與參與者標籤會呈現為有圍欄的未受信任中繼資料，而非行內系統指示。

iMessage 特定事項

• 進行路由或加入允許清單時，優先使用 chat_id:<id>。
• 列出聊天：imsg chats --limit 20。
• 群組回覆一律傳回相同的 chat_id。

WhatsApp 系統提示

如需 WhatsApp 系統提示的標準規則，包括群組與直接提示的解析、萬用字元行為及帳號覆寫語意，請參閱 WhatsApp。

WhatsApp 特定事項

如需 WhatsApp 專屬行為（歷史記錄注入、提及處理細節），請參閱群組訊息。

相關內容

• 廣播群組
• 頻道路由
• 群組訊息
• 配對