OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

主流消息传递

Matrix 消息行为

如何OpenClaw将回复传递到Matrix房间：流媒体预览、入站语音注释和反应。

流式预览

Matrix 回复流式传输是可选启用的。streaming.mode 控制 OpenClaw 如何传递进行中的助手回复；streaming.block.enabled 控制每个已完成的块是否作为独立的 Matrix 消息保留。

json5
{  channels: {    matrix: {      streaming: { mode: "partial" },    },  },}

保留实时答案预览但隐藏临时答案tool/progress线路：

json5
{  channels: {    matrix: {      streaming: {        mode: "partial",        preview: {          toolProgress: false,        },      },    },  },}

完整配置接受 { mode, chunkMode, block, preview, progress }：

json5
{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // pick from configured or built-in labels (false to hide)          labels: ["Thinking", "Writing", "Searching"], // candidates for label: "auto"          maxLines: 8, // max rolling progress lines (default: 8)          maxLineChars: 120, // max chars per line before truncation (default: 120)          toolProgress: true, // rolling tool log in the progress draft (default: false)        },      },    },  },}
  • progress.label：自定义标签，"auto"/unset选择一个配置的或内置的标签，或者false隐藏它。
  • progress.labels：仅当 label 为 "auto" 或未设置时使用的候选项。
  • progress.maxLines：草稿中保留的最大滚动进度行数；更早的行会被裁剪。
  • progress.maxLineChars：每条紧凑进度行在截断前的最大字符数。
  • progress.toolProgress：当 true 时，实时 tool/progress 活动（包括工具故障）出现在草稿中。默认的 false 保留草稿的标题、评论、计划里程碑和批准请求。中间工具故障和非零命令退出被隐藏；终端任务错误仍然使用正常的错误传递。
streaming.mode 行为
"off"（默认） 等待完整回复，一次发送。
"partial" 当模型写入当前块时，就地编辑一条普通文本消息。原生客户端可能会在第一次预览时通知，而不是在最终编辑时通知。
"quiet" 与 "partial" 相同，但该消息是非通知通知。一旦每用户推送规则与最终编辑匹配，收件人就会收到通知（请参阅 自托管推送规则以获取安静的最终预览 ）。
"progress" 使用进度草稿发送单独的紧凑进度行。

streaming.block.enabled（默认 false）独立于 streaming.mode：

streaming.mode block.enabled: true block.enabled: false（默认）
"partial" / "quiet" 当前块的实时草稿，已完成的块作为消息保留 当前块的实时草稿，就地最终化
"off" 每个已完成块发送一条会通知的 Matrix 消息 整个回复发送一条会通知的 Matrix 消息

注意：

  • 如果预览超过了 Matrix 的单事件大小限制，OpenClaw 会停止预览流式传输，并回退为仅最终结果的传递。
  • 媒体回复总是正常发送附件。如果可见预览无​​法安全地重复使用，OpenClaw 会保留它，直到确认完全替换，然后对其进行编辑。如果替换传送失败、部分传送或未产生可见事件，则预览仍然可见。
  • 当预览流式传输处于活动状态时，工具进度预览更新默认开启。将 streaming.preview.toolProgress: false 设为仅保留答案文本的预览编辑，而让工具进度走正常传递路径。
  • 预览编辑会额外消耗 Matrix API 调用。若要获得最保守的速率限制配置，请保持 streaming.mode: "off"。
  • 遗产scalar/boolean streaming价值观和平坦blockStreaming / chunkMode键被重写为这个嵌套形状openclaw doctor --fix。

语音消息

传入的 Matrix 语音消息会在房间提及门控之前进行转写，因此，在 requireMention: true 的房间中，一条提到机器人名称的语音消息可以触发代理，而代理接收到的是转写文本，而不是仅仅一个音频附件占位符。

Matrix 使用位于 tools.media.audio 下的共享音频媒体提供商，例如 OpenAI gpt-4o-mini-transcribe。有关提供商设置和限制，请参见媒体工具概览。

  • m.audio事件和m.file事件与audio/* MIME类型均符合资格。
  • 在加密房间中，OpenClaw 会在转写之前通过现有的 Matrix 媒体路径解密附件。
  • 转写文本会在代理提示中被标记为机器生成且不可信。
  • 该附件会被标记为已转写，因此下游媒体工具不会再次对其进行转写。
  • 将 tools.media.audio.enabled: false 设为禁用全局音频转写。

反应

Matrix 支持外发反应、入站反应通知和确认反应。

外发反应工具受 channels.matrix.actions.reactions 控制：

  • react 向某个 Matrix 事件添加反应。
  • reactions 列出某个 Matrix 事件当前的反应摘要。
  • emoji-list 从当前对话的房间包和您的个人包中发现自定义表情符号。
  • emoji="" 移除机器人在该事件上的自身反应。
  • remove: true 仅移除机器人指定的表情反应。

emoji-list从授权的当前房间和im.ponies.user_emotes帐户数据中读取MSC2545 im.ponies.room_emotes包。它最多返回 100 个排序条目，例如 { "name": "party", "identifier": "party", "url": "mxc://example.org/party" }；仅限贴纸的参赛作品被排除在外。将 identifier 传递给 react：它是直接存储为 Matrix 反应的 m.relates_to.key 的纯简码，而不是 mxc:// 媒体 URL。自定义反应渲染取决于 Matrix 客户端，因此为需要图像的客户端或代理单独包含 url。

解析顺序（先定义的值优先）：

设置 顺序
ackReaction 每个帐户 -> 通道 -> messages.ackReaction -> 代理身份表情符号后备
ackReactionScope 每个账户 -> 通道 -> messages.ackReactionScope -> 默认 "group-mentions"
reactionNotifications 每个账户 -> 通道 -> 默认 "own"

reactionNotifications: "own" 会在反应指向机器人发出的 Matrix 消息时，转发新增的 m.reaction 事件；"off" 会禁用反应系统事件。反应移除不会被合成为系统事件——Matrix 会将其表现为 redactions，而不是作为独立的 m.reaction 移除事件。

本页有帮助吗？