跳转至

消息

入站消息会依次经过路由、去重/防抖、Agent 运行和出站投递:

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

关键配置面:

  • messages.* 用于前缀、排队、入站防抖和群组行为。
  • agents.defaults.* 用于分块流式输出、分块和静默回复默认值。
  • 渠道覆盖(channels.telegram.*、channels.whatsapp.* 等)用于各渠道上限和流式输出开关。

完整 schema 参见 Configuration。

入站消息去重

渠道在重连后可能重新投递同一条消息。OpenClaw 维护一个内存缓存,键为 Agent 作用域、渠道路由(渠道 + 对端 + 账号 + 线程)和消息 ID,因此重新投递的消息不会触发第二次 Agent 运行。缓存条目在 20 分钟后过期,或跟踪条目达到 5000 条时过期,以先到者为准。

入站消息防抖

来自同一发送者的快速连续文本消息可以通过 messages.inbound 合并为一次 Agent 轮次。防抖按“渠道 + 会话”范围进行,并使用最新消息作为回复线程/ID。这是一种静默窗口启发式策略,并不保证长消息的每个部分都会在一次轮次中到达。

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        discord: 1500,
        slack: 1500,
        whatsapp: 5000,
      },
    },
  },
}
  • 防抖仅适用于纯文本消息;媒体/附件会立即刷新。
  • 控制命令(stop/abort/status 等)绕过防抖,立即派发。
  • Telegram 默认在 300ms 静默窗口后对普通文本进行批处理。其他渠道除非另行配置,否则没有通用防抖延迟。
  • messages.inbound.byChannel.<channel> 优先于 messages.inbound.debounceMs;两者都可覆盖渠道默认值。设置为 0 可禁用普通突发消息批处理。
  • 对于非转发的 Telegram 文本,长度至少为 4000 字符的消息允许最多 1500ms 等待后续内容。短消息和长消息共享同一批次,不要求连续的消息 ID。这种自动的长粘贴拼接在普通批处理被禁用时仍然生效。
  • iMessage 遵循相同的通用防抖策略。imsg 0.13.1 及更新版本会在 OpenClaw 接收之前合并 Apple URL 预览的拆分发送,因此无需为 iMessage 单独设置防抖参数。

对 messages.inbound.debounceMs 和 messages.inbound.byChannel 的更改无需重连 Discord、Feishu、iMessage、Mattermost、Microsoft Teams、Signal、Slack、Telegram 或 WhatsApp 即可生效。新接收的入站工作使用已提交的延迟。仅更改配置不会重新调度待处理的批次;后续消息可以在原始最大截止时间内更新其空闲延迟。显式的传输层时间覆盖保持固定。Telegram 的转发消息收集窗口仍然独立。

会话与设备

会话由网关拥有,而非客户端拥有。

  • 私聊会合并到 Agent 的主会话键中。
  • 群组/频道拥有各自的会话键。
  • 会话存储和转录记录位于网关主机上。

多个设备/渠道可以映射到同一会话,但历史记录不会完整同步回每个客户端。对于长对话,请使用一个主要设备,以免上下文出现分歧。Control UI 和 TUI 始终显示网关支持的会话转录,因此它们是事实来源。

如果某次运行在助手回复保存之前失败或超时,其转录记录会收到一条可见的失败通知。嵌套运行即使在其请求轮次结束后,仍会保留各自的失败通知。

详情:会话管理。

提示词正文与历史上下文

渠道插件会在入站上下文上填充多个文本字段,按优先级从高到低排列:

字段 用途
BodyForAgent 面向模型的当前轮次文本。未设置时回退到 CommandBody / RawBody / Body。
BodyForCommands 用于指令/命令解析的干净文本。未设置时回退到 CommandBody / RawBody / Body。
CommandBody 旧版中间正文;优先使用 BodyForCommands。
RawBody CommandBody 的已弃用别名。
Body 旧版提示词正文;可能包含渠道信封和历史包装器。

当渠道提供历史记录时,它会用以下内容包装历史:

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

对于非私聊(群组/频道/房间),当前消息正文会加上发送者标签前缀,样式与历史条目一致。指令剥离仅适用于当前消息部分,因此历史记录保持完整。包装历史的渠道应将 BodyForCommands(或旧版的 CommandBody / RawBody)设置为原始消息文本,并将 Body 保留为组合提示词。

历史缓冲区仅包含待处理内容:它们包括未触发运行(例如受提及限制的消息)的群组消息,并排除已在会话转录中的消息。结构化历史、回复、转发和渠道元数据会在提示词组装期间渲染为不可信的用户角色上下文块。

使用 messages.groupChat.historyLimit(全局默认值)或各渠道覆盖项(如 channels.slack.historyLimit 和 channels.telegram.accounts.<id>.historyLimit)配置历史记录大小(设置为 0 可禁用)。

工具结果元数据

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

  • toolResult.details 在提供商重放之前以及压缩输入之前会被移除。
  • 持久化的会话转录仅保留有界的 details;超大的元数据会被替换为带有 persistedDetailsTruncated: true 标记的紧凑摘要。
  • 显示历史会保留工具状态标志和会话键,并在工具提供时保留命令退出码、持续时间以及有界的工作目录。
  • 插件和工具应将模型必须读取的文本放在 content 中,而不仅仅放在 details 中。

当工具错误警告是代理的唯一回复时,WebChat 会显示并保留它。该警告本身不会将已完成的代理运行变为运行时失败;失败的工具结果仍会单独记录。

排队与后续消息

当已有运行处于活动状态时,传入消息默认会引导进入该运行。messages.queue 控制模式:

模式 行为
steer(默认) 将新提示注入到活动运行中。
followup 在活动运行完成后运行该消息。
collect 将兼容的消息批量合并为一个后续轮次。
interrupt 中止活动运行,然后启动最新的提示。

具有独立持久入口准入的消息(包括 Discord 和 Telegram 消息)即使在 collect 模式下也会保持在单独的后续轮次中。兼容的 Gateway chat.send 输入仍可以合并。

队列对 steer、followup 和 collect 批处理使用内置的 500ms 防抖。messages.queue.cap 默认为 20 条排队消息,messages.queue.drop 默认为 summarize(也可用 old 和 new)。通过 messages.queue.byChannel 和 messages.queue.debounceMsByChannel 配置按通道覆盖。

详情:命令队列 和 引导队列。

通道运行所有权

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

一旦轮次被持久接受,在其回答之前发生意外失败时,会在直接聊天以及启用了自动回复的显式指定对话中生成一条紧凑的错误回复。进度确认不会替代该最终结果。该轮次仍保持失败状态,并且不会作为新的传入消息重放;投递策略以及已通过 message 工具发送的回复仍然适用。

在 OpenClaw 运行时中,如果助手轮次在生成部分文本后发生错误或中止,且没有工具调用,则会在下一个模型请求中显示为一个简短的失败标记。其未完成的文本不会被重放,存储的失败轮次保持不变。空失败和仅占位符失败仍被排除;失败的工具调用保留其现有配对规则。该标记不会确定先前操作是否已完成。

流式传输、分块与批处理

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

  • 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(块回复之间类似人类的暂停)
  • 通道覆盖:捆绑通道上的 *.streaming.block.enabled 和 *.streaming.block.coalesce;过时的扁平键由 openclaw doctor --fix 迁移。除非明确启用,否则块流式传输在所有通道上均关闭,包括 Telegram。QQ Bot 是例外:它没有 streaming.block 键,并且会流式传输块回复,除非 channels.qqbot.streaming.mode 为 "off"。

详情:流式传输 + 分块。

推理可见性与 Token

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

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

前缀、线程与回复

  • 支持回复前缀的通道使用 channels.<channel>.responsePrefix;当支持多账户配置时,使用 channels.<channel>.accounts.<id>.responsePrefix。账户值优先,包括使用 "" 禁用继承的前缀。使用 "auto" 表示代理身份名称,或使用 "[{model}]" 等模板表示所选模型。自动回复支持因通道而异。当这些规范字段未设置时,Doctor 会将全局回退值复制到受支持的已配置通道块中;messages.responsePrefix 仍作为隐式和自定义通道的回退值。
  • 显式 message 工具和 CLI 文本发送也会应用解析后的前缀,而不会重复已存在的前缀。它们会解析身份占位符,但不会选择模型;包含未解析的模型、提供商或思考级别占位符的前缀会被完全省略。
  • 通过 replyToMode 和按通道默认值进行回复线程化。

详情:配置 和通道文档。

静默回复

静默令牌 NO_REPLY(不区分大小写,因此 no_reply 也会匹配)专用于连接到外部消息通道的会话,并且永远不会作为用户可见文本投递。子代理、Control UI 和其他内部会话必须返回结果或继续未完成的工作;静默令牌无法完成它们的任务。当轮次还具有待处理工具媒体(例如生成的 TTS 音频)时,OpenClaw 会移除静默文本,但仍会投递媒体附件。

静默策略按会话类型解析:

  • 直接会话永远不会收到 NO_REPLY prompt 指导。未送达的必需回复仍需恢复;该 token 不能免除这一义务。
  • 已接受的群组/频道请求默认需要回复,包括以 requireMention: false 准入的未提及消息。提及和访问门控仍决定哪些消息到达 agent。要允许未指向的请求静默结束,请在以下配置范围之一中显式设置 silentReply.group: "allow";提及和授权命令仍需要响应。
  • 环境房间事件 可以保持静默。在 message_tool 可见回复模式下,可选回合通过不调用 message(action=send) 保持静默。私有 subagent 的完成会在内部记录父级的已审核结果;它们不需要静默 token 来保持该结果私有。

默认值位于 agents.defaults.silentReply.group;surfaces.<id>.silentReply.group 可按 surface 覆盖群组策略。Doctor 在配置迁移期间移除已弃用的 internal 设置。

通用内部 runner 失败对于尚未显示可见输出的可选回合保持静默,包括显式配置为允许静默的群组。必需回合仍会收到错误。已分类的恢复指导,例如 missing-auth、rate-limit 或 overload 通知,仍可送达,并且可见进度会收到失败结果,而不是被留作未完成。直接聊天默认显示紧凑的失败文案;只有启用 /verbose full 时才会显示原始 runner 详情。

回复要求来自准入,而不是模型控制 token。已确认送达或仍由当前方持有的送达可防止重复恢复;参见 回复整形。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw