From 2cf6b5061466fde46cfe8afc4425b44eebc0dbeb Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 25 Jul 2026 06:43:02 -0700 Subject: [PATCH] docs(discord): document channel-allowlist and ambient room event pitfalls (#113692) * docs(discord): document channel-allowlist and ambient room event pitfalls Three gating behaviors that silently produce a mute or blind agent: - A guild channels map is an allowlist. Adding one entry denies every unlisted channel rather than leaving them at guild defaults; the "*" wildcard key keeps the rest of the guild reachable. - requireMention: true drops unmentioned messages before they can become room events, so an ambient agent has no room backlog at all. - Room events post via message(action=send), but the message tool ships only in the messaging profile; a coding-profile agent listens and can never speak. Adds matching Discord failure-signature rows to channel troubleshooting. * docs: regenerate docs map for new Discord and ambient headings --- docs/channels/ambient-room-events.md | 22 +++++++++++++++++++++ docs/channels/discord.md | 29 ++++++++++++++++++++++++++++ docs/channels/troubleshooting.md | 15 ++++++++------ docs/docs_map.md | 2 ++ 4 files changed, 62 insertions(+), 6 deletions(-) diff --git a/docs/channels/ambient-room-events.md b/docs/channels/ambient-room-events.md index 57df25079b7a..180bb599b600 100644 --- a/docs/channels/ambient-room-events.md +++ b/docs/channels/ambient-room-events.md @@ -32,6 +32,28 @@ Set the global group-chat behavior: Then make the room always-on by disabling mention gating for that room. The room must still pass its normal `groupPolicy`, room allowlist, and sender allowlist. +## Prerequisites + +Two settings silently disable ambient room events even when `unmentionedInbound: "room_event"` is set. + +**Mention gating must be off for the room.** `requireMention: true` drops unmentioned messages before routing, so they never become room events. The agent then has no room backlog at all — it only ever sees messages that mentioned it. If the agent reports that it cannot see recent room history, check mention gating before anything else. + +**The agent needs the `message` tool.** Room events use strict visible delivery, so posting requires `message(action=send)`. The `message` tool ships in the `messaging` tool profile; the `minimal` and `coding` profiles do not include it. An agent on `tools.profile: "coding"` will listen to room events and can never speak. Grant it explicitly when the profile omits it: + +```json5 +{ + agents: { + entries: { + "": { + tools: { alsoAllow: ["message"] }, + }, + }, + }, +} +``` + +Check the effective surface with `openclaw agents list` and a probe turn rather than assuming the profile includes it. + After saving the config, the Gateway hot-applies `messages` settings. Restart only when file watching or config reload is disabled (`gateway.reload.mode: "off"`). ## What changes diff --git a/docs/channels/discord.md b/docs/channels/discord.md index 5cb9343e40cd..87473f744623 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -590,6 +590,35 @@ Example: +### Guild channel maps are allowlists + +A guild entry with no `channels` map lets the bot work in every channel it can see, subject to the guild's `requireMention` and `users` rules. **Adding even one channel entry turns the map into an allowlist**: any channel not matched by an entry is denied, not merely left at guild defaults. + +This surprises people who add one channel to give it special settings and find the bot has gone silent everywhere else. Use the `"*"` wildcard key to keep the rest of the guild reachable: + +```json5 +{ + channels: { + discord: { + guilds: { + YOUR_SERVER_ID: { + requireMention: true, + users: ["YOUR_USER_ID"], + channels: { + // always-on room: everyone in it can talk to the bot, no mention needed + YOUR_CHANNEL_ID: { enabled: true, requireMention: false, users: ["*"] }, + // every other channel keeps the guild defaults + "*": { enabled: true, requireMention: true }, + }, + }, + }, + }, + }, +} +``` + +Channel entries override guild-level values, so a channel entry with `users: ["*"]` opens that one room to any sender even when the guild `users` list is narrow. Entries match by channel ID, name, or slug, and a thread falls back to its parent channel's entry. + ### Role-based agent routing Use `bindings[].match.roles` to route Discord guild members to different agents by role ID. Role-based bindings accept role IDs only and are evaluated after peer or parent-peer bindings and before guild-only bindings. If a binding also sets other match fields (for example `peer` + `guildId` + `roles`), all configured fields must match. diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index afedb49eb5c1..92051a17f003 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -80,12 +80,15 @@ Full troubleshooting: [Telegram troubleshooting](/channels/telegram#troubleshoot ### Discord failure signatures -| Symptom | Fastest check | Fix | -| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Bot online but no guild replies | `openclaw channels status --probe` | Allow guild/channel and verify message content intent. | -| Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. | -| Typing/token usage but no Discord message | Check whether this is an ambient room event or an opted-in `message_tool` room where the model missed `message(action=send)` | Inspect the gateway verbose log for suppressed final payload metadata, verify `messages.groupChat.unmentionedInbound`, read [Ambient room events](/channels/ambient-room-events), or keep `messages.groupChat.visibleReplies: "automatic"` for normal group requests. | -| DM replies missing | `openclaw pairing list discord` | Approve DM pairing or adjust DM policy. | +| Symptom | Fastest check | Fix | +| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Bot online but no guild replies | `openclaw channels status --probe` | Allow guild/channel and verify message content intent. | +| Group messages ignored | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. | +| Typing/token usage but no Discord message | Check whether this is an ambient room event or an opted-in `message_tool` room where the model missed `message(action=send)` | Inspect the gateway verbose log for suppressed final payload metadata, verify `messages.groupChat.unmentionedInbound`, read [Ambient room events](/channels/ambient-room-events), or keep `messages.groupChat.visibleReplies: "automatic"` for normal group requests. | +| DM replies missing | `openclaw pairing list discord` | Approve DM pairing or adjust DM policy. | +| Bot silent in channels that used to work | Check whether the guild entry gained a `channels` map | A channel map is an allowlist: unlisted channels are denied. Add a `"*"` wildcard entry. See [Guild channel maps are allowlists](/channels/discord#guild-channel-maps-are-allowlists). | +| Agent cannot see room history or attachments from other bots | Check the room's `requireMention` and the account's `allowBots` | `requireMention: true` drops unmentioned messages before they become room events, so there is no backlog. Bot-authored messages and their attachments need `allowBots` (`"mentions"` is the safer setting). See [Ambient room events](/channels/ambient-room-events). | +| Agent watches an ambient room but never posts | Check the agent's tool profile for the `message` tool | Room events require `message(action=send)`, which the `minimal` and `coding` profiles omit. Grant `tools.alsoAllow: ["message"]` for that agent. | Full troubleshooting: [Discord troubleshooting](/channels/discord#troubleshooting) diff --git a/docs/docs_map.md b/docs/docs_map.md index e47973b83871..7e95e2dc7a9e 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -247,6 +247,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - Route: /channels/ambient-room-events - Headings: - H2: Recommended setup + - H2: Prerequisites - H2: What changes - H2: Discord example - H2: Slack example @@ -353,6 +354,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`. - H2: Forum channels - H2: Interactive components - H2: Access control and routing + - H3: Guild channel maps are allowlists - H3: Role-based agent routing - H2: Native commands and command auth - H2: Feature details