forked from Selig/openclaw-skill
Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
106 lines
15 KiB
JSON
Executable File
106 lines
15 KiB
JSON
Executable File
{
|
||
"title": "Groups",
|
||
"content": "OpenClaw treats group chats consistently across surfaces: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams.\n\n## Beginner intro (2 minutes)\n\nOpenClaw “lives” on your own messaging accounts. There is no separate WhatsApp bot user.\nIf **you** are in a group, OpenClaw can see that group and respond there.\n\n* Groups are restricted (`groupPolicy: \"allowlist\"`).\n* Replies require a mention unless you explicitly disable mention gating.\n\nTranslation: allowlisted senders can trigger OpenClaw by mentioning it.\n\n> TL;DR\n>\n> * **DM access** is controlled by `*.allowFrom`.\n> * **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).\n> * **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).\n\nQuick flow (what happens to a group message):\n\n<img alt=\"Group message flow\" />\n\n| Goal | What to set |\n| -------------------------------------------- | ---------------------------------------------------------- |\n| Allow all groups but only reply on @mentions | `groups: { \"*\": { requireMention: true } }` |\n| Disable all group replies | `groupPolicy: \"disabled\"` |\n| Only specific groups | `groups: { \"<group-id>\": { ... } }` (no `\"*\"` key) |\n| Only you can trigger in groups | `groupPolicy: \"allowlist\"`, `groupAllowFrom: [\"+1555...\"]` |\n\n* Group sessions use `agent:<agentId>:<channel>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).\n* Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.\n* Direct chats use the main session (or per-sender if configured).\n* Heartbeats are skipped for group sessions.\n\n## Pattern: personal DMs + public groups (single agent)\n\nYes — this works well if your “personal” traffic is **DMs** and your “public” traffic is **groups**.\n\nWhy: in single-agent mode, DMs typically land in the **main** session key (`agent:main:main`), while groups always use **non-main** session keys (`agent:main:<channel>:group:<id>`). If you enable sandboxing with `mode: \"non-main\"`, those group sessions run in Docker while your main DM session stays on-host.\n\nThis gives you one agent “brain” (shared workspace + memory), but two execution postures:\n\n* **DMs**: full tools (host)\n* **Groups**: sandbox + restricted tools (Docker)\n\n> If you need truly separate workspaces/personas (“personal” and “public” must never mix), use a second agent + bindings. See [Multi-Agent Routing](/concepts/multi-agent).\n\nExample (DMs on host, groups sandboxed + messaging-only tools):\n\nWant “groups can only see folder X” instead of “no host access”? Keep `workspaceAccess: \"none\"` and mount only allowlisted paths into the sandbox:\n\n* Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)\n* Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)\n* Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)\n\n* UI labels use `displayName` when available, formatted as `<channel>:<token>`.\n* `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).\n\nControl how group/room messages are handled per channel:\n\n| Policy | Behavior |\n| ------------- | ------------------------------------------------------------ |\n| `\"open\"` | Groups bypass allowlists; mention-gating still applies. |\n| `\"disabled\"` | Block all group messages entirely. |\n| `\"allowlist\"` | Only allow groups/rooms that match the configured allowlist. |\n\n* `groupPolicy` is separate from mention-gating (which requires @mentions).\n* WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: use `groupAllowFrom` (fallback: explicit `allowFrom`).\n* Discord: allowlist uses `channels.discord.guilds.<id>.channels`.\n* Slack: allowlist uses `channels.slack.channels`.\n* Matrix: allowlist uses `channels.matrix.groups` (room IDs, aliases, or names). Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.\n* Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`).\n* Telegram allowlist can match user IDs (`\"123456789\"`, `\"telegram:123456789\"`, `\"tg:123456789\"`) or usernames (`\"@alice\"` or `\"alice\"`); prefixes are case-insensitive.\n* Default is `groupPolicy: \"allowlist\"`; if your group allowlist is empty, group messages are blocked.\n\nQuick mental model (evaluation order for group messages):\n\n1. `groupPolicy` (open/disabled/allowlist)\n2. group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist)\n3. mention gating (`requireMention`, `/activation`)\n\n## Mention gating (default)\n\nGroup messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups.\"*\"`.\n\nReplying to a bot message counts as an implicit mention (when the channel supports reply metadata). This applies to Telegram, WhatsApp, Slack, Discord, and Microsoft Teams.\n\n* `mentionPatterns` are case-insensitive regexes.\n* Surfaces that provide explicit mentions still pass; patterns are a fallback.\n* Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).\n* Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).\n* Discord defaults live in `channels.discord.guilds.\"*\"` (overridable per guild/channel).\n* Group history context is wrapped uniformly across channels and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.\n\n## Group/channel tool restrictions (optional)\n\nSome channel configs support restricting which tools are available **inside a specific group/room/channel**.\n\n* `tools`: allow/deny tools for the whole group.\n* `toolsBySender`: per-sender overrides within the group (keys are sender IDs/usernames/emails/phone numbers depending on the channel). Use `\"*\"` as a wildcard.\n\nResolution order (most specific wins):\n\n1. group/channel `toolsBySender` match\n2. group/channel `tools`\n3. default (`\"*\"`) `toolsBySender` match\n4. default (`\"*\"`) `tools`\n\n* Group/channel tool restrictions are applied in addition to global/agent tool policy (deny still wins).\n* Some channels use different nesting for rooms/channels (e.g., Discord `guilds.*.channels.*`, Slack `channels.*`, MS Teams `teams.*.channels.*`).\n\nWhen `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.\n\nCommon intents (copy/paste):\n\n1. Disable all group replies\n\n2. Allow only specific groups (WhatsApp)\n\n3. Allow all groups but require mention (explicit)\n\n4. Only the owner can trigger in groups (WhatsApp)\n\n## Activation (owner-only)\n\nGroup owners can toggle per-group activation:\n\n* `/activation mention`\n* `/activation always`\n\nOwner is determined by `channels.whatsapp.allowFrom` (or the bot’s self E.164 when unset). Send the command as a standalone message. Other surfaces currently ignore `/activation`.\n\nGroup inbound payloads set:\n\n* `ChatType=group`\n* `GroupSubject` (if known)\n* `GroupMembers` (if known)\n* `WasMentioned` (mention gating result)\n* Telegram forum topics also include `MessageThreadId` and `IsForum`.\n\nThe agent system prompt includes a group intro on the first turn of a new group session. It reminds the model to respond like a human, avoid Markdown tables, and avoid typing literal `\\n` sequences.\n\n## iMessage specifics\n\n* Prefer `chat_id:<id>` when routing or allowlisting.\n* List chats: `imsg chats --limit 20`.\n* Group replies always go back to the same `chat_id`.\n\n## WhatsApp specifics\n\nSee [Group messages](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).",
|
||
"code_samples": [
|
||
{
|
||
"code": "groupPolicy? disabled -> drop\ngroupPolicy? allowlist -> group allowed? no -> drop\nrequireMention? yes -> mentioned? no -> store for context only\notherwise -> reply",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Want “groups can only see folder X” instead of “no host access”? Keep `workspaceAccess: \"none\"` and mount only allowlisted paths into the sandbox:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Related:\n\n* Configuration keys and defaults: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)\n* Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)\n* Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)\n\n## Display labels\n\n* UI labels use `displayName` when available, formatted as `<channel>:<token>`.\n* `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).\n\n## Group policy\n\nControl how group/room messages are handled per channel:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "| Policy | Behavior |\n| ------------- | ------------------------------------------------------------ |\n| `\"open\"` | Groups bypass allowlists; mention-gating still applies. |\n| `\"disabled\"` | Block all group messages entirely. |\n| `\"allowlist\"` | Only allow groups/rooms that match the configured allowlist. |\n\nNotes:\n\n* `groupPolicy` is separate from mention-gating (which requires @mentions).\n* WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: use `groupAllowFrom` (fallback: explicit `allowFrom`).\n* Discord: allowlist uses `channels.discord.guilds.<id>.channels`.\n* Slack: allowlist uses `channels.slack.channels`.\n* Matrix: allowlist uses `channels.matrix.groups` (room IDs, aliases, or names). Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.\n* Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`).\n* Telegram allowlist can match user IDs (`\"123456789\"`, `\"telegram:123456789\"`, `\"tg:123456789\"`) or usernames (`\"@alice\"` or `\"alice\"`); prefixes are case-insensitive.\n* Default is `groupPolicy: \"allowlist\"`; if your group allowlist is empty, group messages are blocked.\n\nQuick mental model (evaluation order for group messages):\n\n1. `groupPolicy` (open/disabled/allowlist)\n2. group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist)\n3. mention gating (`requireMention`, `/activation`)\n\n## Mention gating (default)\n\nGroup messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups.\"*\"`.\n\nReplying to a bot message counts as an implicit mention (when the channel supports reply metadata). This applies to Telegram, WhatsApp, Slack, Discord, and Microsoft Teams.",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Notes:\n\n* `mentionPatterns` are case-insensitive regexes.\n* Surfaces that provide explicit mentions still pass; patterns are a fallback.\n* Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).\n* Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).\n* Discord defaults live in `channels.discord.guilds.\"*\"` (overridable per guild/channel).\n* Group history context is wrapped uniformly across channels and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.\n\n## Group/channel tool restrictions (optional)\n\nSome channel configs support restricting which tools are available **inside a specific group/room/channel**.\n\n* `tools`: allow/deny tools for the whole group.\n* `toolsBySender`: per-sender overrides within the group (keys are sender IDs/usernames/emails/phone numbers depending on the channel). Use `\"*\"` as a wildcard.\n\nResolution order (most specific wins):\n\n1. group/channel `toolsBySender` match\n2. group/channel `tools`\n3. default (`\"*\"`) `toolsBySender` match\n4. default (`\"*\"`) `tools`\n\nExample (Telegram):",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Notes:\n\n* Group/channel tool restrictions are applied in addition to global/agent tool policy (deny still wins).\n* Some channels use different nesting for rooms/channels (e.g., Discord `guilds.*.channels.*`, Slack `channels.*`, MS Teams `teams.*.channels.*`).\n\n## Group allowlists\n\nWhen `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.\n\nCommon intents (copy/paste):\n\n1. Disable all group replies",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "2. Allow only specific groups (WhatsApp)",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "3. Allow all groups but require mention (explicit)",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "4. Only the owner can trigger in groups (WhatsApp)",
|
||
"language": "unknown"
|
||
}
|
||
],
|
||
"headings": [
|
||
{
|
||
"level": "h2",
|
||
"text": "Beginner intro (2 minutes)",
|
||
"id": "beginner-intro-(2-minutes)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Session keys",
|
||
"id": "session-keys"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Pattern: personal DMs + public groups (single agent)",
|
||
"id": "pattern:-personal-dms-+-public-groups-(single-agent)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Display labels",
|
||
"id": "display-labels"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Group policy",
|
||
"id": "group-policy"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Mention gating (default)",
|
||
"id": "mention-gating-(default)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Group/channel tool restrictions (optional)",
|
||
"id": "group/channel-tool-restrictions-(optional)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Group allowlists",
|
||
"id": "group-allowlists"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Activation (owner-only)",
|
||
"id": "activation-(owner-only)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Context fields",
|
||
"id": "context-fields"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "iMessage specifics",
|
||
"id": "imessage-specifics"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "WhatsApp specifics",
|
||
"id": "whatsapp-specifics"
|
||
}
|
||
],
|
||
"url": "llms-txt#groups",
|
||
"links": []
|
||
} |