Appearance
适用场景：构建可渲染 OpenClaw 富响应的 Matrix 客户端，或调试 com.openclaw.presentation 事件内容。OpenClaw 在出站 Matrix m.room.message 事件中附加标准化 MessagePresentation 元数据，普通客户端继续显示纯文本 body，而 OpenClaw 感知客户端可读取结构化元数据渲染按钮、选择框、上下文行、分割线等原生 UI。关键限制：元数据仅作为最佳努力呈现提示，未知类型/版本/块类型应忽略；交互仅通过回传值（通常是斜杠命令）到房间实现，无回调语义。
OpenClaw Matrix 消息呈现元数据配置与调试
事件内容
元数据存储在 Matrix 事件内容中：
json
{
"msgtype": "m.text",
"body": "Select model\n\n- DeepSeek: /model deepseek/deepseek-chat",
"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"
}
]
}
]
}
}version：Matrix 呈现元数据模式版本。客户端应忽略无法安全解释的未知版本。type：OpenClaw 感知客户端的稳定鉴别器。客户端应忽略未知的type值。blocks：富呈现块数组。每个块有type和对应字段。未知块类型应忽略。
回退行为
OpenClaw 始终在 body 中生成可读的纯文本回退。结构化元数据是附加的，不应要求其用于基本的 Matrix 互操作性。
- 不支持的客户端：继续显示回退文本。
- OpenClaw 感知客户端：可优先使用结构化元数据进行显示，同时在复制、搜索、通知和无障碍场景中保留回退文本。
支持的块类型
Matrix 出站适配器支持以下块：
buttons：按钮组select：选择框（带选项列表）context：上下文行（辅助信息）divider：分割线
客户端应将这些块视为最佳努力呈现提示。未知字段和未知块类型应被忽略，而不是导致整条消息渲染失败。
交互方式
此元数据不添加 Matrix 回调语义。按钮和选择框的值是备用交互负载，通常是斜杠命令或文本命令。想支持交互的 Matrix 客户端可将选中的值以普通消息形式发送回房间。
例如，按钮的值为 /model deepseek/deepseek-chat，客户端通过向同一房间发送加密的 Matrix 文本消息来处理该命令。
与审批元数据的关系
com.openclaw.presentation 用于通用富消息呈现。
审批提示使用专用的 com.openclaw.approval 元数据，因为审批携带安全敏感的状态、决策和执行/插件细节。如果同一事件同时存在两个元数据键，客户端应优先使用专用的审批渲染器。
媒体消息
当回复包含多个媒体 URL 时，OpenClaw 每条媒体 URL 发送一个 Matrix 事件。呈现元数据仅附加到第一个媒体事件，使客户端获得一个稳定的结构化负载，并避免重复渲染器。
保持呈现元数据紧凑。用户可见的大段文本应留在 body 中，使用普通的 Matrix 文本分块路径。
常见问题
com.openclaw.presentation 元数据在 Matrix 事件中不出现怎么办？
确认 OpenClaw 已正确配置 Matrix 出站适配器并启用了富呈现。检查事件内容是否确实包含 com.openclaw.presentation 字段；如果缺失，可能是适配器版本不支持或消息类型不符（仅 m.room.message 且 msgtype 为 m.text 时附加）。
如何让 Matrix 客户端支持按钮点击交互？
客户端需要捕获用户选择的按钮值，然后以普通消息形式将值（如 /model deepseek/deepseek-chat）发送到同一房间。OpenClaw 不提供回调机制，因此客户端需自行实现值回传逻辑。
为什么媒体消息只给第一个媒体事件加呈现元数据？
避免重复渲染。OpenClaw 保证每个媒体 URL 独立事件，只有第一个事件包含结构化元数据，客户端据此渲染一次 UI，其他媒体事件仅包含纯文本回退。