Matrix 展示元数据

OpenClaw 会在出站 Matrix m.room.message 事件的 com.openclaw.presentation 内容键下附加规范化后的 MessagePresentation 元数据。

标准 Matrix 客户端会继续渲染纯文本 body。支持 OpenClaw 的客户端可以读取结构化元数据，并渲染原生 UI，例如按钮、选择器、上下文行和分隔线。

事件内容¶

{
  "msgtype": "m.text",
  "body": "Select model\n\nChoose model:\n- DeepSeek",
  "com.openclaw.presentation": {
    "version": 1,
    "type": "message.presentation",
    "title": "Select model",
    "tone": "info",
    "blocks": [
      {
        "type": "select",
        "placeholder": "Choose model",
        "options": [
          {
            "label": "DeepSeek",
            "value": "/model deepseek/deepseek-chat -s"
          }
        ]
      }
    ]
  }
}

• version 是元数据模式版本；当前版本为 1。type 是稳定的判别字段，始终为 "message.presentation"。Matrix 适配器只发出具有完全匹配此版本和类型的负载；客户端同样应忽略其无法安全解释的未知版本、未知 type 值以及未知块类型。
• title 和 tone（info、success、warning、danger、neutral）是可选提示。
• 按钮和选择器选项可以携带类型化的 action（{ "type": "command", "command": "/..." } 或 { "type": "callback", "value": "..." }），同时保留旧版字符串 value。当两者都存在时，优先使用 action。

回退行为¶

OpenClaw 始终将可读的纯文本回退渲染到 body。结构化元数据是附加的，不得成为基本 Matrix 互操作性的必需条件。

回退渲染规则：

• title、text 和 context 内容渲染为纯文本行。
• 带有 command 操作的按钮渲染为 label: `/command`，以便命令保持可复制。带有 callback 操作或仅有旧版 value 的按钮仅渲染标签，以便不透明的回调值保持私密；禁用按钮始终仅渲染标签。URL 和网页应用按钮渲染为 label: URL。
• 选择器块将占位符（或 Options:）渲染为标题，再加上仅标签的选项行。
• 如果没有内容可渲染，例如仅包含分隔线的展示，body 回退为 ---。

不支持的客户端会继续显示回退文本。支持 OpenClaw 的客户端可以优先使用结构化元数据进行显示，同时保留回退文本用于复制、搜索、通知和辅助功能。

支持的块¶

Matrix 出站适配器声明原生支持：

• buttons
• select
• context
• divider

text 块始终通过回退 body 支持。将所有块视为尽力而为的展示提示；忽略未知字段和块类型，而不是导致整条消息失败。

交互¶

此元数据不会添加 Matrix 回调语义。按钮和选择器值是回退交互负载，通常是斜杠命令或文本命令。希望支持交互的 Matrix 客户端会解析控件值（action.command，然后是 action.value，然后是 value），并将其作为普通消息发送回房间。

例如，值为 /model deepseek/deepseek-chat -s 的按钮可以通过将该值作为加密 Matrix 文本消息发送到同一房间来处理。显式会话标志会阻止根据 模型选择范围 设置更新已配置的默认值。

与审批元数据的关系¶

com.openclaw.presentation 用于通用富消息展示。

审批提示使用专用的 com.openclaw.approval 元数据，因为审批携带安全敏感的状态、决策以及 exec/plugin 详情。如果同一事件上同时存在这两个元数据键，客户端应优先使用专用审批渲染器。

媒体消息¶

当回复包含多个媒体 URL 时，OpenClaw 会为每个媒体 URL 发送一个 Matrix 事件。说明文本和展示元数据仅附加到第一个事件，以便客户端获得一个稳定的结构化负载，而不会出现重复渲染器。当长文本跨事件分块时，也适用相同规则：元数据仅随第一个事件发送。

保持展示元数据紧凑。大型用户可见文本应保留在 body 中，并使用正常的 Matrix 文本分块路径。