mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-28 05:16:23 -06:00
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
This commit is contained in:
Peter Steinberger
committed by
GitHub
GitHub
parent
4aeb426d2d
commit
2cf6b50614
@@ -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: {
|
||||
"<agent-id>": {
|
||||
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
|
||||
|
||||
@@ -590,6 +590,35 @@ Example:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user