Messages（消息处理）

本页将 OpenClaw 处理入站消息的完整链路串联起来，涵盖会话管理、消息队列、流式输出和推理可见性。

消息处理流程（高层视图）

入站消息
  -> 路由/绑定 -> 会话 key
  -> 队列（若有 run 正在进行）
  -> Agent run（流式输出 + 工具调用）
  -> 出站回复（渠道限制 + 分块）

关键配置项：

• messages.*：前缀、队列、群组行为。
• agents.defaults.*：块流式默认值和分块默认值。
• 渠道覆盖（channels.whatsapp.*、channels.telegram.* 等）：上限和流式开关。

完整配置 Schema 见 Configuration。

入站去重

渠道在重新连接后可能会重复投递同一消息。OpenClaw 维护一个短期缓存，以渠道/账户/对话/会话/消息 ID 为 key，避免重复触发 Agent run。

入站防抖

来自同一发送者的连续快速消息可以通过 messages.inbound 合并为单个 Agent 轮次。防抖按渠道 + 对话范围生效，用最新消息作为回复线程/ID。

配置（全局默认 + 按渠道覆盖）：

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

注意：

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

会话与设备

会话由 Gateway 管理，不属于客户端。

• 私聊合并到 Agent 主会话 key。
• 群组/频道拥有各自独立的会话 key。
• 会话存储和记录位于 Gateway 宿主机。

多个设备/渠道可以映射到同一会话，但历史记录不会完全同步回所有客户端。建议：长对话使用一个主设备，避免上下文分叉。控制 UI 和 TUI 始终显示 Gateway 中的会话记录，是唯一的权威来源。

详情见：Session management。

入站消息体与历史上下文

OpenClaw 将**提示体（Body）与命令体（CommandBody）**分开处理：

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

当渠道提供历史记录时，使用共享的包装格式：

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

对于非私聊（群组/频道/房间），当前消息体会以发送者标签为前缀（与历史条目使用相同格式）。这保证了实时消息和队列/历史消息在 Agent 提示中的一致性。

历史缓冲区是待处理消息专用的：只包含未触发 run 的群组消息（例如基于 @ 提及的消息），不包含已在会话记录中的消息。

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

队列与后续跟进

如果当前有 run 正在执行，入站消息可以排队、引导进入当前 run，或收集为后续跟进轮次。

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

详情见：Queueing。

流式输出、分块与批处理

块流式输出（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。

推理可见性与 Token 消耗

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

• /reasoning on|off|stream 控制可见性。
• 推理内容在模型生成时仍计入 token 用量，无论是否显示。
• Telegram 支持将推理流式输出到草稿气泡中。

详情见：Thinking + reasoning 指令 和 Token 用量。

前缀、线程与回复

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

• messages.responsePrefix、channels.<channel>.responsePrefix 和 channels.<channel>.accounts.<id>.responsePrefix（出站前缀层叠规则），以及 channels.whatsapp.messagePrefix（WhatsApp 入站前缀）
• 通过 replyToMode 和按渠道默认值控制回复线程

详情见：Configuration 和各渠道文档。