OpenClaw 使用一套完整的管道处理入站消息：先通过短期缓存去重避免重复触发 Agent 运行，再对同一发送者的连续文本消息进行防抖合并（默认 2 秒，可按渠道调整）。消息被路由到对应会话后，若已有运行则按队列模式（引导、后续、收集、中断）处理，最终通过块流式分块输出到渠道。推理可见性可通过 /reasoning 指令控制。全部配置位于 messages.* 和 agents.defaults.*，支持全局默认值与渠道覆盖。

OpenClaw 消息处理配置：入站去重、防抖、队列与流式输出

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

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

关键配置项：

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

完整配置 Schema 见 Configuration。

入站去重（Deduplication）

渠道在重新连接后可能重复投递同一消息。OpenClaw 维护一个短期缓存，以 channel/account/peer/session/message id 为 key，避免重复触发 Agent run。

入站防抖（Debouncing）

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

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

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

注意：

• 防抖只适用于纯文本消息；媒体/附件消息会立即处理。
• 控制命令绕过防抖（/reasoning 等），保持独立执行。如果渠道显式允许同发送者 DM 合并，则控制命令也可在防抖窗口内合并。

会话与设备（Sessions and Devices）

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

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

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

详情见：Session management。

工具结果元数据（Tool Result Metadata）

toolResult.content 是模型可见的结果；toolResult.details 是运行时元数据，用于 UI 渲染、诊断、媒体传递和插件。

OpenClaw 保持边界明确：

• toolResult.details 在 Provider 重播和压缩输入前会被剥离。
• 持久化的会话记录只保留有限制大小的 details；过大的元数据被替换为紧凑摘要，标记 persistedDetailsTruncated: true。
• 插件和工具应将模型必须阅读的文本放入 content，不要仅放入 details。

入站消息体与历史上下文（Inbound Bodies and History Context）

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

• BodyForAgent：面向模型的当前消息主要文本。渠道插件应将此字段保持为发送者的当前提示文本。
• Body：旧版提示回退。可能包含渠道信封和可选的历史包装，但当前渠道不应依赖它作为主要模型输入（当 BodyForAgent 可用时）。
• CommandBody：用于指令/命令解析的原始用户文本。
• RawBody：CommandBody 的旧版别名（为兼容性保留）。

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

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

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

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

指令剥离只适用于当前消息部分，历史记录保持完整。提供历史的渠道应将 CommandBody（或 RawBody）设为原始消息文本，Body 设为完整的组合提示。结构化历史、回复、转发和渠道元数据在提示组装期间以 user 角色的不可信上下文块呈现。历史缓冲区可通过 messages.groupChat.historyLimit（全局默认）以及按渠道覆盖（如 channels.slack.historyLimit、channels.telegram.accounts.<id>.historyLimit，设为 0 即禁用）进行配置。

队列与后续跟进（Queueing and Followups）

如果当前有 run 正在进行，入站消息默认引导到当前 run。messages.queue 选择活跃运行的消息如何排队：引导（steer）、后续（followup）、收集（collect）或中断（interrupt）。

• 通过 messages.queue（和 messages.queue.byChannel）配置。
• 默认模式为 steer，附带 500ms 的 Codex 引导批处理和后续/收集队列防抖。
• 模式：steer、followup、collect、interrupt。

详情见：Command queue 和 Steering queue。

渠道运行所有权（Channel Run Ownership）

渠道插件应在消息进入会话队列之前维护顺序、防抖输入并应用传输背压。它们不应在 Agent 轮次周围施加单独的超时。一旦消息被路由到会话，长时间运行的工作由会话、工具和运行时生命周期管理，所有渠道一致报告和恢复慢轮次。

流式输出、分块与批处理（Streaming, Chunking, and Batching）

块流式输出在模型生成文本块时实时发送部分回复。分块遵循渠道文本限制，避免在代码围栏中间断开。

关键配置项：

• 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 消耗（Reasoning Visibility and Tokens）

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

• /reasoning on|off|stream 控制可见性。
• 推理内容由模型生成时仍计入 token 用量，无论是否显示。
• Telegram 支持将推理流式输出到临时草稿气泡（最终交付时删除）；使用 /reasoning on 可持久显示推理输出。

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

前缀、线程与回复（Prefixes, Threading, and Replies）

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

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

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

静默回复（Silent Replies）

精确的静默标记 NO_REPLY / no_reply 表示“不要交付用户可见的回复”。当轮次还有待处理的工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本但仍交付媒体附件。

OpenClaw 根据对话类型处理：

• 私聊从不接收 NO_REPLY 提示引导。如果私聊运行意外返回裸静默标记，OpenClaw 会抑制它，而不重写或交付。
• 群组/频道默认仅在自动群组回复时允许静默。在 message_tool 可见回复模式下，静默意味着模型不调用 message(action=send)。
• 内部编排默认允许静默。

OpenClaw 还使用静默回复处理非私聊中在助手回复前的内部运行器失败场景，使群组/频道不会看到网关错误样板。私聊默认显示紧凑失败信息；仅当 /verbose full 启用时才显示原始运行器详情。

默认值位于 agents.defaults.silentReply；surfaces.<id>.silentReply 可以按展示面覆盖群组/内部策略。

所有展示面都会丢弃裸静默回复，因此父会话保持静默，而不是将标记文本重写为回退闲聊。

相关文档

• Message lifecycle refactor — 目标持久化的发送与接收设计
• Streaming — 实时消息交付
• Retry — 消息交付重试行为
• Queue — 消息处理队列
• Channels — 消息平台集成

常见问题

消息重复触发 Agent run 怎么办？

默认已启用短期缓存去重，以 channel/account/peer/session/message id 为 key。如果仍出现重复，检查渠道是否开启了重连重发，或确认配置中没有关闭去重（messages.inbound 没有禁用缓存）。

入站防抖怎么配置？

在 messages.inbound.debounceMs 中设置全局默认值（毫秒），或通过 messages.inbound.byChannel 按渠道覆盖。仅作用于纯文本消息，媒体和控制命令会立即处理。

流式输出在哪里开启？

全局默认关闭。需要在 agents.defaults.blockStreamingDefault 设置为 on，非 Telegram 渠道还需在渠道配置中显式设置 *.blockStreaming: true。详细设置见 Streaming。