Groups

Groups 문서는 OpenClaw 공식 문서(channels/groups)를 한국어로 정리한 가이드입니다. Group chat behavior across surfaces (Discord/iMessage/Matrix/Microsoft Teams/QQBot/Signal/Slack/Telegram/WhatsApp/Zalo) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Group chat behavior across surfaces (Discord/iMessage/Matrix/Microsoft Teams/QQBot/Signal/Slack/Telegram/WhatsApp/Zalo)

한국어 가이드 범위: channels/groups 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Beginner intro (2 minutes)
Visible replies
Context visibility and allowlists
Session keys
Pattern: personal DMs + public groups (single agent)
Display labels
Group policy
Mention gating (default)
Scope configured mention patterns
Group/channel tool restrictions (optional)
Group allowlists
Activation (owner-only)
Context fields
iMessage specifics
WhatsApp system prompts
WhatsApp specifics
관련 문서

상세 내용

본문

OpenClaw applies the same group rules across group-capable channels, including Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, and Zalo.

Beginner intro (2 minutes)

OpenClaw "lives" on your own messaging accounts. There is no separate WhatsApp bot user: if you are in a group, OpenClaw can see that group and respond there.

주요 항목:

Groups are restricted (groupPolicy: "allowlist"); group senders are blocked until allowlisted.
Replies require a mention unless you disable mention gating for a group.
Final reply text posts to the room automatically (visibleReplies: "automatic").
DM access is controlled by *.allowFrom.
Group access is controlled by *.groupPolicy + allowlists (*.groups, *.groupAllowFrom).
Reply triggering is controlled by mention gating (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

Visible replies

For normal group/channel requests, OpenClaw defaults to messages.groupChat.visibleReplies: "automatic": the final assistant text posts to the room as the visible reply.

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

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

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

Context visibility and allowlists

Two different controls are involved in group safety:

주요 항목:

Trigger authorization: who can trigger the agent (groupPolicy, groups, groupAllowFrom, channel-specific allowlists).
Context visibility: what supplemental context is injected into the model (reply/quote text, thread history, forwarded metadata).

Mode	Behavior
`"all"` (default)	Keep supplemental context as received.
`"allowlist"`	Only inject history/thread/quote/forwarded context from allowlisted senders.
`"allowlist_quote"`	`allowlist`, plus keep the explicitly quoted/replied-to message from any sender.

Goal	What to set
Allow all groups but only reply on @mentions	`groups: { "*": { requireMention: true } }`
Disable all group replies	`groupPolicy: "disabled"`
Only specific groups	`groups: { "<group-id>": { ... } }` (no `"*"` key)
Only you can trigger in groups	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`
Reuse one trusted sender set across channels	`groupAllowFrom: ["accessGroup:operators"]`

Session keys

주요 항목:

Group sessions use agent:<agentId>:<channel>:group:<id> session keys (rooms/channels use agent:<agentId>:<channel>:channel:<id>).
Telegram forum topics add :topic:<threadId> to the group id so each topic has its own session.
Direct chats use the main session (or per-sender sessions if session.dmScope is configured).
Heartbeats run in the configured heartbeat session (default: the agent main session); group sessions do not run their own heartbeats.

Pattern: personal DMs + public groups (single agent)

Yes — this works well if your "personal" traffic is DMs and your "public" traffic is groups.

주요 항목:

DMs: full tools (host)
Groups: sandbox + restricted tools
Configuration keys and defaults: Gateway configuration
Debugging why a tool is blocked: Sandbox vs Tool Policy vs Elevated
Bind mounts details: Sandboxing

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

Display labels

주요 항목:

UI labels use displayName when available, formatted as <channel>:<token>.
#room is reserved for rooms/channels; group chats use g-<slug> (lowercase, spaces -> -, keep #@+._-). Very long opaque ids are shortened into a stable token instead of leaking full route ids into the UI.

Group policy

Control how group/room messages are handled per channel:

주요 항목:

groupPolicy is separate from mention-gating (which requires @mentions).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use groupAllowFrom (fallback: explicit allowFrom).
Signal: groupAllowFrom can match either the inbound Signal group id or the sender phone/UUID.
DM pairing approvals (*-allowFrom store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
Discord: allowlist uses channels.discord.guilds.<id>.channels.
Slack: allowlist uses channels.slack.channels.
Matrix: allowlist uses channels.matrix.groups. Use room IDs (!room:server) or aliases (#alias:server); room-name keys match only with channels.matrix.dangerouslyAllowNameMatching: true, and unresolved entries are ignored at runtime. Use channels.matrix.groupAllowFrom to restrict senders; per-room users allowlists are also supported.
Group DMs are controlled separately (channels.discord.dm.*, channels.slack.dm.*: groupEnabled, groupChannels).
Telegram: sender allowlists accept numeric user IDs only ("123456789"; telegram:/tg: prefixes are stripped case-insensitively). @username entries do not match at runtime and log a warning; setup resolves @username to IDs. Negative chat IDs belong under channels.telegram.groups, not sender allowlists.
Default is groupPolicy: "allowlist"; if your group allowlist is empty, group messages are blocked.
Runtime safety: when a provider block is completely missing (channels.<provider> absent), group policy fails closed to allowlist instead of inheriting channels.defaults.groupPolicy, and the gateway logs the fallback once per account.

Policy	Behavior
`"open"`	Groups bypass allowlists; mention-gating still applies.
`"disabled"`	Block all group messages entirely.
`"allowlist"`	Only allow groups/rooms that match the configured allowlist.

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (setup resolves @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: { 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 },
      },
    },
  },
}

Mention gating (default)

Group messages require a mention unless overridden per group. Defaults live per subsystem under *.groups."*".

Fact	Current built-in producers
Reply to the bot	Discord, Microsoft Teams, QQBot, Slack, Telegram
Quote of the bot	WhatsApp, Zalo personal
Bot joined the thread	Mattermost, Slack, Tlon

{
  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: {
    entries: {
      main: {
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    },
  },
}

Scope configured mention patterns

Configured mentionPatterns are regex fallback triggers. Use them when the platform does not expose a native bot mention, or when you want plain text such as openclaw: to count as a mention. Native platform mentions are separate: when Discord, Slack, Telegram, Matrix, Signal, or another channel can prove the message explicitly mentioned the bot, that native mention still triggers even if configured regex patterns are denied.

주요 항목:

mentionPatterns are case-insensitive safe regex patterns; invalid patterns and unsafe nested-repetition forms are ignored (with a warning).
Pattern precedence: agents.entries.*.groupChat.mentionPatterns (useful when multiple agents share a group) overrides messages.groupChat.mentionPatterns; when neither is set, patterns are derived from the agent identity name/emoji.
Mention gating is only enforced when mention detection is possible (native mentions or mentionPatterns are configured).
Allowlisting a group or sender does not disable mention gating; set that group's requireMention to false when all messages should trigger.
Automatic group chat prompt context carries the resolved silent-reply instruction every turn; workspace files should not duplicate NO_REPLY mechanics.
Groups where automatic silent replies are allowed treat clean empty or reasoning-only model turns as silent, equivalent to NO_REPLY. Direct chats never receive NO_REPLY guidance, and message-tool-only group replies stay quiet by not calling message(action=send).
Ambient always-on group chatter uses user-request semantics by default. Set messages.groupChat.unmentionedInbound: "room_event" to submit it as quiet context instead. See Ambient room events for setup examples.
Room events are not stored as fake user requests, and private assistant text from no-message-tool room events is not replayed as chat history.
Discord defaults live in channels.discord.guilds."*" (overridable per guild/channel).
Group history context is wrapped uniformly across channels. Mention-gated groups keep pending skipped messages; always-on groups may also retain recent processed room messages when the channel supports it. Use messages.groupChat.historyLimit for the global default and channels.<channel>.historyLimit (or channels.<channel>.accounts.*.historyLimit) for overrides. Set 0 to disable.

Field	Effect
`mode: "allow"`	Regex mention patterns are enabled unless the conversation ID is in `denyIn`. This is the default.
`mode: "deny"`	Regex mention patterns are disabled unless the conversation ID is in `allowIn`.
`allowIn`	Conversation IDs where regex mention patterns are enabled in deny mode.
`denyIn`	Conversation IDs where regex mention patterns are disabled. `denyIn` wins over `allowIn` if both include the same ID.

Channel	IDs used in `allowIn` / `denyIn`
Discord	Discord channel IDs.
Matrix	Matrix room IDs.
Slack	Slack channel IDs.
Telegram	Group chat IDs, or `chatId:topic:threadId` for forum topics.
WhatsApp	WhatsApp conversation IDs such as `123@g.us`.

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

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

Group/channel tool restrictions (optional)

Some channel configs support restricting which tools are available inside a specific group/room/channel.

주요 항목:

tools: allow/deny tools for the whole group (allow, alsoAllow, deny; deny wins).
toolsBySender: per-sender overrides within the group. Use explicit key prefixes: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, and "*" wildcard. Channel ids use canonical OpenClaw channel ids; aliases such as teams normalize to msteams. Legacy unprefixed keys are still accepted, matched as id: only, and log a deprecation warning.

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

Group allowlists

When channels.whatsapp.groups, channels.telegram.groups, or channels.imessage.groups is configured, the keys act as a group allowlist. Use "*" to allow all groups while still setting default mention behavior.

{
      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 (owner-only)

Group owners can toggle per-group activation with a standalone message:

주요 항목:

/activation mention
/activation always

Context fields

The agent system prompt includes a group intro on the first turn of a new group session (and after /activation changes). It reminds the model to respond like a human, minimize empty lines and follow normal chat spacing, and avoid typing literal \n sequences. Channels whose declared table mode does not preserve native or raw tables also discourage Markdown tables. Channel-sourced group names and participant labels are rendered as fenced untrusted metadata, not inline system instructions.

주요 항목:

ChatType=group
GroupSubject (if known)
GroupMembers (if known)
WasMentioned (mention gating result)
Telegram forum topics also include MessageThreadId and IsForum.

iMessage specifics

주요 항목:

Prefer chat_id:<id> when routing or allowlisting.
List chats: imsg chats --limit 20.
Group replies always go back to the same chat_id.

WhatsApp system prompts

See WhatsApp for the canonical WhatsApp system prompt rules, including group and direct prompt resolution, wildcard behavior, and account override semantics.

WhatsApp specifics

See Group messages for WhatsApp-only behavior (history injection, mention handling details).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/channels/groups
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

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

Groups

핵심 요약

Group chat behavior across surfaces (Discord/iMessage/Matrix/Microsoft Teams/QQBot/Signal/Slack/Telegram/WhatsApp/Zalo)

한국어 가이드 범위: channels/groups 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Beginner intro (2 minutes)
Visible replies
Context visibility and allowlists
Session keys
Pattern: personal DMs + public groups (single agent)
Display labels
Group policy
Mention gating (default)
Scope configured mention patterns
Group/channel tool restrictions (optional)
Group allowlists
Activation (owner-only)
Context fields
iMessage specifics
WhatsApp system prompts
WhatsApp specifics
관련 문서

상세 내용

본문

OpenClaw applies the same group rules across group-capable channels, including Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, and Zalo.

Beginner intro (2 minutes)

OpenClaw "lives" on your own messaging accounts. There is no separate WhatsApp bot user: if you are in a group, OpenClaw can see that group and respond there.

주요 항목:

Groups are restricted (groupPolicy: "allowlist"); group senders are blocked until allowlisted.
Replies require a mention unless you disable mention gating for a group.
Final reply text posts to the room automatically (visibleReplies: "automatic").
DM access is controlled by *.allowFrom.
Group access is controlled by *.groupPolicy + allowlists (*.groups, *.groupAllowFrom).
Reply triggering is controlled by mention gating (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

Visible replies

For normal group/channel requests, OpenClaw defaults to messages.groupChat.visibleReplies: "automatic": the final assistant text posts to the room as the visible reply.

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

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

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

Context visibility and allowlists

Two different controls are involved in group safety:

주요 항목:

Trigger authorization: who can trigger the agent (groupPolicy, groups, groupAllowFrom, channel-specific allowlists).
Context visibility: what supplemental context is injected into the model (reply/quote text, thread history, forwarded metadata).

Mode	Behavior
`"all"` (default)	Keep supplemental context as received.
`"allowlist"`	Only inject history/thread/quote/forwarded context from allowlisted senders.
`"allowlist_quote"`	`allowlist`, plus keep the explicitly quoted/replied-to message from any sender.

Goal	What to set
Allow all groups but only reply on @mentions	`groups: { "*": { requireMention: true } }`
Disable all group replies	`groupPolicy: "disabled"`
Only specific groups	`groups: { "<group-id>": { ... } }` (no `"*"` key)
Only you can trigger in groups	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`
Reuse one trusted sender set across channels	`groupAllowFrom: ["accessGroup:operators"]`

Session keys

주요 항목:

Group sessions use agent:<agentId>:<channel>:group:<id> session keys (rooms/channels use agent:<agentId>:<channel>:channel:<id>).
Telegram forum topics add :topic:<threadId> to the group id so each topic has its own session.
Direct chats use the main session (or per-sender sessions if session.dmScope is configured).
Heartbeats run in the configured heartbeat session (default: the agent main session); group sessions do not run their own heartbeats.

Pattern: personal DMs + public groups (single agent)

Yes — this works well if your "personal" traffic is DMs and your "public" traffic is groups.

주요 항목:

DMs: full tools (host)
Groups: sandbox + restricted tools
Configuration keys and defaults: Gateway configuration
Debugging why a tool is blocked: Sandbox vs Tool Policy vs Elevated
Bind mounts details: Sandboxing

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

Display labels

주요 항목:

UI labels use displayName when available, formatted as <channel>:<token>.
#room is reserved for rooms/channels; group chats use g-<slug> (lowercase, spaces -> -, keep #@+._-). Very long opaque ids are shortened into a stable token instead of leaking full route ids into the UI.

Group policy

Control how group/room messages are handled per channel:

주요 항목:

groupPolicy is separate from mention-gating (which requires @mentions).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use groupAllowFrom (fallback: explicit allowFrom).
Signal: groupAllowFrom can match either the inbound Signal group id or the sender phone/UUID.
DM pairing approvals (*-allowFrom store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
Discord: allowlist uses channels.discord.guilds.<id>.channels.
Slack: allowlist uses channels.slack.channels.
Matrix: allowlist uses channels.matrix.groups. Use room IDs (!room:server) or aliases (#alias:server); room-name keys match only with channels.matrix.dangerouslyAllowNameMatching: true, and unresolved entries are ignored at runtime. Use channels.matrix.groupAllowFrom to restrict senders; per-room users allowlists are also supported.
Group DMs are controlled separately (channels.discord.dm.*, channels.slack.dm.*: groupEnabled, groupChannels).
Telegram: sender allowlists accept numeric user IDs only ("123456789"; telegram:/tg: prefixes are stripped case-insensitively). @username entries do not match at runtime and log a warning; setup resolves @username to IDs. Negative chat IDs belong under channels.telegram.groups, not sender allowlists.
Default is groupPolicy: "allowlist"; if your group allowlist is empty, group messages are blocked.
Runtime safety: when a provider block is completely missing (channels.<provider> absent), group policy fails closed to allowlist instead of inheriting channels.defaults.groupPolicy, and the gateway logs the fallback once per account.

Policy	Behavior
`"open"`	Groups bypass allowlists; mention-gating still applies.
`"disabled"`	Block all group messages entirely.
`"allowlist"`	Only allow groups/rooms that match the configured allowlist.

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (setup resolves @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: { 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 },
      },
    },
  },
}

Mention gating (default)

Group messages require a mention unless overridden per group. Defaults live per subsystem under *.groups."*".

Fact	Current built-in producers
Reply to the bot	Discord, Microsoft Teams, QQBot, Slack, Telegram
Quote of the bot	WhatsApp, Zalo personal
Bot joined the thread	Mattermost, Slack, Tlon

{
  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: {
    entries: {
      main: {
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    },
  },
}

Scope configured mention patterns

주요 항목:

mentionPatterns are case-insensitive safe regex patterns; invalid patterns and unsafe nested-repetition forms are ignored (with a warning).
Pattern precedence: agents.entries.*.groupChat.mentionPatterns (useful when multiple agents share a group) overrides messages.groupChat.mentionPatterns; when neither is set, patterns are derived from the agent identity name/emoji.
Mention gating is only enforced when mention detection is possible (native mentions or mentionPatterns are configured).
Allowlisting a group or sender does not disable mention gating; set that group's requireMention to false when all messages should trigger.
Automatic group chat prompt context carries the resolved silent-reply instruction every turn; workspace files should not duplicate NO_REPLY mechanics.
Groups where automatic silent replies are allowed treat clean empty or reasoning-only model turns as silent, equivalent to NO_REPLY. Direct chats never receive NO_REPLY guidance, and message-tool-only group replies stay quiet by not calling message(action=send).
Ambient always-on group chatter uses user-request semantics by default. Set messages.groupChat.unmentionedInbound: "room_event" to submit it as quiet context instead. See Ambient room events for setup examples.
Room events are not stored as fake user requests, and private assistant text from no-message-tool room events is not replayed as chat history.
Discord defaults live in channels.discord.guilds."*" (overridable per guild/channel).
Group history context is wrapped uniformly across channels. Mention-gated groups keep pending skipped messages; always-on groups may also retain recent processed room messages when the channel supports it. Use messages.groupChat.historyLimit for the global default and channels.<channel>.historyLimit (or channels.<channel>.accounts.*.historyLimit) for overrides. Set 0 to disable.

Field	Effect
`mode: "allow"`	Regex mention patterns are enabled unless the conversation ID is in `denyIn`. This is the default.
`mode: "deny"`	Regex mention patterns are disabled unless the conversation ID is in `allowIn`.
`allowIn`	Conversation IDs where regex mention patterns are enabled in deny mode.
`denyIn`	Conversation IDs where regex mention patterns are disabled. `denyIn` wins over `allowIn` if both include the same ID.

Channel	IDs used in `allowIn` / `denyIn`
Discord	Discord channel IDs.
Matrix	Matrix room IDs.
Slack	Slack channel IDs.
Telegram	Group chat IDs, or `chatId:topic:threadId` for forum topics.
WhatsApp	WhatsApp conversation IDs such as `123@g.us`.

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

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

Group/channel tool restrictions (optional)

Some channel configs support restricting which tools are available inside a specific group/room/channel.

주요 항목:

tools: allow/deny tools for the whole group (allow, alsoAllow, deny; deny wins).
toolsBySender: per-sender overrides within the group. Use explicit key prefixes: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, and "*" wildcard. Channel ids use canonical OpenClaw channel ids; aliases such as teams normalize to msteams. Legacy unprefixed keys are still accepted, matched as id: only, and log a deprecation warning.

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

Group allowlists

{
      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 (owner-only)

Group owners can toggle per-group activation with a standalone message:

주요 항목:

/activation mention
/activation always

Context fields

주요 항목:

ChatType=group
GroupSubject (if known)
GroupMembers (if known)
WasMentioned (mention gating result)
Telegram forum topics also include MessageThreadId and IsForum.

iMessage specifics

주요 항목:

Prefer chat_id:<id> when routing or allowlisting.
List chats: imsg chats --limit 20.
Group replies always go back to the same chat_id.

WhatsApp system prompts

See WhatsApp for the canonical WhatsApp system prompt rules, including group and direct prompt resolution, wildcard behavior, and account override semantics.

WhatsApp specifics

See Group messages for WhatsApp-only behavior (history injection, mention handling details).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/channels/groups
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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

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

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

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

Groups

핵심 요약

문서 구성

상세 내용

본문

Beginner intro (2 minutes)

Visible replies

Context visibility and allowlists

Session keys

Pattern: personal DMs + public groups (single agent)

Display labels

Group policy

Mention gating (default)

Scope configured mention patterns

Group/channel tool restrictions (optional)

Group allowlists

Activation (owner-only)

Context fields

iMessage specifics

WhatsApp system prompts

WhatsApp specifics

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Groups

핵심 요약

문서 구성

상세 내용

본문

Beginner intro (2 minutes)

Visible replies

Context visibility and allowlists

Session keys

Pattern: personal DMs + public groups (single agent)

Display labels

Group policy

Mention gating (default)

Scope configured mention patterns

Group/channel tool restrictions (optional)

Group allowlists

Activation (owner-only)

Context fields

iMessage specifics

WhatsApp system prompts

WhatsApp specifics

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드