环境房间事件

环境房间事件让 OpenClaw 将未提及的群组或频道聊天作为安静上下文处理。代理可以更新记忆和会话状态，但除非代理显式调用 message 工具，房间保持静默。

对于始终在线的群聊，将 messages.groupChat.unmentionedInbound: "room_event" 与 messages.groupChat.visibleReplies: "message_tool" 结合使用。代理会监听，判断何时回复有用，并且不再需要旧的提示模式来回答 NO_REPLY。

当前支持：Discord 服务器频道、Slack 频道和私有频道、Slack 多人私信，以及 Telegram 群组或超级群。其他群聊频道保持现有群聊行为，除非其频道页面说明支持环境房间事件。

前提条件¶

即使设置了 unmentionedInbound: "room_event"，也有两个设置会静默禁用环境房间事件。

房间的提及门控必须关闭。 requireMention: true 会在路由前丢弃未提及的消息，因此它们永远不会成为房间事件。这样代理将完全没有房间积压——它只能看到提及它的消息。如果代理报告无法看到最近的房间历史，请首先检查提及门控。

代理需要 message 工具。 房间事件使用严格可见投递，因此发布需要 message(action=send)。message 工具包含在 messaging 工具配置文件中；minimal 和 coding 配置文件不包含它。使用 tools.profile: "coding" 的代理会监听房间事件，但永远无法发言。当配置文件省略它时，请显式授予：

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

请使用 openclaw agents list 和一个探测回合来检查有效工具表面，而不是假设配置文件包含它。

保存配置后，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>"],
        },
      },
    },
  },
}

当只有一个频道应处于环境模式时，请使用按频道配置的 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"。当最终助手文本应在没有显式消息工具调用的情况下可见发布时，请保留该默认值。

对于环境常开房间，仍建议使用 messages.groupChat.visibleReplies: "message_tool"，尤其是使用 GPT-6 Astra 等最新一代、可靠调用工具的模型。它允许代理通过调用消息工具来决定何时发言。如果模型在未调用工具的情况下返回最终文本，OpenClaw 会保持该最终文本为私有，并记录被抑制投递的元数据。

即使其他群请求使用自动回复，房间事件仍保持严格。未被提及的环境房间事件始终需要 message(action=send) 才能产生可见输出。

历史记录¶

messages.groupChat.historyLimit 设置全局群历史默认值（未设置时为 50；必须为正整数）。频道可以通过 channels.<channel>.historyLimit 覆盖它，某些频道还支持按账号的历史限制。将频道级别的 historyLimit: 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（多人私信）。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw