消息（Messages）

本页将 OpenClaw 如何处理入站消息、会话、队列、流式传输和推理可见性联系在一起。

消息流（高级）

入站消息（Inbound message）
  -> 路由/绑定（routing/bindings） -> 会话密钥（session key）
  -> 队列（如果运行处于活动状态）
  -> 代理运行（streaming + tools）
  -> 出站回复（频道限制 + 分块）

关键旋钮位于配置中：

  • messages.* 用于前缀、队列和群组行为。
  • agents.defaults.* 用于块流式传输和分块默认值。
  • 频道覆盖（channels.whatsapp.*、channels.telegram.* 等）用于上限和流式切换。

有关完整架构，请参见 配置（Configuration）。

入站去重（Inbound dedupe）

频道可以在重新连接后重新传递相同的消息。OpenClaw 保留一个由频道/账户/对等方/会话/消息 id 键控的短期缓存，以便重复传递不会触发另一个代理运行。

入站防抖（Inbound debouncing）

来自同一发送者的快速连续消息可以通过 messages.inbound 批量处理到单个代理轮次中。防抖的作用域限定在每个频道 + 对话，并使用最新消息进行回复线程/ID。

配置（全局默认 + 每频道覆盖）：

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}

注意：

  • 防抖适用于仅文本消息；媒体/附件立即刷新。
  • 控制命令绕过防抖，因此它们保持独立。

会话和设备（Sessions and devices）

会话由网关（gateway）拥有，而不是客户端。

  • 直接聊天折叠到代理主会话密钥中。
  • 群组/频道获得自己的会话密钥。
  • 会话存储和记录存储在网关主机上。

多个设备/频道可以映射到同一个会话，但历史记录不会完全同步回每个客户端。建议：使用一个主要设备进行长对话，以避免分散的上下文。控制 UI 和 TUI 始终显示网关支持的会话记录，因此它们是真实来源。

详细信息：会话管理（Session management）。

入站正文和历史上下文（Inbound bodies and history context）

OpenClaw 将**提示正文（prompt body）与命令正文（command body）**分开：

  • Body：发送给代理的提示文本。这可能包括频道信封和可选的历史包装器。
  • CommandBody：用于指令/命令解析的原始用户文本。
  • RawBody：CommandBody 的遗留别名（为兼容性保留）。

当频道提供历史记录时，它使用共享包装器：

  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]

对于非直接聊天（群组/频道/房间），当前消息正文以发送者标签为前缀（与历史条目使用的样式相同）。这使实时和队列/历史消息在代理提示中保持一致。

历史缓冲区是仅待处理：它们包括未触发运行的群组消息（例如，提及门控消息），并排除会话记录中已有的消息。

指令剥离仅适用于当前消息部分，因此历史记录保持完整。包装历史记录的频道应将 CommandBody（或 RawBody）设置为原始消息文本，并将 Body 保持为组合提示。历史缓冲区可通过 messages.groupChat.historyLimit（全局默认）和每频道覆盖（如 channels.slack.historyLimit 或 channels.telegram.accounts.<id>.historyLimit）配置（设置 0 以禁用）。

队列和后续（Queueing and followups）

如果运行已经处于活动状态，入站消息可以排队、引导到当前运行或收集用于后续轮次。

  • 通过 messages.queue（和 messages.queue.byChannel）配置。
  • 模式：interrupt、steer、followup、collect，加上积压变体。

详细信息：队列（Queueing）。

流式传输、分块和批处理（Streaming, chunking, and batching）

块流式传输（Block streaming）在模型生成文本块时发送部分回复。分块尊重频道文本限制并避免拆分围栏代码。

关键设置：

  • agents.defaults.blockStreamingDefault（on|off，默认 off）
  • agents.defaults.blockStreamingBreak（text_end|message_end）
  • agents.defaults.blockStreamingChunk（minChars|maxChars|breakPreference）
  • agents.defaults.blockStreamingCoalesce（基于空闲的批处理）
  • agents.defaults.humanDelay（块回复之间的类人暂停）
  • 频道覆盖：*.blockStreaming 和 *.blockStreamingCoalesce（非 Telegram 频道需要显式 *.blockStreaming: true）

详细信息：流式传输 + 分块（Streaming + chunking）。

推理可见性和令牌（Reasoning visibility and tokens）

OpenClaw 可以暴露或隐藏模型推理：

  • /reasoning on|off|stream 控制可见性。
  • 推理内容在模型生成时仍计入令牌使用量。
  • Telegram 支持将推理流式传输到草稿气泡中。

详细信息：思考 + 推理指令（Thinking + reasoning directives） 和 令牌使用（Token use）。

前缀、线程和回复（Prefixes, threading, and replies）

出站消息格式化在 messages 中集中：

  • messages.responsePrefix（出站前缀）和 channels.whatsapp.messagePrefix（WhatsApp 入站前缀）
  • 通过 replyToMode 和每频道默认值进行回复线程

详细信息：配置（Configuration） 和频道文档。

← 返回文档首页