环境房间事件

环境房间事件让 OpenClaw 能将未被点名的群组或频道聊天作为安静上下文来处理。代理可以更新记忆和会话状态，但除非代理显式调用 message 工具，否则房间保持静默。对于始终在线的群组聊天，请将 messages.groupChat.unmentionedInbound: "room_event" 与 messages.groupChat.visibleReplies: "message_tool" 结合使用。代理会监听，判断何时回复有用，并且不再需要旧的提示模式 NO_REPLY。目前受支持：Discord 公会频道、Slack 频道和私人频道、Slack 多人 DM，以及 Telegram 群组或超级群组。其他群组频道会保持其现有的群组行为，除非其频道页面说明它们支持环境房间事件。

先决条件

即使设置了 unmentionedInbound: "room_event"，两个设置也会静默禁用 ambient room events。 房间的提及门控必须关闭。 requireMention: true 会在路由之前丢弃未被提及的消息，因此它们永远不会成为 room events。这样一来，agent 完全没有 room backlog——它只能看到提及了它的消息。如果 agent 报告它看不到最近的房间历史，先检查提及门控，而不是别的。 agent 需要 message 工具。 Room events 使用严格的可见投递，因此发送需要 message(action=send)。message 工具随 messaging 工具配置文件一起提供；minimal 和 coding 配置文件不包含它。配置文件为 tools.profile: "coding" 的 agent 会监听 room events，但永远不能发言。如果配置文件省略了它，就显式授予：

{
  agents: {
    entries: {
      "<agent-id>": {
        tools: { alsoAllow: ["message"] },
      },
    },
  },
}

使用 openclaw agents list 和一次 probe turn 检查实际生效的 surface，不要假定配置文件一定包含它。保存配置后，Gateway 会热加载 messages 设置。只有在文件监听或配置重载被禁用时（gateway.reload.mode: "off"）才需要重启。

变化内容

使用 messages.groupChat.unmentionedInbound: "room_event" 时：

未提及的允许群组或频道消息会变成静默的房间事件
被提及的消息仍然是用户请求
文本控制命令和原生命令仍然是用户请求
中止或停止请求仍然是用户请求
直接消息仍然是用户请求

房间事件使用严格的可见交付。最终助手文本是私有的。代理必须调用 message(action=send) 才能在房间中发帖。对于房间事件，输入状态和生命周期状态反应仍然会被抑制。唯一明确的回执例外是 messages.ackReactionScope: "all"，它会发送配置的确认反应；当房间必须保持完全静默时，请使用任何更窄的范围或 "off"。

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 时，使用按频道的 Discord 配置。在 groupPolicy: "allowlist" 下，列出该频道即表示允许它（enabled: false 会禁用一个条目）：

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "<DISCORD_SERVER_ID>": {
          channels: {
            "<DISCORD_CHANNEL_ID_OR_NAME>": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

Slack 示例

Slack 频道允许名单以 ID 为先。请使用频道 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,
        },
      },
    },
  },
}

Telegram 示例

对于 Telegram 群组，机器人必须能够看到正常的群组消息。如果 requireMention: false，请禁用 BotFather 隐私模式，或使用其他能将完整群组流量传递给机器人的 Telegram 设置。

{
  messages: {
    groupChat: {
      unmentionedInbound: "room_event",
      visibleReplies: "message_tool",
      historyLimit: 50,
    },
  },
  channels: {
    telegram: {
      groups: {
        "<TELEGRAM_GROUP_CHAT_ID>": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Telegram 群组 ID 通常是负数，例如 -1001234567890。可通过 openclaw logs --follow 读取 chat.id，将群组消息转发给 ID 辅助机器人，或检查 Bot API 的 getUpdates。

代理特定策略

当多个代理共享同一个房间，但只有一个代理应将未点名聊天视为环境上下文时，请使用代理覆盖：

{
  messages: {
    groupChat: {
      visibleReplies: "message_tool",
    },
  },
  agents: {
    entries: {
      main: {
        default: true,
        groupChat: {
          unmentionedInbound: "room_event",
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    },
  },
}

代理特定的 agents.entries.*.groupChat.unmentionedInbound 值会覆盖该代理的 messages.groupChat.unmentionedInbound。

可见回复模式

对于普通群组/频道用户请求，messages.groupChat.visibleReplies 默认值为 "automatic"。当最终助手文本应当以可见方式发布且没有显式的 message-tool 调用时，请保持该默认值。对于 ambient 始终在线房间，仍然建议使用 messages.groupChat.visibleReplies: "message_tool"，尤其是在最新一代、工具调用可靠的模型（如 GPT-5.6 Sol）上。它允许代理通过调用 message 工具来决定何时发言。如果模型在没有调用该工具的情况下返回最终文本，OpenClaw 会将该最终文本保留为私有，并记录被抑制投递的元数据。即使其他群组请求使用 automatic 回复，房间事件仍然保持严格模式。未被提及的 ambient 房间事件始终需要使用 message(action=send) 才能可见输出。

历史记录

messages.groupChat.historyLimit 设置全局群组历史记录默认值（未设置时为 50；必须是正整数）。各频道可以通过 channels.<channel>.historyLimit 覆盖它，且某些频道还支持按账户设置历史记录限制。将频道级 historyLimit: 0 设为 0，可禁用该频道的群组历史上下文。受支持的房间事件频道会将最近的环境房间消息保留为上下文。Telegram 会为每个群组维持一个始终开启的滚动窗口，并受 historyLimit 限制；用户请求轮次会在机器人上一次记录的回复之后选择条目，而房间事件轮次会接收完整的最近窗口，这样模型就能看到自己最近的发言。已弃用的 Telegram includeGroupHistoryContext 模式键会被 openclaw doctor --fix 移除。

故障排查

如果房间显示了打字或 token 使用情况，但没有可见消息：

确认该房间已被频道允许列表和发送者允许列表允许。
确认你期望的房间级别已设置 requireMention: false。
检查 messages.groupChat.unmentionedInbound 或代理覆盖是否为 "room_event"。
检查日志中是否有被抑制的最终有效载荷元数据或 didSendViaMessagingTool: false。
对于正常群组请求，如果你希望最终回复自动发帖，请保持或恢复 messages.groupChat.visibleReplies: "automatic"。对于使用 message_tool 的环境房间，请使用能可靠调用工具的模型/运行时。

如果 Telegram 环境房间完全没有触发，请检查 BotFather 隐私模式并确认 Gateway 正在接收正常的群组消息。如果 Slack 环境房间没有触发，请验证频道键是否为 Slack 频道 ID，并且应用程序已拥有该房间类型的历史范围：channels:history（公开）、groups:history（私密）或 mpim:history（多人私信）。

概览

主流消息平台

开发者与自托管

区域平台

配置

推荐设置

先决条件

变化内容

Discord 示例

Slack 示例

Telegram 示例

代理特定策略

可见回复模式

历史记录

故障排查

相关内容

​推荐设置

​先决条件

​变化内容

​Discord 示例

​Slack 示例

​Telegram 示例

​代理特定策略

​可见回复模式

​历史记录

​故障排查

​相关内容

推荐设置

先决条件

变化内容

Discord 示例

Slack 示例

Telegram 示例

代理特定策略

可见回复模式

历史记录

故障排查

相关内容