跳转至

群组消息如何触达代理:提及门控、可见回复模式、私信历史记录限制与自我聊天模式

群聊提及门控

群组消息默认要求提及(元数据提及或安全的正则表达式模式)。适用于 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群聊。

可见回复是单独控制的。普通群组、频道和内部 WebChat 直接请求默认采用自动最终投递:最终助手文本通过传统可见回复路径发布。当模型撰写的源回复应仅在代理调用 message(action=send) 后才发布时,请选择加入 messages.visibleReplies: "message_tool" 或 messages.groupChat.visibleReplies: "message_tool"。如果模型在已选择加入的纯工具模式下返回了实质性最终答案但没有调用消息工具,该最终文本将保持私有,网关详细日志会记录被抑制的负载元数据,并且 OpenClaw 会排入一次恢复重试,要求模型通过 message(action=send) 传递相同的回复。

纯工具策略管辖助手源回复和通用工具媒体。它不会抑制运行时拥有的终端输出,例如经授权的命令响应、持久完成通知,或由所属 harness 明确归类为主机拥有的提供方原生产物。主机拥有的产物通过正常的频道调度路径投递,并且仍然遵循出站 sendPolicy 的拒绝规则。环境性的 room_event 轮次保持静默,除非它们是显式命令,即使运行时输出被标记为主机拥有。

纯工具可见回复要求模型/运行时能够可靠地调用工具,并推荐在工具调用可靠性强的模型(如 GPT-6 Astra)上用于共享的环境房间。一些较弱的模型可以给出最终文本答案,但无法理解源可见输出必须通过 message(action=send) 发送。OpenClaw 仅在最终回复是实质性的、源轮次不是房间事件、发送策略未拒绝投递且尚未发送任何源回复时,默认恢复常见的滞留最终回复场景。恢复限制为一次重试;它会抑制合成重试提示的持久化,并将该重试排除在收集批处理之外,使其无法与无关的排队提示合并。如果重试也滞留或无法入队,OpenClaw 只投递一条经过净化的诊断消息,例如“我已生成回复,但无法将其投递到此聊天。请重试。”原始私有最终文本永远不会被标记为自动源投递。对于反复滞留回复的模型,请使用 "automatic" 使最终助手轮次成为可见回复路径,切换到更强的工具调用模型,检查网关详细日志中被抑制的负载摘要,或将 messages.groupChat.visibleReplies: "automatic" 设置为对每个群组/频道请求使用可见最终回复。

如果消息工具在当前工具策略下不可用,OpenClaw 会回退到自动可见回复,而不是静默抑制响应。openclaw doctor 会警告此不匹配。

此规则适用于普通代理最终文本。插件拥有的会话绑定使用所属插件返回的回复作为已声明绑定线程轮次的可见响应;插件无需为这些绑定回复调用 message(action=send)。

故障排查:群组 @提及 触发输入状态后静默(无错误)

症状:群组/频道 @提及 显示输入指示器,网关日志报告 dispatch complete (queuedFinal=false, replies=0),但房间中没有消息到达。同一代理的私信回复正常。

原因:群组/频道的可见回复模式解析为 "message_tool",因此 OpenClaw 会运行该轮次,但除非代理调用 message(action=send),否则会抑制最终助手文本。此模式中没有 NO_REPLY 契约;未调用消息工具意味着原始最终文本是私有的。对于实质性源轮次,OpenClaw 现在会尝试一次受保护的恢复重试;简短笔记、显式静默、房间事件、发送策略拒绝的轮次以及已投递的轮次不会重试。普通群组和频道轮次默认使用 "automatic",因此只有当 messages.groupChat.visibleReplies(或全局 messages.visibleReplies)被显式设置为 "message_tool" 时才会出现此症状。Harness 的 defaultVisibleReplies 在此不适用——群组/频道解析器会忽略它;它只影响直接/源聊天(Codex harness 就是以这种方式抑制直接聊天最终回复的)。

修复:要么选择更强的工具调用模型,移除显式的 "message_tool" 覆盖以回退到 "automatic" 默认值,或者设置 messages.groupChat.visibleReplies: "automatic" 以强制对每个群组/频道请求使用可见回复。实质性的滞留最终回复不应再以静默成功结束;它应通过一次 message(action=send) 重试恢复,或显示经过净化的投递失败诊断。网关会在文件保存后热重载 messages 配置;仅当部署中禁用了文件监视或配置重载时,才需要重启网关。

提及类型:

  • 元数据提及:平台原生 @提及。在 WhatsApp 自我聊天模式中会被忽略。
  • 文本模式:agents.entries.*.groupChat.mentionPatterns 中的安全正则表达式模式。无效模式和不安全的嵌套重复会被忽略。
  • 仅在可检测到时才强制执行提及门控(原生提及或至少一个模式)。
{
  messages: {
    visibleReplies: "automatic", // force old automatic final replies for direct/source chats
    groupChat: {
      historyLimit: 50,
      unmentionedInbound: "room_event", // always-on unmentioned room chatter becomes quiet context
      visibleReplies: "message_tool", // opt-in; require message(action=send) for visible room replies
    },
  },
  agents: {
    entries: {
      main: {
        groupChat: { mentionPatterns: ["@openclaw", "openclaw"] },
      },
    },
  },
}

messages.groupChat.historyLimit 设置全局默认值。频道可以通过 channels.<channel>.historyLimit(或按账户)覆盖。设置 0 可禁用。

messages.groupChat.unmentionedInbound: "room_event" 在支持的频道上,将未提及的常开群组/频道消息作为安静的房间上下文提交。被提及的消息、命令和直接消息仍作为用户请求。有关 Discord、Slack 和 Telegram 的完整示例,请参阅 环境房间事件。

messages.visibleReplies 是全局源事件默认值;messages.groupChat.visibleReplies 会针对群组/频道源事件覆盖它。当 messages.visibleReplies 未设置时,直接/源聊天使用所选运行时或 harness 默认值,但内部 WebChat 直接轮次使用自动最终交付,以实现 Pi/Codex 提示一致性。设置 messages.visibleReplies: "message_tool" 可有意要求可见输出必须使用 message(action=send)。频道允许列表和提及门控仍决定事件是否被处理。

DM 历史限制

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

解析顺序:按 DM 覆盖 → 提供商默认值 → 无限制(全部保留)。在多账户频道上,会先检查当前消息所属的账户,再检查频道根配置,因此 channels.<provider>.accounts.<id>.dmHistoryLimit 仅对该账户覆盖 channels.<provider>.dmHistoryLimit。

dms 映射是例外:如果某个账户定义了 accounts.<id>.dms,它会替换该账户的根 dms 映射,而不是逐条合并。因此,仅在根中列出的对端会回退到该账户的 dmHistoryLimit,而不是根中的按 DM 值。如果仍需要某些根条目,请在账户映射中重复它们。

嵌入式 OpenClaw 运行时在频道范围的 DM 会话(包括 per-account-channel-peer)准备提示期间,会针对最近轮次应用这些限制。共享主会话不会因这些频道限制而被窗口化。客户端压缩仍会总结较旧的持久历史;生成的摘要会与窗口化的最近轮次一起保留。这些限制不会删除已存储的消息。原生运行时管理自己的转录历史。

提供商端压缩使用已准备的转录窗口。由 Gateway 触发的压缩会从当前会话记录的主对话中解析关联的对端;缺失或过期的路由事实不会选择另一个对端的覆盖。

频道提供的最近消息上下文是另一个窗口。例如,Telegram 按原生用户 ID 查找 dms 并统计单独的消息,而嵌入式转录窗口查找会话对端并统计用户轮次。使用 session.identityLinks 时,该会话对端是关联 ID。如果希望为关联身份同时限制两个窗口,请配置这两个键:

{
  session: {
    dmScope: "per-channel-peer",
    identityLinks: { alice: ["telegram:123456789"] },
  },
  channels: {
    telegram: {
      accounts: {
        work: {
          dms: {
            "123456789": { historyLimit: 2 }, // Telegram supplemental context
            alice: { historyLimit: 2 }, // Embedded session transcript
          },
        },
      },
    },
  },
}

这些现有窗口并非一个严格的全提示上限:补充回复上下文、已保存的压缩摘要以及转录窗口的批处理缓冲可能会添加超出配置数量的上下文。

仅凭会话键可能会产生歧义,尤其是当账户名称或关联对端 ID 包含诸如 direct 之类的标记时。OpenClaw 使用观察到的路由对端来选择正确的按 DM 覆盖。当存在歧义的会话没有观察到的对端,或其身份链接已更改时,将应用已知的账户/频道 DM 默认值,而不是另一个对端的覆盖。无歧义的会话键保留其现有的按 DM 查找。

自聊天模式

在 allowFrom 中包含你自己的号码以启用自聊天模式(忽略原生 @-提及,仅响应文本模式):

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    entries: {
      main: {
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    },
  },
}

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