@@ -0,0 +1,214 @@
1+---
2+summary: "Let supported group rooms provide quiet context unless the agent sends with the message tool"
3+read_when:
4+ - Configuring always-on group or channel rooms
5+ - You want the agent to watch room chatter without posting final text automatically
6+ - Debugging typing and token usage with no visible room message
7+title: "Ambient room events"
8+sidebarTitle: "Ambient room events"
9+---
10+11+Ambient room events let OpenClaw process unmentioned group or channel chatter as quiet context. The agent can update memory and session state, but the room stays silent unless the agent explicitly calls the `message` tool.
12+13+Use this for always-on rooms where the agent should listen, decide when a reply is useful, and avoid the old prompt pattern of answering `NO_REPLY`.
14+15+Supported today: Discord guild channels, Slack channels and private channels, Slack multi-person DMs, and Telegram groups or supergroups. Other group channels keep their existing group behavior unless their channel page says they support ambient room events.
16+17+## Quick setup
18+19+Set the global group-chat behavior:
20+21+```json5
22+{
23+ messages: {
24+ groupChat: {
25+ unmentionedInbound: "room_event",
26+ visibleReplies: "message_tool",
27+ historyLimit: 50,
28+ },
29+ },
30+}
31+```
32+33+Then configure the room itself as always-on by disabling mention gating for that room. The channel must still be allowed by its normal `groupPolicy`, room allowlist, and sender allowlist.
34+35+After saving the config, the Gateway hot-reloads `messages` settings. Restart only when file watching or config reload is disabled.
36+37+## What changes
38+39+With `messages.groupChat.unmentionedInbound: "room_event"`:
40+41+- unmentioned allowed group or channel messages become quiet room events
42+- mentioned messages stay user requests
43+- text commands and native commands stay user requests
44+- abort or stop requests stay user requests
45+- direct messages stay user requests
46+47+Room events use strict visible delivery. Final assistant text is private. The agent must call `message(action=send)` to post in the room.
48+49+## Discord example
50+51+```json5
52+{
53+ messages: {
54+ groupChat: {
55+ unmentionedInbound: "room_event",
56+ visibleReplies: "message_tool",
57+ historyLimit: 50,
58+ },
59+ },
60+ channels: {
61+ discord: {
62+ groupPolicy: "allowlist",
63+ guilds: {
64+"<DISCORD_SERVER_ID>": {
65+ requireMention: false,
66+ users: ["<YOUR_DISCORD_USER_ID>"],
67+ },
68+ },
69+ },
70+ },
71+}
72+```
73+74+Use per-channel Discord config when only one channel should be ambient:
75+76+```json5
77+{
78+ channels: {
79+ discord: {
80+ guilds: {
81+"<DISCORD_SERVER_ID>": {
82+ channels: {
83+"<DISCORD_CHANNEL_ID_OR_NAME>": {
84+ allow: true,
85+ requireMention: false,
86+ },
87+ },
88+ },
89+ },
90+ },
91+ },
92+}
93+```
94+95+## Slack example
96+97+Slack channel allowlists are ID-first. Use channel IDs such as `C12345678`, not `#channel-name`.
98+99+```json5
100+{
101+ messages: {
102+ groupChat: {
103+ unmentionedInbound: "room_event",
104+ visibleReplies: "message_tool",
105+ historyLimit: 50,
106+ },
107+ },
108+ channels: {
109+ slack: {
110+ groupPolicy: "allowlist",
111+ channels: {
112+"<SLACK_CHANNEL_ID>": {
113+ allow: true,
114+ requireMention: false,
115+ },
116+ },
117+ },
118+ },
119+}
120+```
121+122+## Telegram example
123+124+For Telegram groups, the bot must be able to see normal group messages. If `requireMention: false`, disable BotFather privacy mode or use another Telegram setup that delivers full group traffic to the bot.
125+126+```json5
127+{
128+ messages: {
129+ groupChat: {
130+ unmentionedInbound: "room_event",
131+ visibleReplies: "message_tool",
132+ historyLimit: 50,
133+ },
134+ },
135+ channels: {
136+ telegram: {
137+ groups: {
138+"<TELEGRAM_GROUP_CHAT_ID>": {
139+ groupPolicy: "open",
140+ requireMention: false,
141+ },
142+ },
143+ },
144+ },
145+}
146+```
147+148+Telegram group IDs are usually negative numbers such as `-1001234567890`. Read `chat.id` from `openclaw logs --follow`, forward a group message to an ID helper bot, or inspect Bot API `getUpdates`.
149+150+## Agent specific policy
151+152+Use an agent override when several agents share the same room but only one should treat unmentioned chatter as ambient context:
153+154+```json5
155+{
156+ messages: {
157+ groupChat: {
158+ visibleReplies: "message_tool",
159+ },
160+ },
161+ agents: {
162+ list: [
163+ {
164+ id: "main",
165+ groupChat: {
166+ unmentionedInbound: "room_event",
167+ mentionPatterns: ["@openclaw", "openclaw"],
168+ },
169+ },
170+ ],
171+ },
172+}
173+```
174+175+The agent-specific `agents.list[].groupChat.unmentionedInbound` value overrides `messages.groupChat.unmentionedInbound` for that agent.
176+177+## Visible reply modes
178+179+`messages.groupChat.visibleReplies: "message_tool"` is the recommended group and channel default. It lets the agent decide when to speak by calling the message tool. If the model returns final text without calling the tool, OpenClaw keeps that final text private and logs suppressed delivery metadata.
180+181+Use `messages.groupChat.visibleReplies: "automatic"` only when you want legacy behavior where normal group requests post final assistant text automatically.
182+183+Room events stay strict even when other group requests use automatic replies. Unmentioned ambient room events still require `message(action=send)` for visible output.
184+185+## History
186+187+`messages.groupChat.historyLimit` controls the global group history default. Channels can override it with `channels.<channel>.historyLimit`, and some channels also support per-account history limits.
188+189+Set `historyLimit: 0` to disable group history context.
190+191+Supported room-event channels keep recent ambient room messages as context. Discord keeps room-event history until a visible Discord send succeeds, so quiet context is not lost before message-tool delivery.
192+193+## Troubleshooting
194+195+If the room shows typing or token usage but no visible message:
196+197+1. Confirm the room is allowed by the channel allowlist and sender allowlist.
198+2. Confirm `requireMention: false` is set at the room level you expect.
199+3. Check whether `messages.groupChat.unmentionedInbound` or the agent override is `"room_event"`.
200+4. Inspect logs for suppressed final payload metadata or `didSendViaMessagingTool: false`.
201+5. Use a model/runtime that reliably calls tools, or set `messages.groupChat.visibleReplies: "automatic"` for legacy final replies on normal group requests.
202+203+If Telegram ambient rooms do not trigger at all, check BotFather privacy mode and verify the Gateway is receiving normal group messages.
204+205+If Slack ambient rooms do not trigger, verify the channel key is the Slack channel ID and the app has the required `channels:history` or `groups:history` scope for that room type.
206+207+## Related
208+209+- [Groups](/channels/groups)
210+- [Discord](/channels/discord)
211+- [Slack](/channels/slack)
212+- [Telegram](/channels/telegram)
213+- [Channel troubleshooting](/channels/troubleshooting)
214+- [Channel configuration reference](/gateway/config-channels)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。