配置 — 群组提及门控和历史

群组消息如何触达智能体：提及门控、可见回复模式、私信历史限制与自聊模式。

群组聊天提及门控¶

群组消息默认需要提及（元数据提及或安全正则表达式模式）。适用于 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 仅在以下情况下默认恢复常见的滞留最终回复：最终回复具有实质性、源轮次不是房间事件、发送策略未拒绝投递、且尚未发送任何源回复。恢复仅限于一次重试；它会为合成重试提示抑制持久化，并将该重试排除在 collect 批处理之外，使其无法与无关的排队提示合并。如果重试仍然滞留或无法入队，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: {
        default: true,
        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 未设置时，直接/来源聊天使用所选运行时或框架的默认值，但内部 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。共享的主会话仍不受这些频道限制的窗口化影响。客户端压缩仍会汇总较旧的持久历史记录；生成的摘要与带窗口的最近轮次一起保留。这些限制不会删除已存储的消息。原生运行时管理自己的对话记录历史。

提供方侧的压缩使用准备好的对话记录窗口。网关触发的压缩从当前会话记录的主对话中解析关联对端；缺失或过时的路由事实不会选择另一个对端的覆盖设置。

频道提供的最近消息上下文是一个独立的窗口。例如，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: {
        default: true,
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    },
  },
}

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