Messages

这个页面介绍 OpenClaw 如何处理入站消息、Session、队列、流式传输和推理可见性。

消息流转（概览）

入站消息
  -> 路由/绑定 -> Session 键
  -> 队列（如果有运行中的任务）
  -> Agent 运行（流式传输 + 工具）
  -> 出站回复（Channel 限制 + 分块）

关键配置项：

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

详见配置完整架构。

入站去重

Channel 可能在重连后重新投递同一条消息。OpenClaw 会维护一个短期缓存，以 channel/account/peer/session/message id 为键，这样重复投递不会触发另一次 Agent 运行。

入站防抖

来自同一发送者的快速连续消息可以通过 messages.inbound 批量合并为单次 Agent 回合。防抖的作用范围是每个 channel + 对话，并使用最新消息进行回复线程/ID 处理。

配置（全局默认 + 每个 Channel 的覆盖）：

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

注意：

  • 防抖只适用于纯文本消息；媒体/附件会立即刷新。
  • 控制命令会绕过防抖，保持独立。

Session 和设备

Session 由 Gateway 拥有，而不是客户端。

  • 直接聊天会合并到 Agent 主 Session 键。
  • 群组/频道有自己的 Session 键。
  • Session 存储和记录保存在 Gateway 主机上。

多个设备/Channel 可以映射到同一个 Session，但历史记录不会完全同步回每个客户端。建议：长对话使用一个主设备，避免上下文分歧。Control UI 和 TUI 始终显示 Gateway 支持的 Session 记录，它们是真实来源。

详见：Session 管理。

入站消息体和历史上下文

OpenClaw 将 Prompt 消息体和命令消息体分开：

  • Body：发送给 Agent 的 Prompt 文本。可能包含 Channel 信封和可选的历史包装器。
  • CommandBody：用于指令/命令解析的原始用户文本。
  • RawBody：CommandBody 的旧版别名（为兼容性保留）。

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

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

对于非直接聊天（群组/频道/房间），当前消息体会加上发送者标签前缀（与历史条目使用的样式相同）。这让实时消息和队列/历史消息在 Agent Prompt 中保持一致。

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

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

队列和后续处理

如果已有运行中的任务，入站消息可以排队、引导到当前运行，或收集用于后续回合。

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

详见：队列。

流式传输、分块和批处理

块流式传输会在模型生成文本块时发送部分回复。分块会遵守 Channel 文本限制，避免拆分代码围栏。

关键设置：

  • 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（块回复之间的类人暂停）
  • Channel 覆盖：*.blockStreaming 和 *.blockStreamingCoalesce（非 Telegram Channel 需要显式设置 *.blockStreaming: true）

详见：流式传输 + 分块。

推理可见性和 Token

OpenClaw 可以显示或隐藏模型推理：

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

详见：思考 + 推理指令和 Token 使用。

前缀、线程和回复

出站消息格式在 messages 中集中管理：

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

详见：配置和 Channel 文档。