消息

本页把 OpenClaw 如何处理入站消息、sessions、队列、streaming 与 reasoning 可见性串起来。

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

关键旋钮主要在配置里：

- ''messages.*''：前缀、队列与群聊行为。

- ''agents.defaults.*''：block streaming 与 chunking 默认值。

- 通道覆盖（''channels.whatsapp.*''、''channels.telegram.*'' 等）：上限与 streaming 开关。

完整 schema 见 ''Configuration''。

通道在重连后可能会重投递同一条消息。OpenClaw 会维护一个短生命周期的 cache（按 channel/account/peer/session/message id 做 key），避免重复投递触发第二次 agent run。

同一发送者在短时间内连续发送多条消息时，可以通过 ''messages.inbound'' 将它们合并为一次 agent turn。防抖以通道 + 会话为作用域，并使用"最新一条消息"作为 reply threading/IDs 的来源。

配置（全局默认 + per-channel 覆盖）：

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

说明：

- 防抖只作用于纯文本；媒体/附件会立刻 flush。

- 控制命令会绕过防抖，保持为单独消息。

Sessions 由 gateway 持有，而不是客户端。

- 私信默认折叠进 agent 的 main session key。

- 群聊/频道使用独立 session keys。

- session store 与 transcripts 存在 gateway 主机上。

多个设备/通道可以映射到同一个 session，但历史不会 100% 同步回所有客户端。建议：长对话尽量使用一个主设备，避免上下文分叉。Control UI 与 TUI 总是展示 gateway-backed transcript，因此它们是事实来源。

详情：''/concepts/session''。

ReferenceConceptsMessagesPage step 04: P7

OpenClaw 把 prompt body 与 command body 区分开：

- ''Body''：发送给 agent 的 prompt 文本，可能包含通道 envelope 与可选历史 wrappers。

- ''CommandBody''：用于 directive/command 解析的原始用户文本。

- ''RawBody''：''CommandBody'' 的 legacy alias（为兼容保留）。

当通道提供历史上下文时，会使用统一 wrapper：

- ''[Chat messages since your last reply - for context]''

- ''[Current message - respond to this]''

对非直聊（群/频道/rooms），当前消息正文会带上发送者 label（与历史 entries 同风格），让实时消息与队列/历史消息在 prompt 中更一致。

历史缓冲是 pending-only：包含那些因为 mention gating 没触发 run 的群消息，并排除已经写入 session transcript 的消息。

指令剥离仅适用于''当前消息''块，确保历史内容保持不变。包装历史的通道应将 ''CommandBody''（或 ''RawBody''）设置为原始消息文本，将 ''Body'' 设置为组合提示。历史缓冲区可以通过 ''messages.groupChat.historyLimit''（全局默认值）和通道覆盖（例如 ''channels.slack.historyLimit''、''channels.telegram.accounts.<id>.historyLimit''）配置；设置为 ''0'' 可禁用。

ReferenceConceptsMessagesPage step 05: P11

当某个 run 正在进行时，新的入站消息可以被排队、注入当前 run 做 steer，或收集为后续 turn：

- 通过 ''messages.queue''（以及 ''messages.queue.byChannel''）配置。

- 模式：''interrupt''、''steer''、''followup''、''collect''，以及 backlog variants。

详情：''/concepts/queue''。

ReferenceConceptsMessagesPage step 06: P5

ReferenceConceptsMessagesPage step 06: P6

block streaming 会在模型产生 text blocks 时逐块发送部分回复。chunking 会遵守通道文本上限，并尽量避免把 fenced code 拆断。

关键设置：

- ''agents.defaults.blockStreamingDefault''（''on|off''，默认 off）

- ''agents.defaults.blockStreamingBreak''（''text_end|message_end''）

- ''agents.defaults.blockStreamingChunk''（''minChars|maxChars|breakPreference''）

- ''agents.defaults.blockStreamingCoalesce''（基于 idle 的合并）

- ''agents.defaults.humanDelay''（类人停顿）

- 通道覆盖：''*.blockStreaming'' 与 ''*.blockStreamingCoalesce''（非 Telegram 通道需要显式 ''*.blockStreaming: true''）

OpenClaw 可以显示或隐藏模型 reasoning：

- ''/reasoning on|off|stream'' 控制可见性。

- reasoning 内容只要被模型产生，仍会计入 token 使用量。

- Telegram 支持把 reasoning 流式写进 draft bubble。

详情：''/tools/thinking''、''/token-use''。

出站格式集中在 ''messages''：

- ''messages.responsePrefix''（出站前缀）与 ''channels.whatsapp.messagePrefix''（WhatsApp 入站前缀）

- 通过 ''replyToMode'' 与各通道默认值控制 reply threading

详情：''/gateway/configuration#messages'' 与各通道文档。