消息

OpenClaw 如何将回复发送到 Matrix 房间：流式预览、传入语音消息和表情回应。

流式预览¶

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

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

如需保留实时答案预览，但隐藏中间工具/进度行：

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

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

{
  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"/未设置时会选择一个已配置或内置标签；false 表示隐藏。
• progress.labels：仅在 label 为 "auto" 或未设置时使用的候选标签。
• progress.maxLines：草稿中保留的最大滚动进度行数；超出此数量的较旧行会被裁剪。
• progress.maxLineChars：每条紧凑进度行截断前的最大字符数。
• progress.toolProgress：当为 true 时，实时工具/进度活动（包括工具失败）会显示在草稿中。默认 false 使草稿仅保留标题、评论、计划里程碑和审批请求。中间工具失败和非零命令退出会被隐藏；终端任务错误仍使用正常错误发送。

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

说明：

• 如果预览超过 Matrix 的单事件大小限制，OpenClaw 将停止预览流式传输，并回退为仅发送最终回复。
• 媒体回复始终正常发送附件。如果可见预览无法安全复用，OpenClaw 会保留它，直到确认完整替换后再将其撤回。如果替换发送失败、不完整或未产生可见事件，预览将保持可见。
• 当预览流式传输处于活动状态时，工具进度预览更新默认开启。设置 streaming.preview.toolProgress: false 可让预览编辑仅用于答案文本，而将工具进度保留在正常发送路径上。
• 预览编辑会产生额外的 Matrix API 调用。如需最保守的速率限制配置，请保持 streaming.mode: "off"。
• 旧版标量/布尔 streaming 值以及扁平的 blockStreaming / chunkMode 键会通过 openclaw doctor --fix 重写为此嵌套结构。

语音消息¶

传入的 Matrix 语音消息会在房间提及门控之前进行转录，因此一条说出机器人名称的语音消息可以在 requireMention: true 房间中触发智能体，并且智能体获得转录文本，而不仅仅是音频附件占位符。

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

• m.audio 事件以及 MIME 类型为 audio/* 的 m.file 事件符合条件。
• 在加密房间中，OpenClaw 会在转录前通过现有 Matrix 媒体路径解密附件。
• 转录文本会在智能体提示中标记为机器生成且不可信。
• 附件会被标记为已转录，以便下游媒体工具不会再次转录它。
• 设置 tools.media.audio.enabled: false 可全局禁用音频转录。

反应¶

Matrix 支持出站反应、入站反应通知和 ack 反应。

出站反应工具由 channels.matrix.actions.reactions 控制：

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

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

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

reactionNotifications: "own" 会在新增的 m.reaction 事件指向机器人创建的 Matrix 消息时转发这些事件；"off" 禁用反应系统事件。反应移除不会被合成为系统事件 - Matrix 将其呈现为撤回，而不是独立的 m.reaction 移除。