Principle:Openclaw Openclaw Group Chat Configuration
| Knowledge Sources | |
|---|---|
| Domains | Messaging, Configuration, Group Chat |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Group chat configuration governs how an OpenClaw bot behaves in group conversations, including require-mention gating, per-group policies, tool restrictions, and system prompt overrides.
Description
Group conversations present unique challenges for bot behavior that do not apply to direct messages. In a group, the bot typically should not respond to every message -- it should wait to be explicitly mentioned or addressed. Additionally, different groups may require different tool access levels, different system prompts, or different participant restrictions. OpenClaw addresses these needs through a layered group configuration system.
The require-mention setting is the primary gating mechanism for group messages. When enabled (the default), the bot will only process messages that explicitly mention it (e.g., @botname in Telegram or Discord). This prevents the bot from responding to unrelated group chatter. The setting can be configured at three levels of specificity: the channel account level (global default for all groups), the per-group level (override for a specific group), and the wildcard group level ("*" entry in the groups config, which serves as a fallback default).
Beyond mention gating, each group entry can specify: a tool policy that restricts which tools the bot may use in that group, a tools-by-sender policy that applies different tool restrictions based on who sent the message, a skills list that limits available skills, a system prompt override that changes the bot's personality or instructions for that specific group, and an enabled flag to temporarily disable the bot in a group without removing its config.
The resolution order follows a cascading priority: explicit per-group config takes precedence over the wildcard ("*") group config, which takes precedence over the channel account-level defaults. This allows operators to set broad defaults and selectively override them for specific groups.
Usage
Group chat configuration is defined within the channel account's groups record in the OpenClaw config file. Each key in the record is a group identifier (platform-specific: chat ID for Telegram, guild/channel ID for Discord, etc.), and the value contains the group-specific settings. The configuration is consulted at message processing time to determine whether to process a message and how to handle it.
Theoretical Basis
The group configuration model follows a cascading resolution with override ordering pattern:
- Per-group config -- If a group entry exists for the exact group ID, its settings are used. Fields like
requireMention,tools, andsystemPromptare read from this entry. - Wildcard default -- If the specific group has no entry but a
"*"wildcard entry exists, its settings serve as the default for all groups. - Account-level default -- If neither a specific group entry nor a wildcard exists, the account-level
requireMentionandgroupPolicysettings apply. - Override ordering -- The
resolveChannelGroupRequireMentionfunction supports anoverrideOrderparameter that controls whether a programmatic override (e.g., from the channel adapter) takes precedence before or after the config-based value. The default"after-config"order lets config values win, with the override serving as a fallback.
The mention gating itself is resolved through a separate function (resolveMentionGating) that considers whether mention detection is supported on the platform, whether the bot was actually mentioned, and whether an implicit mention or bypass condition applies.