OpenClaw 静默房间事件Ambient Room Events完全指南让 Agent 在群聊中只听不说【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读本文档讲解 OpenClaw 的 ambient room events静默房间事件机制它允许 Agent 将群聊或频道中未被 提及的消息作为安静上下文进行处理——Agent 可以更新记忆与会话状态但房间保持静默除非 Agent 显式调用message工具才会发言。该机制面向需要 7×24 小时常驻监听型群聊的场景是替代旧式NO_REPLY提示词模式的现代方案。读完本文你将掌握如何配置全局群聊行为、如何针对 Discord / Slack / Telegram 等频道落地、如何做 Agent 级策略覆盖以及如何排查只打字不说话类问题。一、什么是 Ambient Room Events在默认行为下OpenClaw 收到群聊中未被 提及的消息时通常不会唤醒 Agent 进行处理。而开启 ambient room events 后未提及的群组/频道消息会被归类为room_event房间事件而不是user_request用户请求。从源码分类器可以清晰看到这一设计意图src/channels/inbound-event/kind.ts/** * High-level inbound event class used to separate actionable user requests from room activity. */ export type InboundEventKind user_request | room_event;对应的分类逻辑位于 src/channels/inbound-event/classification.tsexport function classifyChannelInboundEvent( params: ClassifyChannelInboundEventParams, ): InboundEventKind { if (params.unmentionedGroupPolicy ! room_event) { return user_request; } if (params.conversation.kind ! group params.conversation.kind ! channel) { return user_request; } // Native commands, mentions, control commands, and aborts are explicit user intent even when // unmentioned group traffic would otherwise be treated as passive room activity. if ( params.wasMentioned true || params.hasControlCommand true || params.hasAbortRequest true || params.commandSource native ) { return user_request; } return room_event; }也就是说只有当未提及群聊策略被显式配置为room_event、且会话属于群组/频道、且消息既未被提及、也不含控制命令/中止请求/原生命令时该消息才会被归类为静默房间事件。提及、控制命令、原生命令、中止请求始终是显式的用户意图无论群聊流量如何配置都会保持为user_request。支持范围目前支持 ambient room events 的频道有Discord 公会频道guild channelsSlack 频道与私密频道channels private channelsSlack 多人私信multi-person DMsmpimTelegram 群组与超级群组groups / supergroups其他群组频道在未明确声明支持前维持原有的群组行为不变。与旧式 NO_REPLY 提示词模式的对比传统做法是在系统提示词中要求模型对无需回复的消息输出NO_REPLY由 Agent 端判断后抑制回复。ambient room events 将这一决策从模型提示词下沉到路由层分类器分类器在消息进入 Agent 前就决定其归属Agent 只处理被归类为user_request的请求而房间事件则作为静默上下文注入。这意味着不再依赖模型记得输出 NO_REPLY模型不会因为被迫输出标记文本而浪费 token是否发言完全由 Agent 通过显式调用message(actionsend)决定。二、推荐配置让房间常驻监听、按需发言核心推荐组合是两条messages.groupChat配置{ messages: { groupChat: { unmentionedInbound: room_event, visibleReplies: message_tool, historyLimit: 50, }, }, }三个字段的作用字段取值说明unmentionedInboundroom_event未提及的群组/频道消息被归类为静默房间事件另一可选值为user_request即默认行为未提及消息仍唤醒 AgentvisibleRepliesmessage_tool可见回复必须通过message工具发送模型产出的最终文本默认保持私密historyLimit正整数默认 50全局群组历史窗口条数上限从配置 Schema 可以看到这三个字段的合法取值范围src/config/zod-schema.messages.tsexport const GroupChatSchema z .object({ mentionPatterns: z.array(z.string()).optional(), historyLimit: z.number().int().min(0).optional(), unmentionedInbound: z.enum([user_request, room_event]).optional(), visibleReplies: VisibleRepliesSchema.optional(), }) .strict() .optional();其中visibleReplies还兼容布尔写法src/config/zod-schema.messages.tstrue归一化为automaticfalse归一化为message_tool。关于历史窗口的补充historyLimit为 0 时表示该频道禁用群组历史上下文频道可用channels.channel.historyLimit覆盖全局值部分频道还支持按账号设置历史上限。Telegram 的旧配置键includeGroupHistoryContext已被移除可通过openclaw doctor --fix自动清理。完成全局配置后还需要让该房间常驻开启即关闭该房间的提及门槛mention gating。注意房间仍需通过其正常的groupPolicy、房间白名单与发送者白名单校验。配置生效方式保存配置后Gateway 会对messages相关设置进行热应用hot-apply。但如果设置了gateway.reload.mode: off则需要手动重启 Gateway 才能使改动生效。三、前置条件两个容易忽略的静默开关即使设置了unmentionedInbound: room_event仍有两个设置会静默地禁用 ambient room events。1. 房间必须关闭提及门槛requireMention: falserequireMention: true会在消息路由之前丢弃所有未提及消息因此它们永远不可能变成房间事件。此时 Agent 完全没有房间回放room backlog它只能看到提及自己的消息。如果 Agent 反馈看不到最近的房间历史请先检查提及门槛而不是其他配置。2. Agent 必须拥有 message 工具房间事件采用严格的可见投递strict visible delivery机制发言必须调用message(actionsend)。message工具随messaging工具档案tool profile一起提供而minimal与coding档案不包含它。如果 Agent 运行在tools.profile: coding下它会听得到房间事件却永远无法发言。当档案缺少该工具时需要显式授权{ agents: { entries: { agent-id: { tools: { alsoAllow: [message] }, }, }, }, }不要凭经验假设档案一定包含message工具请用openclaw agents list查看有效工具面effective surface并通过一轮探针对话probe turn实测确认。四、开启后行为变化一览配置messages.groupChat.unmentionedInbound: room_event后入站消息类型归类结果被允许的未提及群组/频道消息静默房间事件room event被提及的消息用户请求user request文本控制命令 / 原生命令用户请求中止abort/ 停止请求用户请求私聊消息direct message用户请求房间事件使用严格的可见投递最终助手文本final assistant text保持私密Agent 必须调用message(actionsend)才能在房间内发言打字状态typing与生命周期状态反应lifecycle status reactions对房间事件保持抑制。唯一显式的回执receipt例外是messages.ackReactionScope: all该配置会发送已配置的确认反应ack reaction。如果希望房间完全静默请使用任何更窄的 scope 或off。从 ack 反应门控源码可以看到这一约束src/channels/ack-reactions.tsexport function shouldAckReaction(params: AckReactionGateParams): boolean { const scope params.scope ?? group-mentions; if (scope off || scope none) { return false; } // Ambient room events stay silent unless the operator explicitly chose the // unconditional scope. This keeps every channel on the same all contract. if (params.inboundEventKind room_event scope ! all) { return false; } if (scope all) { return true; } ... }ackReactionScope的合法取值在 src/config/zod-schema.messages.ts 中定义为[group-mentions, group-all, direct, all, off, none]默认值是group-mentions。五、Discord 实例配置场景一整个公会全部静默监听{ messages: { groupChat: { unmentionedInbound: room_event, visibleReplies: message_tool, historyLimit: 50, }, }, channels: { discord: { groupPolicy: allowlist, guilds: { DISCORD_SERVER_ID: { requireMention: false, users: [YOUR_DISCORD_USER_ID], }, }, }, }, }场景二仅单个频道静默监听当只需要一个频道保持 ambient 时使用按频道per-channel的 Discord 配置。在groupPolicy: allowlist下列出该频道即是允许它enabled: false可禁用某个条目{ channels: { discord: { groupPolicy: allowlist, guilds: { DISCORD_SERVER_ID: { channels: { DISCORD_CHANNEL_ID_OR_NAME: { requireMention: false, }, }, }, }, }, }, }注意这里的DISCORD_SERVER_ID与DISCORD_CHANNEL_ID_OR_NAME需要替换为你实际的值。Discord 频道既支持 ID 也支持频道名称作为键。六、Slack 实例配置Slack 频道白名单是ID-first的必须使用频道 ID形如C12345678而不是#channel-name。在channels.slack.channels下列出该频道即是允许它enabled: false可禁用条目{ messages: { groupChat: { unmentionedInbound: room_event, visibleReplies: message_tool, historyLimit: 50, }, }, channels: { slack: { groupPolicy: allowlist, channels: { SLACK_CHANNEL_ID: { requireMention: false, }, }, }, }, }Slack 历史权限提示如果 Slack ambient 房间完全不触发请确认① 频道键确实是 Slack 频道 ID② 应用具备对应房间类型的历史读取 scope——公开频道需要channels:history私密频道需要groups:history多人私信mpim需要mpim:history。七、Telegram 实例配置对 Telegram 群组而言bot 必须能够看到普通群消息。设置requireMention: false后需要关闭 BotFather 的隐私模式privacy mode或采用其他能向 bot 投递完整群流量的 Telegram 设置。{ messages: { groupChat: { unmentionedInbound: room_event, visibleReplies: message_tool, historyLimit: 50, }, }, channels: { telegram: { groups: { TELEGRAM_GROUP_CHAT_ID: { groupPolicy: open, requireMention: false, }, }, }, }, }获取 Telegram 群组 ID 的三种途径Telegram 群组 ID 通常是负数形如-1001234567890从openclaw logs --follow中读取chat.id将一条群消息转发给 ID helper bot或直接检查 Bot API 的getUpdates返回。Telegram 历史窗口的特殊行为Telegram 支持房间事件频道时会维护一个由historyLimit限定的常驻滚动窗口always-on rolling per-group window。用户请求回合user-request turns会选取 bot 最后一次回复之后的条目作为上下文而房间事件回合room-event turns会获得完整的最近窗口以便模型看到自己最近的发言。旧版includeGroupHistoryContext模式键已被移除openclaw doctor --fix会负责清理。八、Agent 级策略覆盖多 Agent 共享房间当多个 Agent 共享同一个房间、但只有其中一个需要把未提及闲聊当作 ambient 上下文时可以使用 Agent 覆盖agent override{ messages: { groupChat: { visibleReplies: message_tool, }, }, agents: { entries: { main: { default: true, groupChat: { unmentionedInbound: room_event, mentionPatterns: [openclaw, openclaw], }, }, }, }, }Agent 特定的agents.entries.*.groupChat.unmentionedInbound值会覆盖全局messages.groupChat.unmentionedInbound。这一点与源码中的策略解析逻辑一致src/channels/inbound-event/classification.ts解析时优先读取 Agent 的groupChat配置仅当 Agent 配置显式包含unmentionedInbound键时才采用它否则回退到全局messages.groupChat.unmentionedInbound最终默认值为user_request。九、可见回复模式Visible Reply Modes详解messages.groupChat.visibleReplies的默认值是automatic适用于普通群组/频道的用户请求最终助手文本无需显式调用 message 工具即可自动可见发布。保持automatic适用于常规群聊希望 Agent 的最终回复自动上屏改用message_tool适用于 ambient 常驻房间让 Agent 通过调用 message 工具自行决定何时发言。官方建议在 ambient 常驻房间中始终使用message_tool尤其适合最新一代、工具调用可靠性高的模型例如文档中提到的 GPT-5.6 Sol 类模型。如果模型返回了最终文本但没有调用工具OpenClaw 会保持该文本私密并记录抑制投递suppressed-delivery元数据。重要区别即使其他群组请求使用自动回复房间事件依然保持严格投递——未提及的 ambient 房间事件始终需要message(actionsend)才能产生可见输出。十、历史上下文History机制messages.groupChat.historyLimit是全局群组历史默认值未设置时为 50必须为正整数频道可用channels.channel.historyLimit覆盖全局值部分频道还支持按账号设置历史上限设置频道级historyLimit: 0可禁用该频道的群组历史上下文。从源码的会话转录逻辑可见src/channels/inbound-event/context.ts历史窗口只有在historyLimit 0时才会作为SessionTranscriptContext提供给入站事件SessionTranscriptContext: params.sessionTranscript params.sessionTranscript.historyLimit 0 ? params.sessionTranscript : undefined,支持房间事件的频道会保留最近的 ambient 房间消息作为上下文。Telegram 的滚动窗口行为已在第七节详述。十一、故障排查Troubleshooting现象房间显示打字状态或 token 消耗但看不到可见消息按以下顺序排查确认房间已通过频道白名单与发送者白名单channel allowlist sender allowlist确认requireMention: false已设置在预期的房间层级检查是公会级还是频道级检查messages.groupChat.unmentionedInbound或 Agent 覆盖值是否为room_event检查日志中的抑制投递元数据关注didSendViaMessagingTool: false之类的标记对普通群组请求如果需要最终回复自动上屏请保持/恢复messages.groupChat.visibleReplies: automatic对使用message_tool的 ambient 房间请使用能可靠调用工具的模型/运行时。现象Telegram ambient 房间完全不触发检查 BotFather 隐私模式是否关闭并验证 Gateway 是否确实收到了普通群消息。现象Slack ambient 房间不触发验证两点① 频道键是否为 Slack 频道 ID而非#channel-name② 应用是否具备对应房间类型的历史 scope公开channels:history/ 私密groups:history/ 多人私信mpim:history。现象Agent 报告看不到房间历史优先检查提及门槛——requireMention: true会在路由前丢弃未提及消息Agent 将完全没有房间回放。十二、延伸阅读群组GroupsDiscord 频道Slack 频道Telegram 频道频道故障排查频道配置参考小结Ambient room events 是 OpenClaw 中监听型常驻 Agent的基础设施它在路由层完成消息分类让 Agent 在群聊中安静地更新记忆与状态只在值得回应时通过message工具主动开口。核心配置只有三件事——unmentionedInbound: room_event、visibleReplies: message_tool、房间级requireMention: false再加上message工具授权配合 Agent 级覆盖与频道级历史窗口即可构建出从 Discord、Slack 到 Telegram 的统一静默监听体验。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考