群組

OpenClaw 在各平台上統一處理群組聊天：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo。

新手入門（2 分鐘）

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

預設行為：

群組受到限制（groupPolicy: "allowlist"）。
除非你明確停用提及門檻，否則回覆需要被提及。

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

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
otherwise -> reply

Group message flow

如果你想要…

目標	要設定的內容
允許所有群組但只在 @提及時回覆	`groups: { "*": { requireMention: true } }`
停用所有群組回覆	`groupPolicy: "disabled"`
僅限特定群組	`groups: { "<group-id>": { ... } }`（沒有 `"*"` 鍵）
群組中只有你能觸發	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

工作階段金鑰

群組工作階段使用 agent:<agentId>:<channel>:group:<id> 工作階段金鑰（聊天室/頻道使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 論壇主題會在群組 ID 後加上 :topic:<threadId>，讓每個主題都有自己的工作階段。
私聊使用主要工作階段（或在設定的情況下依發送者區分）。
群組工作階段會跳過心跳檢測。

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

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

原因：在單一代理模式下，DM 通常會到達主要工作階段金鑰（agent:main:main），而群組始終使用非主要工作階段金鑰（agent:main:<channel>:group:<id>）。如果你啟用 mode: "non-main" 的沙盒功能，群組工作階段會在 Docker 中執行，而你的主要 DM 工作階段則留在主機上。

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

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

想讓「群組只能看到資料夾 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 提升
綁定掛載詳情：沙盒

顯示標籤

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": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

政策	行為
`"open"`	群組繞過允許清單；提及門檻仍然適用。
`"disabled"`	完全封鎖所有群組訊息。
`"allowlist"`	僅允許符合已設定允許清單的群組/聊天室。

注意事項：

groupPolicy 與提及門檻（要求 @提及）是分開的。
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 groupAllowFrom（後備：明確的 allowFrom）。
DM 配對核准（*-allowFrom 儲存條目）僅適用於 DM 存取；群組發送者授權仍明確依賴群組允許清單。
Discord：允許清單使用 channels.discord.guilds.<id>.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.<provider> 不存在），群組政策會回退到失敗關閉模式（通常為 allowlist），而不是繼承 channels.defaults.groupPolicy。

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

groupPolicy（open/disabled/allowlist）
群組允許清單（*.groups、*.groupAllowFrom、頻道特定的允許清單）
提及門檻（requireMention、/activation）

提及門檻（預設）

群組訊息需要被提及，除非針對個別群組覆寫。預設值在 *.groups."*" 下的各子系統中設定。

回覆 Bot 訊息視為隱式提及（當頻道支援回覆中繼資料時）。這適用於 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。

{
  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 已設定）。
Discord 的預設值在 channels.discord.guilds."*" 中（可按公會/頻道覆寫）。
群組歷史記錄上下文在各頻道間統一包裝，且僅為待處理（因提及門檻而被跳過的訊息）；使用 messages.groupChat.historyLimit 作為全域預設值，使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）作為覆寫值。設定 0 可停用。

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

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

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

注意事項：

群組/頻道工具限制是在全域/代理工具政策之外額外套用的（deny 始終優先）。
部分頻道對聊天室/頻道使用不同的巢狀結構（例如 Discord guilds.*.channels.*、Slack channels.*、MS Teams teams.*.channels.*）。

群組允許清單

當設定了 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 時，金鑰會作為群組允許清單。使用 "*" 可以在設定預設提及行為的同時允許所有群組。

常見模式（複製貼上）：

停用所有群組回覆

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

僅允許特定群組（WhatsApp）

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

允許所有群組但要求提及（明確）

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

僅擁有者能在群組中觸發（WhatsApp）

{
  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 序列。

iMessage 特定資訊

路由或設定允許清單時，建議使用 chat_id:<id>。
列出聊天：imsg chats --limit 20。
群組回覆始終發回同一個 chat_id。

WhatsApp 特定資訊

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