群組

OpenClaw 會在各介面一致地處理群組聊天：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。

初學者簡介（2 分鐘）

OpenClaw「存在於」你自己的訊息帳號中。沒有獨立的 WhatsApp bot 使用者。如果你在某個群組中，OpenClaw 就能看到該群組並在那裡回應。

預設行為：

• 群組受到限制（groupPolicy: "allowlist"）。
• 除非你明確停用提及閘控，否則回覆需要被提及。
• 群組/頻道中的一般最終回覆預設為私人。可見的聊天室輸出會使用 message 工具。

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

快速流程（群組訊息會發生什麼事）：

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlyotherwise -> reply

可見回覆

對於群組/頻道聊天室，OpenClaw 預設使用 messages.groupChat.visibleReplies: "message_tool"。 openclaw doctor --fix 會將此預設值寫入已設定但省略該值的頻道設定中。 這表示代理仍會處理該回合，並可更新記憶/工作階段狀態，但其一般最終答案不會自動張貼回聊天室。若要公開發言，代理會使用 message(action=send)。

此預設值取決於能可靠呼叫工具的模型/執行階段。如果記錄顯示 assistant 文字但 didSendViaMessagingTool: false，代表模型以 私人方式回答，而不是呼叫訊息工具。這不是 Discord/Slack/Telegram 傳送失敗。請為群組/頻道工作階段使用工具呼叫可靠的模型， 或將 messages.groupChat.visibleReplies: "automatic" 設定為還原舊版可見的 最終回覆。

如果訊息工具在目前的工具政策下不可用，OpenClaw 會退回到自動可見回覆，而不是靜默抑制回應。 openclaw doctor 會警告此不一致。

對於直接聊天和任何其他來源回合，使用 messages.visibleReplies: "message_tool" 可在全域套用相同的僅工具可見回覆行為。測試框架也可以選擇此值作為未設定時的預設值；Codex 測試框架會對 Codex 模式直接聊天這麼做。messages.groupChat.visibleReplies 仍是群組/頻道聊天室更具體的覆寫。

這取代了舊模式：強制模型在大多數潛伏模式回合回答 NO_REPLY。在僅工具模式中，沒有可見動作只代表不呼叫訊息工具。

在僅工具模式中，代理工作時仍會送出輸入中指示器。這些回合的預設群組輸入模式會從 "message" 升級為 "instant"，因為代理決定是否呼叫訊息工具之前，可能永遠不會出現一般 assistant 訊息文字。明確的輸入模式設定仍優先。

若要為群組/頻道聊天室還原舊版自動最終回覆：

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

檔案儲存後，Gateway 會熱重載 messages 設定。只有在部署中停用檔案監看或設定重載時才需要重新啟動。

若要要求每個來源聊天的可見輸出都經由訊息工具：

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

原生斜線命令（Discord、Telegram，以及其他支援原生命令的介面）會繞過 visibleReplies: "message_tool"，並一律可見回覆，讓頻道原生的命令 UI 取得預期回應。這只適用於已驗證的原生命令回合；以文字輸入的 /... 命令和一般聊天回合仍遵循設定的群組預設值。

脈絡可見性與允許清單

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

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

OpenClaw 預設優先採用一般聊天行為，並大致保留收到的脈絡。這表示允許清單主要決定誰可以觸發動作，而不是每個引用或歷史片段的通用遮蔽邊界。

如果你想要...

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

工作階段金鑰

• 群組工作階段使用 agent:<agentId>:<channel>:group:<id> 工作階段金鑰（聊天室/頻道使用 agent:<agentId>:<channel>:channel:<id>）。
• Telegram 論壇主題會將 :topic:<threadId> 加到群組 ID，因此每個主題都有自己的工作階段。
• 直接聊天使用主要工作階段（或在已設定時按傳送者分開）。
• 群組工作階段會略過 Heartbeat。

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

可以，若你的「個人」流量是 DM，而「公開」流量是群組，這很適合。

原因：在單一代理模式中，DM 通常會落在主要工作階段金鑰（agent:main:main），而群組一律使用非主要工作階段金鑰（agent:main:<channel>:group:<id>）。如果你以 mode: "non-main" 啟用沙箱化，這些群組工作階段會在設定的沙箱後端中執行，而你的主要 DM 工作階段會留在主機上。如果你沒有選擇後端，Docker 是預設後端。

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

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

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

相關：

• 設定鍵與預設值：Gateway 設定
• 偵錯工具被封鎖的原因：沙箱 vs 工具政策 vs 提權
• 繫結掛載詳細資訊：沙箱化

顯示標籤

• 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: ["[email protected]"],    },    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 },      },    },  },}

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

提及控管（預設）

除非逐群組覆寫，群組訊息需要提及。預設值位於各子系統的 *.groups."*" 底下。

回覆 bot 訊息在通道支援回覆中繼資料時，會算作隱含提及。在公開引用中繼資料的通道上，引用 bot 訊息也可以算作隱含提及。目前內建情況包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },        "[email protected]": { 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,        },      },    ],  },}

群組/通道工具限制（選用）

某些通道設定支援限制特定群組/聊天室/通道內可用的工具。

• tools：允許/拒絕整個群組的工具。
• 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: {        "[email protected]": { requireMention: true },        "[email protected]": { requireMention: false },      },    },  },}

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

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

啟用（僅擁有者）

群組擁有者可以切換逐群組啟用：

• /activation mention
• /activation always

擁有者由 channels.whatsapp.allowFrom 判定（未設定時則使用 bot 自身的 E.164）。請將命令作為獨立訊息傳送。其他介面目前會忽略 /activation。

內容欄位

群組傳入承載會設定：

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

代理系統提示詞會在新群組工作階段的第一輪包含群組簡介。它會提醒模型像人一樣回應、避免 Markdown 表格、盡量減少空行並遵循一般聊天間距，以及避免輸入字面上的 \n 序列。通道來源的群組名稱和參與者標籤會以 fenced 不受信任中繼資料呈現，而不是內嵌系統指令。

iMessage 特定事項

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

WhatsApp 系統提示詞

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

WhatsApp 特定事項

請參閱 群組訊息，了解 WhatsApp 專屬行為（歷史注入、提及處理詳細資料）。

相關

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