群組

OpenClaw 在所有表面上對待群組聊天的方式是一致的：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。

對於除非代理程式明確傳送可見訊息否則應提供安靜內容的常駐房間，請參閱 Ambient room events。

初學者介紹（2 分鐘）

OpenClaw「寄居」在您自己的訊息帳號上。沒有單獨的 WhatsApp 機器人使用者。如果您在某個群組中，OpenClaw 就能看到該群組並在那裡回應。

預設行為：

• 群組受到限制 (groupPolicy: "allowlist")。
• 除非您明確停用提及閘控，否則回覆需要提及。
• 群組/頻道中的可見回覆預設使用 message 工具。

翻譯：允許清單上的發送者可以透過提及來觸發 OpenClaw。

Note

TL;DR

• DM 存取權由 *.allowFrom 控制。
• 群組存取權由 *.groupPolicy + 允許清單（*.groups、*.groupAllowFrom）控制。
• 回覆觸發由提及閘控（requireMention、/activation）控制。

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

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
mention/reply/command/DM -> user request
always-on group chatter -> user request, or room event when configured

可見回覆

對於一般的群組/頻道請求，OpenClaw 預設為 messages.groupChat.visibleReplies: "automatic"。最終的助手文字會透過舊版的可見回覆路徑發佈，除非您將房間設定為僅使用訊息工具輸出。

當共享房間應讓代理程式透過呼叫 message(action=send) 來決定何時發言時，請使用 messages.groupChat.visibleReplies: "message_tool"。這對於由最新一代、工具可靠的模型（如 GPT 5.5）支援的群組房間最有效。如果模型未使用該工具並傳回實質的最終文字，OpenClaw 會將該最終文字保持私密，而不是發佈到房間中。

如果在現行工具政策下無法使用訊息工具，OpenClaw 將會 回退到自動可見回覆，而不是靜默抑制回應。 openclaw doctor 會針對此不符之處發出警告。

對於直接聊天和任何其他來源事件，請使用 messages.visibleReplies: "message_tool" 在全域範圍內套用相同的僅工具可見回覆行為。包括 Codex 在內的一些連接器，若未設定此項，預設也會將直接/來源聊天設為透過訊息工具傳送。將 messages.visibleReplies: "automatic" 設為 true 以強制使用舊的自動最終回覆路徑。messages.groupChat.visibleReplies 仍是針對群組/頻道房間的更具體覆寫設定。

這取代了舊的模式，即強制模型在大多數潛伏模式回合中回答 NO_REPLY。在僅工具模式中，不做任何可見的事情僅意味著不呼叫訊息工具。

對於直接的群組請求，仍然會傳送輸入指示器。當啟用環境式常駐房間事件時，除非代理程式呼叫訊息工具，否則它們將保持嚴格且安靜。

若要將未被提及的常駐群組閒聊作為安靜的房間內容提交，而不是作為使用者請求，請使用 Ambient room events：

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

預設值為 unmentionedInbound: "user_request"。

被提及的訊息、指令、中止請求和私人訊息仍保持為使用者請求。

若要求群組/頻道請求的可見輸出必須透過訊息工具進行：

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

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

若要要求每個來源聊天的可見輸出都必須透過訊息工具：

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

原生斜線指令（Discord、Telegram 和其他具有原生指令支援的介面）會略過 visibleReplies: "message_tool" 並始終可見地回覆，以便頻道原生指令 UI 能獲得其預期的回應。這僅適用於已驗證的原生指令回合；文字輸入的 /... 指令和一般聊天回合仍遵循設定的群組預設值。

內容可見性與允許清單

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

• 觸發授權：誰可以觸發代理程式（groupPolicy、groups、groupAllowFrom、頻道特定允許清單）。
• 內容可見性：哪些補充內容會被注入到模型中（回覆文字、引用、執行緒歷史、轉發的中繼資料）。

預設情況下，OpenClaw 優先考慮一般聊天行為，並主要保持接收到的內容不變。這意味著允許清單主要決定誰可以觸發動作，而不是對每個被引用或歷史片段設定通用的編輯邊界。

目前行為因頻道而異

• 部分頻道已經在特定路徑中對補充內容套用基於發送者的過濾（例如 Slack 執行緒植入、Matrix 回覆/執行緒查詢）。
• 其他頻道仍會照樣傳遞引用/回覆/轉發內容。

Hardening direction (planned)

• contextVisibility: "all" (預設) 保持當前接收到的行為。
• contextVisibility: "allowlist" 將補充內容過濾為僅限允許清單中的發送者。
• contextVisibility: "allowlist_quote" 是 allowlist 加上一個明確的引用/回覆例外。

在此強化模型在各頻道一致實作之前，預期會因介面不同而有差異。

如果您想要…

目標	設定方法
允許所有群組，但僅在 @提及 時回覆	groups: { "*": { requireMention: true } }
停用所有群組回覆	groupPolicy: "disabled"
僅限特定群組	groups: { "<group-id>": { ... } } (無 "*" 金鑰)
僅限您能在群組中觸發	groupPolicy: "allowlist"、groupAllowFrom: ["+1555..."]
跨通道重複使用同一個受信任的發送者集合	groupAllowFrom: ["accessGroup:operators"]

若要使用可重複使用的發送者允許清單，請參閱存取群組。

Session keys

• 群組會話使用 agent:<agentId>:<channel>:group:<id> 會話金鑰 (房間/頻道則使用 agent:<agentId>:<channel>:channel:<id>)。
• Telegram 論壇主題會將 :topic:<threadId> 加入至群組 ID，因此每個主題都有自己的會話。
• 直接聊天使用主 session（若已設定，則為每位發送者使用個別 session）。
• 群組會話會跳過心跳。

Pattern: personal DMs + public groups (single agent)

是的 — 如果您的「個人」流量是 DMs 而「公開」流量是 groups，這個方式運作良好。

原因：在單一代理程式模式下，私人訊息 (DM) 通常會進入 主要 (main) 會話金鑰 (agent:main:main)，而群組則一律使用 非主要 (non-main) 會話金鑰 (agent:main:<channel>:group:<id>)。如果您使用 mode: "non-main" 啟用沙盒化，這些群組會話將會在設定的沙盒後端執行，而您的主要私人訊息會話則保持在主機上。如果您未選擇後端，則預設為 Docker。

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

• DMs：完整工具（主機）
• Groups：沙箱 + 受限工具

Note

如果您需要完全分開的工作區/角色人格 (「個人」與「公開」絕對不可混用)，請使用第二個代理程式 + 繫結。請參閱

多代理程式路由

。

DMs on host, groups sandboxedGroups see only an allowlisted folder

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

相關：

• 設定金鑰與預設值：閘道設定
• 除錯工具被封鎖的原因：沙盒 vs 工具政策 vs 提升權限
• Bind 掛載詳細資訊：沙盒化

顯示標籤

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

原則	行為
"open"	群組略過允許清單；提及閘門仍然適用。
"disabled"	完全封鎖所有群組訊息。
"allowlist"	僅允許符合設定允許清單的群組/房間。

Per-channel notes

• groupPolicy 與提及閘控分開（後者需要 @mentions）。
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 groupAllowFrom（後備：明確的 allowFrom）。
• Signal：groupAllowFrom 可以符合傳入的 Signal 群組 ID 或發送者電話/UUID。
• DM 配對核准（*-allowFrom 儲存條目）僅適用於 DM 存取；群組發送者授權仍對群組允許清單保持明確規定。
• Discord：允許清單使用 `channels.discord.guilds.

.channels。 - Slack：允許清單使用 channels.slack.channels。 - Matrix：允許清單使用 channels.matrix.groups。建議優先使用房間 ID 或別名；已加入房間名稱查詢為盡力而為，無法解析的名稱會在執行時被忽略。使用 channels.matrix.groupAllowFrom限制發送者；也支援每個房間的users 允許清單。 - 群組 DM 受到單獨控制（channels.discord.dm.，channels.slack.dm.）。 - Telegram 允許清單可以符合使用者 ID（”123456789”，”telegram:123456789”，”tg:123456789”）或使用者名稱（”@alice”或”alice”）；前綴不區分大小寫。 - 預設值為 groupPolicy: “allowlist”；如果您的群組允許清單為空，則會封鎖群組訊息。 - 執行時安全性：當提供者區塊完全遺失（channels.

不存在）時，群組原則會退回到失敗關閉模式（通常是allowlist），而不是繼承 channels.defaults.groupPolicy`。

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

1. groupPolicy

   groupPolicy (open/disabled/allowlist)。

2. Group allowlists

   群組允許清單（*.groups，*.groupAllowFrom，特定頻道允許清單）。

3. 提及閘道

   提及閘道（requireMention、/activation）。

提及閘控（預設）

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

當頻道支援回覆中繼資料時，回覆機器人訊息會被視為隱含提及。在公開引用中繼資料的頻道上，引用機器人訊息也可視為隱含提及。目前內建的案例包括 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,
        },
      },
    ],
  },
}

提及控制備註

• mentionPatterns 是不區分大小寫的安全正規表達式模式；無效的模式和不安全的巢狀重複形式會被忽略。
• 提供明確提及的介面仍然會通過；模式是備用方案。
• 每個代理的覆寫：agents.list[].groupChat.mentionPatterns （當多個代理共用一個群組時很有用）。
• 僅在可以偵測提及時才會強制執行提及控制（已設定原生提及或 mentionPatterns）。
• 將群組或發送者加入允許清單並不會停用提及控制；當所有訊息都應觸發時，將該群組的 requireMention 設定為 false。
• 自動群組聊天提示詞上下文每回合都會攜帶已解析的靜默回覆指令；工作區檔案不應重複 NO_REPLY 機制。
• 允許自動靜默回覆的群組會將純空白或僅推理的模型回合視為靜默，等同於 NO_REPLY。直接聊天永遠不會接收 NO_REPLY 指引，且僅使用訊息工具的群組回覆會因不呼叫 message(action=send) 而保持安靜。
• 環境型常開群組閒聊預設使用使用者請求語意。設定 messages.groupChat.unmentionedInbound: "room_event" 以將其作為安靜上下文提交。請參閱 Ambient room events 了解設定範例。
• 房間事件不會儲存為虛假的使用者請求，且來自無訊息工具房間事件的私人助理文字不會作為聊天歷史重播。
• Discord 預設值位於 channels.discord.guilds."*" （可依伺服器/頻道覆寫）。
• 群組歷史上下文在各頻道間以統一方式包裝。提及控制的群組會保留待處理的略過訊息；常開群組在頻道支援時也可能保留最近的已處理房間訊息。使用 messages.groupChat.historyLimit 作為全域預設值，並使用 `channels.

.historyLimit（或channels.

.accounts.*.historyLimit）進行覆寫。設定 0` 以停用。

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

某些通道設定支援限制在特定群組/房間/通道內可使用的工具。

• tools：針對整個群組允許/拒絕工具。
• toolsBySender：群組內的每個發送者覆寫。使用明確的鍵前綴：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 和 "*" 萬用字元。頻道 ID 使用標準的 OpenClaw 頻道 ID；別名如 teams 會正規化為 msteams。舊版無前綴的鍵仍被接受，並且僅作為 id: 進行匹配。

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

1. Group toolsBySender

   群組/頻道 toolsBySender 比對。

2. Group tools

   群組/頻道 tools。

3. Default toolsBySender

   預設 ("*") toolsBySender 比對。

4. Default tools

   預設 ("*") tools。

範例 (Telegram)：

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

Note

群組/頻道工具限制會與全域/代理工具策略一起套用（拒絕權限仍優先）。部分頻道對房間/頻道使用不同的巢狀結構（例如：Discord

guilds.*.channels.*

、Slack

channels.*

、Microsoft Teams

teams.*.channels.*

）。

群組允許清單

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

Warning

常見誤解：DM 配對批准不等同於群組授權。對於支援 DM 配對的頻道，配對儲存僅解鎖 DM。群組指令仍需要來自配置允許清單（如

groupAllowFrom

）或該頻道文件化配置後援的明確群組發送者授權。

常見意圖（複製/貼上）：

停用所有群組回覆僅允許特定群組 (WhatsApp)允許所有群組但需要提及僅限所有者觸發 (WhatsApp)

{
  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 決定（若未設定，則為機器人自身的 E.164 號碼）。請將該指令作為獨立訊息發送。其他介面目前會忽略 /activation。

Context 欄位

群組傳入的 Payload 會設定：

• ChatType=group
• GroupSubject（如果已知）
• GroupMembers（如果已知）
• WasMentioned（提及閘道結果）
• Telegram 論壇主題還包含 MessageThreadId 和 IsForum。

代理系統提示會在新群組會話的第一輪包含群組介紹。它會提醒模型像人類一樣回應，避免使用 Markdown 表格，盡量減少空行並遵循正常的聊天間距，並避免輸入字面意義的 \n 序列。來自頻道的群組名稱和參與者標籤會被渲染為圍欄式的不受信任元數據，而非內聯系統指令。

iMessage 詳細資訊

• 在路由或設定允許清單時，請優先使用 chat_id:<id>。
• 列出聊天：imsg chats --limit 20。
• 群組回覆總是會發回同一個 chat_id。

WhatsApp 系統提示

關於正式的 WhatsApp 系統提示規則，包括群組和直接提示解析、萬用字元行為以及帳號覆寫語義，請參閱 WhatsApp。

WhatsApp 詳細資訊

關於 WhatsApp 專屬的行為（歷史記錄注入、提及處理細節），請參閱 Group messages。

相關

• Broadcast groups
• Channel routing
• Group messages
• Pairing