[OpenClaw 文档]代理--消息与投递

2026年 5月 17日 OpenClaw SE_You
[OpenClaw 文档]代理--消息与投递

本文档汇总了 OpenClaw 官方文档站 代理 > 消息与投递 子模块下的全部 4 篇内容，源自 docs.openclaw.ai/zh-CN。

📑 本文目录（4 篇）

  1. 消息
  2. 流式传输和分块
  3. 重试策略
  4. 命令队列

📄 消息

原文：https://docs.openclaw.ai/zh-CN/concepts/messages

OpenClaw 通过会话解析、排队、流式传输、工具执行和推理可见性组成的流水线处理入站消息。本页展示从入站消息到回复的路径。

消息流程（高层级）

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

关键控制项位于配置中：

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

完整 schema 见 配置。

入站去重

频道可能会在重新连接后重新投递同一条消息。OpenClaw 会保留一个短生命周期缓存，以频道/账户/对端/会话/消息 ID 为键，避免重复投递触发另一次智能体运行。

入站防抖

来自同一发送者的快速连续消息可以通过 messages.inbound 合并为单个智能体轮次。防抖按每个频道 + 对话划定范围，并使用最新消息进行回复线程/ID 关联。

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

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

注意：

  • 防抖适用于纯文本消息；媒体/附件会立即刷新。
  • 控制命令会绕过防抖，因此它们保持独立。显式选择加入同发送者私信合并的频道，可以让私信命令留在防抖窗口内，以便分开发送的负载加入同一个智能体轮次。

会话和设备

会话由 Gateway 网关拥有，而不是由客户端拥有。

  • 直接聊天会折叠进智能体主会话键。
  • 群组/频道会获得自己的会话键。
  • 会话存储和转录记录位于 Gateway 网关主机上。

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

详情：会话管理。

工具结果元数据

工具结果 content 是模型可见的结果。工具结果 details 是用于 UI 渲染、诊断、媒体投递和插件的运行时元数据。

OpenClaw 会明确保持这条边界：

  • toolResult.details 会在提供商重放和压缩输入前被剥离。
  • 持久化的会话转录记录只保留有界的 details；过大的元数据会替换为带有 persistedDetailsTruncated: true 标记的紧凑摘要。
  • 插件和工具应将模型必须读取的文本放在 content 中，而不是只放在 details 中。

入站正文和历史上下文

OpenClaw 会区分提示正文和命令正文：

  • BodyForAgent：当前消息中主要面向模型的文本。频道插件应让它聚焦于发送者当前承载提示的文本。
  • Body：旧版提示回退。这可能包含频道信封和可选的历史包装，但当前频道在 BodyForAgent 可用时不应依赖它作为主要模型输入。
  • 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 可禁用）。

排队和后续轮次

如果已有运行处于活跃状态，入站消息可以排队、Steer 到当前运行中，或收集为后续轮次。

  • 通过 messages.queue（以及 messages.queue.byChannel）配置。
  • 默认模式为 steer，当 Steering 回退到排队后续投递时，会使用 500ms 的后续防抖。
  • 模式：steer、followup、collect、steer-backlog、interrupt，以及旧版一次一个的 queue 模式。

详情：命令队列 和 Steering queue。

频道运行所有权

频道插件可以在消息进入会话队列之前保留顺序、对输入进行防抖，并应用传输层背压。它们不应围绕智能体轮次本身施加单独的超时。消息一旦路由到会话，长时间运行的工作就由会话、工具和运行时生命周期管理，这样所有频道都能一致地报告并从慢轮次中恢复。

流式传输、分块和批处理

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

关键设置：

  • 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）

详情：流式传输 + 分块。

推理可见性和 token

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

  • /reasoning on|off|stream 控制可见性。
  • 由模型生成时，推理内容仍计入 token 用量。
  • Telegram 支持将推理流式传输到临时草稿气泡中，最终投递后会删除；使用 /reasoning on 可获得持久推理输出。

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

前缀、线程和回复

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

  • messages.responsePrefix、channels.<channel>.responsePrefix 和 channels.<channel>.accounts.<id>.responsePrefix（出站前缀级联），以及 channels.whatsapp.messagePrefix（WhatsApp 入站前缀）
  • 通过 replyToMode 和按频道默认值进行回复线程关联

详情：配置 和频道文档。

静默回复

精确的静默 token NO_REPLY / no_reply 表示“不要投递用户可见的回复”。
当一个轮次还有待处理的工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本，但仍会投递媒体附件。
OpenClaw 会按对话类型解析该行为：

  • 直接对话默认不允许静默，并会将裸静默回复重写为简短的可见回退。
  • 群组/频道默认允许静默。
  • 内部编排默认允许静默。

OpenClaw 还会将静默回复用于在非直接聊天中、任何助手回复之前发生的内部运行器失败，因此群组/频道不会看到 Gateway 网关错误样板文本。直接聊天默认显示紧凑的失败文案；只有当 /verbose 为 on 或 full 时，才会显示原始运行器详情。

默认值位于 agents.defaults.silentReply 和 agents.defaults.silentReplyRewrite 下；surfaces.<id>.silentReply 和 surfaces.<id>.silentReplyRewrite 可以按 surface 覆盖它们。

当父会话有一个或多个待处理的已生成子智能体运行时，裸静默回复会在所有 surface 上被丢弃，而不是被重写，因此父会话会保持安静，直到子完成事件投递真正的回复。

相关

📄 流式传输和分块

原文：https://docs.openclaw.ai/zh-CN/concepts/streaming

OpenClaw 有两个独立的流式传输层：

  • 分块流式传输（渠道）： 在 assistant 写入时发出完成的块。这些是普通渠道消息（不是令牌增量）。
  • 预览流式传输（Telegram/Discord/Slack）： 在生成时更新临时预览消息。

目前没有向渠道消息发送的真正令牌增量流式传输。预览流式传输基于消息（发送 + 编辑/追加）。

分块流式传输（渠道消息）

分块流式传输会在 assistant 输出可用时，以较粗粒度的分块发送输出。

Model output
  └─ text_delta/events
       ├─ (blockStreamingBreak=text_end)
       │    └─ chunker emits blocks as buffer grows
       └─ (blockStreamingBreak=message_end)
            └─ chunker flushes at message_end
                   └─ channel send (block replies)

图例：

  • text_delta/events：模型流事件（对于非流式模型可能较稀疏）。
  • chunker：EmbeddedBlockChunker，应用最小/最大边界 + 断点偏好。
  • channel send：实际出站消息（块回复）。

控制项：

  • agents.defaults.blockStreamingDefault："on"/"off"（默认关闭）。
  • 渠道覆盖：*.blockStreaming（以及按账号的变体），用于按渠道强制设为 "on"/"off"。
  • agents.defaults.blockStreamingBreak："text_end" 或 "message_end"。
  • agents.defaults.blockStreamingChunk：{ minChars, maxChars, breakPreference? }。
  • agents.defaults.blockStreamingCoalesce：{ minChars?, maxChars?, idleMs? }（发送前合并流式块）。
  • 渠道硬上限：*.textChunkLimit（例如 channels.whatsapp.textChunkLimit）。
  • 渠道分块模式：*.chunkMode（默认 length，newline 会先按空行（段落边界）拆分，再按长度分块）。
  • Discord 软上限：channels.discord.maxLinesPerMessage（默认 17），用于拆分过高的回复以避免 UI 裁切。

边界语义：

  • text_end：只要 chunker 发出块就流式发送块；在每个 text_end 刷新。
  • message_end：等到 assistant 消息完成后，再刷新缓冲的输出。

如果缓冲文本超过 maxChars，message_end 仍会使用 chunker，因此它可以在末尾发出多个分块。

分块流式传输中的媒体交付

MEDIA: 指令是普通交付元数据。当分块流式传输提前发送媒体块时，OpenClaw 会记住该轮次的这次交付。如果最终 assistant 载荷重复相同的媒体 URL，最终交付会移除重复媒体，而不是再次发送附件。

完全重复的最终载荷会被抑制。如果最终载荷在已经流式传输的媒体周围添加了不同文本，OpenClaw 仍会发送新文本，同时保持媒体只交付一次。这可以防止在 Telegram 等渠道上，当 agent 在流式传输期间发出 MEDIA: 且提供商也在完整回复中包含它时，出现重复语音消息或文件。

分块算法（低/高边界）

分块由 EmbeddedBlockChunker 实现：

  • 低边界： 直到缓冲区 >= minChars 才发出（除非强制）。
  • 高边界： 优先在 maxChars 之前拆分；如果强制，则在 maxChars 处拆分。
  • 断点偏好： paragraph → newline → sentence → whitespace → 硬断点。
  • 代码围栏： 绝不在围栏内拆分；当在 maxChars 处强制拆分时，会关闭 + 重新打开围栏以保持 Markdown 有效。

maxChars 会被限制到渠道的 textChunkLimit，因此你不能超过每个渠道的上限。

合并（合并流式块）

启用分块流式传输后，OpenClaw 可以在发送前合并连续的块分块。这可以减少“单行刷屏”，同时仍提供渐进式输出。

  • 合并会等待空闲间隙（idleMs）后再刷新。
  • 缓冲区受 maxChars 限制，超过时会刷新。
  • minChars 会防止过小片段发送，直到累积足够文本（最终刷新始终会发送剩余文本）。
  • 连接符派生自 blockStreamingChunk.breakPreference（paragraph → \n\n，newline → \n，sentence → 空格）。
  • 可以通过 *.blockStreamingCoalesce 使用渠道覆盖（包括按账号配置）。
  • 除非覆盖，否则 Signal/Slack/Discord 的默认合并 minChars 会提升到 1500。

块之间的拟人节奏

启用分块流式传输后，你可以在块回复之间（第一个块之后）添加随机暂停。这会让多气泡回复感觉更自然。

  • 配置：agents.defaults.humanDelay（可通过 agents.list[].humanDelay 按 agent 覆盖）。
  • 模式：off（默认）、natural（800-2500ms）、custom（minMs/maxMs）。
  • 仅适用于块回复，不适用于最终回复或工具摘要。

“流式输出分块或全部内容”

这对应于：

  • 流式输出分块： blockStreamingDefault: "on" + blockStreamingBreak: "text_end"（边生成边发出）。非 Telegram 渠道还需要 *.blockStreaming: true。
  • 在末尾流式输出全部内容： blockStreamingBreak: "message_end"（一次刷新；如果很长，可能会有多个分块）。
  • 无分块流式传输： blockStreamingDefault: "off"（仅最终回复）。

渠道说明： 除非显式将 *.blockStreaming 设为 true，否则分块流式传输为关闭。渠道可以在没有块回复的情况下流式传输实时预览（channels.<channel>.streaming）。

配置位置提醒：blockStreaming* 默认值位于 agents.defaults 下，而不是根配置。

预览流式传输模式

规范键：channels.<channel>.streaming

模式：

  • off：禁用预览流式传输。
  • partial：单个预览，会被最新文本替换。
  • block：以分块/追加步骤更新预览。
  • progress：生成期间的进度/状态预览，完成时给出最终答案。

streaming.mode: "block" 是一种预览流式传输模式，适用于 Discord 和 Telegram 等支持编辑的渠道。它不会在这些渠道上启用渠道块交付。想要普通块回复时，请使用 streaming.block.enabled 或旧版 blockStreaming 渠道键。Microsoft Teams 是例外：它没有草稿预览块传输，因此 streaming.mode: "block" 会映射到 Teams 块交付，而不是原生 partial/progress 流式传输。

渠道映射

渠道 off partial block progress
Telegram ✅ ✅ ✅ 可编辑进度草稿
Discord ✅ ✅ ✅ 可编辑进度草稿
Slack ✅ ✅ ✅ ✅
Mattermost ✅ ✅ ✅ ✅
MS Teams ✅ ✅ ✅ 原生进度流

仅限 Slack：

  • channels.slack.streaming.nativeTransport 会在 channels.slack.streaming.mode="partial" 时切换 Slack 原生流式传输 API 调用（默认：true）。
  • Slack 原生流式传输和 Slack assistant 线程状态需要一个回复线程目标。顶层私信不会显示这种线程样式预览，但它们仍可以使用 Slack 草稿预览帖子和编辑。

旧版键迁移：

  • Telegram：旧版 streamMode 以及标量/布尔 streaming 值会被 doctor/config 兼容路径检测并迁移到 streaming.mode。
  • Discord：streamMode + 布尔 streaming 仍是 streaming 枚举的运行时别名；运行 openclaw doctor --fix 可重写持久化配置。
  • Slack：streamMode 仍是 streaming.mode 的运行时别名；布尔 streaming 仍是 streaming.mode 加 streaming.nativeTransport 的运行时别名；旧版 nativeStreaming 仍是 streaming.nativeTransport 的运行时别名。运行 openclaw doctor --fix 可重写持久化配置。

运行时行为

Telegram：

  • 使用 sendMessage + editMessageText 在私信和群组/话题中更新预览。
  • 最终文本会原地编辑活动预览；较长的最终文本会复用该消息作为第一个分块，并只发送剩余分块。
  • progress 模式会在可编辑的状态草稿中保留工具进度，在完成时清除该草稿，并通过普通交付发送最终答案。
  • 如果在确认完成文本之前最终编辑失败，OpenClaw 会使用普通最终交付并清理过期预览。
  • 当 Telegram 分块流式传输显式启用时，会跳过预览流式传输（以避免双重流式传输）。
  • /reasoning stream 可以将推理写入临时预览，该预览会在最终交付后删除。

Discord：

  • 使用发送 + 编辑预览消息。
  • block 模式使用草稿分块（draftChunk）。
  • 当 Discord 分块流式传输显式启用时，会跳过预览流式传输。
  • 最终媒体、错误和显式回复载荷会取消待处理预览，而不刷新新草稿，然后使用普通交付。

Slack：

  • partial 可在可用时使用 Slack 原生流式传输（chat.startStream/append/stop）。
  • block 使用追加式草稿预览。
  • progress 使用状态预览文本，然后给出最终答案。
  • 没有回复线程的顶层私信会使用草稿预览帖子和编辑，而不是 Slack 原生流式传输。
  • 原生和草稿预览流式传输会抑制该轮次的块回复，因此 Slack 回复只会通过一种交付路径流式传输。
  • 最终媒体/错误载荷和进度最终内容不会创建一次性草稿消息；只有可以编辑预览的文本/块最终内容会刷新待处理草稿文本。

Mattermost：

  • 将思考、工具活动和部分回复文本流式传输到单个草稿预览帖子中，当最终答案可以安全发送时原地完成。
  • 如果预览帖子在完成时已被删除或不可用，则回退为发送新的最终帖子。
  • 最终媒体/错误载荷会在普通交付之前取消待处理预览更新，而不是刷新临时预览帖子。

Matrix：

  • 当最终文本可以复用预览事件时，草稿预览会原地完成。
  • 纯媒体、错误和回复目标不匹配的最终内容会在普通交付之前取消待处理预览更新；已经可见的过期预览会被撤回。

工具进度预览更新

预览流式传输还可以包含工具进度更新，即“正在搜索网络”“正在读取文件”或“正在调用工具”等短状态行，它们会在工具运行时、最终回复之前出现在同一条预览消息中。这样可以让多步骤工具轮次在首次思考预览和最终答案之间保持视觉上的活跃，而不是沉默。

支持的界面：

  • Discord、Slack、Telegram 和 Matrix 默认会在启用预览流式传输时，将工具进度流式传输到实时预览编辑中。Microsoft Teams 在个人聊天中使用其原生进度流。
  • Telegram 自 v2026.4.22 起已默认启用工具进度预览更新；保持启用可保留已发布的行为。
  • Mattermost 已经将工具活动折叠进其单个草稿预览帖子中（见上文）。
  • 工具进度编辑会遵循当前的预览流式传输模式；当预览流式传输为 off，或分块流式传输已接管消息时，会跳过这些编辑。在 Telegram 上，streaming.mode: "off" 仅发送最终结果：通用进度闲聊也会被抑制，而不是作为独立 Status 消息发送；审批提示、媒体载荷和错误仍会正常路由。
  • 如需保留预览流式传输但隐藏工具进度行，请将该渠道的 streaming.preview.toolProgress 设为 false。如需保持工具进度行可见但隐藏命令/执行文本，请将 streaming.preview.commandText 设为 "status"，或将 streaming.progress.commandText 设为 "status"；默认值为 "raw"，以保留已发布的行为。此策略由使用 OpenClaw 紧凑进度渲染器的草稿/进度渠道共享，包括 Discord、Matrix、Microsoft Teams、Mattermost、Slack 草稿预览和 Telegram。若要完全禁用预览编辑，请将 streaming.mode 设为 off。
  • Telegram 选中引用回复是一个例外：当 replyToMode 不是 "off" 且存在选中的引用文本时，OpenClaw 会跳过该轮的答案预览流，因此工具进度预览行无法渲染。没有选中引用文本的当前消息回复仍会保留预览流式传输。详情请参阅 Telegram 渠道文档。

保持进度行可见，但隐藏原始命令/执行文本：

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

在另一个紧凑进度渠道键下使用相同结构，例如 channels.discord、channels.matrix、channels.msteams、channels.mattermost，或 Slack 草稿预览。对于进度草稿模式，请将相同策略放在 streaming.progress 下：

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

相关

  • 消息生命周期重构 - 目标共享预览、编辑、流式传输和最终化设计
  • 进度草稿 - 在长轮次期间更新的可见进行中工作消息
  • 消息 - 消息生命周期和递送
  • Retry - 递送失败时的重试行为
  • 渠道 - 按渠道提供的流式传输支持

📄 重试策略

原文：https://docs.openclaw.ai/zh-CN/concepts/retry

目标

  • 按每个 HTTP 请求重试，而不是按多步骤流程重试。
  • 仅重试当前步骤，以保留顺序。
  • 避免重复执行非幂等操作。

默认值

  • 尝试次数：3
  • 最大延迟上限：30000 ms
  • 抖动：0.1（10%）
  • 提供商默认值：
  • Telegram 最小延迟：400 ms
  • Discord 最小延迟：500 ms

行为

模型提供商

  • OpenClaw 让提供商 SDK 处理常规的短重试。
  • 对于基于 Stainless 的 SDK（例如 Anthropic 和 OpenAI），可重试响应
    （408、409、429 和 5xx）可以包含 retry-after-ms 或
    retry-after。当该等待时间超过 60 秒时，OpenClaw 会注入
    x-should-retry: false，使 SDK 立即暴露错误，并让模型故障转移可以轮换到另一个凭证配置文件或备用模型。
  • 使用 OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS=<seconds> 覆盖上限。
    将其设为 0、false、off、none 或 disabled，即可让 SDK 在内部遵循较长的
    Retry-After 休眠。

Discord

  • 对速率限制错误（HTTP 429）、请求超时、HTTP 5xx 响应，
    以及 DNS 查询失败、连接重置、套接字关闭和 fetch 失败等瞬时传输故障进行重试。
  • 可用时使用 Discord retry_after，否则使用指数退避。

Telegram

  • 对瞬时错误（429、超时、连接/重置/关闭、暂时不可用）进行重试。
  • 可用时使用 retry_after，否则使用指数退避。
  • Markdown 解析错误不会重试；它们会回退到纯文本。

配置

在 ~/.openclaw/openclaw.json 中按提供商设置重试策略：

{
  channels: {
    telegram: {
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
    discord: {
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

备注

  • 重试按每个请求应用（发送消息、上传媒体、反应、投票、贴纸）。
  • 复合流程不会重试已完成的步骤。

相关

📄 命令队列

原文：https://docs.openclaw.ai/zh-CN/concepts/queue

我们通过一个很小的进程内队列串行化入站自动回复运行（所有渠道），避免多个智能体运行发生冲突，同时仍允许跨会话的安全并行。

原因

  • 自动回复运行可能成本较高（LLM 调用），并且当多条入站消息接近同时到达时可能发生冲突。
  • 串行化可以避免争用共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。

工作原理

  • 一个感知 lane 的 FIFO 队列会按可配置的并发上限清空每个 lane（未配置 lane 的默认值为 1；main 默认为 4，subagent 默认为 8）。
  • runEmbeddedPiAgent 按 会话键 入队（lane session:<key>），以保证每个会话只有一个活跃运行。
  • 每个会话运行随后会排入 全局 lane（默认为 main），因此整体并行度由 agents.defaults.maxConcurrent 限制。
  • 启用详细日志时，如果排队运行在开始前等待超过约 2 秒，会发出一条简短通知。
  • 输入状态指示仍会在入队时立即触发（如果该渠道支持），因此等待轮到当前运行时，用户体验不会改变。

默认值

未设置时，所有入站渠道表面都使用：

  • mode: "steer"
  • debounceMs: 500
  • cap: 20
  • drop: "summarize"

steer 是默认值，因为它能让活跃模型轮次保持响应，而无需
启动第二个会话运行。它会清空在下一个模型边界之前到达的所有 steering 消息。如果当前运行无法接受 steering，
OpenClaw 会回退到一个 followup 队列条目。

队列模式

入站消息可以 steer 当前运行、等待 followup 轮次，或两者都做：

  • steer：将 steering 消息排入活跃运行时。Pi 会在 当前助手轮次执行完其工具调用后、下一次 LLM 调用前，递送所有待处理 steering 消息；Codex app-server 会收到一个批量的 turn/steer。如果运行没有活跃地流式传输，或 steering 不可用，OpenClaw 会回退到一个 followup 队列条目。
  • queue（旧版）：旧的一次一个 steering。Pi 会在每个模型边界递送一条排队的 steering 消息；Codex app-server 会收到独立的 turn/steer 请求。除非你需要之前的串行化行为，否则优先使用 steer。
  • followup：将每条消息入队，供当前运行结束后的后续智能体轮次处理。
  • collect：在静默窗口后，将排队消息合并为一个 单一 followup 轮次。如果消息目标是不同渠道/线程，它们会单独清空以保留路由。
  • steer-backlog（也称 steer+backlog）：立即 steer，并且 保留同一条消息用于 followup 轮次。
  • interrupt（旧版）：中止该会话的活跃运行，然后运行最新消息。

Steer-backlog 意味着你可能会在被 steer 的运行之后得到一个 followup 响应，因此
流式传输表面可能看起来像重复。若你希望每条入站消息只产生一个响应，请优先使用 collect/steer。

有关运行时特定的时序和依赖行为，请参见
Steering queue。有关显式 /steer <message>
命令，请参见 Steer。

通过 messages.queue 进行全局配置或按渠道配置：

{
  messages: {
    queue: {
      mode: "steer",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

队列选项

选项适用于 followup、collect 和 steer-backlog（也适用于 steering 回退到 followup 时的 steer 或旧版 queue）：

  • debounceMs：清空排队 followup 之前的静默窗口。裸数字表示毫秒；/queue 选项接受单位 ms、s、m、h 和 d。
  • cap：每个会话的最大排队消息数。小于 1 的值会被忽略。
  • drop: "summarize"：默认值。按需丢弃最旧的队列条目，保留紧凑摘要，并将其作为合成 followup prompt 注入。
  • drop: "old"：按需丢弃最旧的队列条目，不保留摘要。
  • drop: "new"：当队列已满时拒绝最新消息。

默认值：debounceMs: 500、cap: 20、drop: summarize。

优先级

对于模式选择，OpenClaw 按以下顺序解析：

  1. 内联或已存储的每会话 /queue 覆盖项。
  2. messages.queue.byChannel.<channel>。
  3. messages.queue.mode。
  4. 默认 steer。

对于选项，内联或已存储的 /queue 选项优先于配置。然后依次应用
渠道特定 debounce（messages.queue.debounceMsByChannel）、插件
debounce 默认值、全局 messages.queue 选项，以及内置默认值。
cap 和 drop 是全局/会话选项，而不是按渠道配置键。

每会话覆盖项

  • 将 /queue <mode> 作为独立命令发送，以存储当前会话的模式。
  • 选项可以组合：/queue collect debounce:0.5s cap:25 drop:summarize
  • /queue default 或 /queue reset 会清除会话覆盖项。

范围和保证

  • 适用于所有使用 Gateway 网关回复管线的入站渠道上的自动回复智能体运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。
  • 默认 lane（main）对于入站 + 主 Heartbeat 是进程范围的；设置 agents.defaults.maxConcurrent 以允许多个会话并行运行。
  • 可能存在其他 lane（例如 cron、cron-nested、nested、subagent），因此后台作业可以并行运行而不阻塞入站回复。隔离的 cron 智能体轮次会占用一个 cron 槽位，而其内部智能体执行使用 cron-nested；两者都使用 cron.maxConcurrentRuns。共享的非 cron nested 流程会保留自己的 lane 行为。这些分离运行会作为 后台任务 跟踪。
  • 每会话 lane 保证同一时间只有一个智能体运行会触碰给定会话。
  • 没有外部依赖或后台工作线程；纯 TypeScript + Promise。

故障排除

  • 如果命令看起来卡住，请启用详细日志并查找 "queued for ...ms" 行，以确认队列正在清空。
  • 如果你需要队列深度，请启用详细日志并观察队列时序行。
  • Codex app-server 运行在接受一个轮次后如果停止发出进度，会被 Codex adapter 中断，这样活跃会话 lane 就能释放，而不是等待外层运行超时。
  • 启用诊断时，超过 diagnostics.stuckSessionWarnMs 仍处于 processing，且未观察到回复、工具、状态、分块或 ACP 进度的会话，会按当前活动分类。活跃工作会记录为 session.long_running；没有最近进度的活跃工作会记录为 session.stalled；session.stuck 仅保留给没有活跃工作的陈旧会话 bookkeeping，且只有该路径能释放受影响的会话 lane，从而让排队工作继续清空。重复的 session.stuck 诊断会在会话保持不变时退避。

相关内容

📎 原文来源（共 4 篇，按子模块顺序聚合）：

  1. 消息
  2. 流式传输和分块
  3. 重试策略
  4. 命令队列

📂 所属板块：代理 > 消息与投递　|　🤖 翻译模型：volcengine-plan/ark-code-latest

版权声明：
作者：SE_You
链接：https://www.cnesa.cn/11788.html
文章版权归作者所有，未经允许请勿转载。
上一篇 [OpenClaw 文档]代理--多代理
下一篇 [OpenClaw 文档]工具--概览