图标样例 原始文档

Reference 导读

让助手输出带上富媒体：`[embed]` 是唯一入口

这一页定义了助手输出中携带富媒体指令的协议。最核心的是 `[embed ...]` 短代码，它能在 Control UI 中嵌入可渲染的卡片或视图，而 `MEDIA:` 只负责附件投递，不要混用。注意 `[view ...]` 已废弃，新输出必须用 `[embed]`，且只有 URL 形式的嵌入才会被渲染。

先讲这一页到底在解决什么

让助手输出带上富媒体：`[embed]` 是唯一入口

这一页定义了助手输出中携带富媒体指令的协议。最核心的是 `[embed ...]` 短代码，它能在 Control UI 中嵌入可渲染的卡片或视图，而 `MEDIA:` 只负责附件投递，不要混用。注意 `[view ...]` 已废弃，新输出必须用 `[embed]`，且只有 URL 形式的嵌入才会被渲染。

原文共 4 节，先看 Start Here 路径：/reference/rich-output-protocol 查看官方原文

第一站

🏷️ 先把四类标签分清

它们都写在助手输出附近，但作用完全不同。分清以后，这页就很短。

📎

MEDIA:

用于附件投递，像告诉客户端“这里有文件要送”。

🔊

[[audio_as_voice]]

用于音频展示提示，像说“这段音频请按语音消息处理”。

↩️

[[reply_to_current]]

用于回复元数据，像在信封上写“回上一条”。

🖼️

[embed ...]

用于 Control UI 的网页 rich rendering，是这页唯一的 agent-facing rich render 语法。

第二站

🧱 [embed ...] 只负责网页内嵌渲染

如果你想在 Control UI 的 assistant message surface 里显示一个 URL-backed embed，就用这个短码。

自闭合写法
[embed ref="cv_123" title="Status" /]
[view ...] 不再是新写法

新输出不要再用 [view ...]。

只渲染 URL-backed embed

使用 ref="..." 或 url="..."，让前端能找到真正要打开的页面。

短码会从可见文字里拿掉

Web UI 会剥掉短码本身，在消息里原地渲染 embed。

别混用

MEDIA: 不是 embed alias。要递附件用 MEDIA:，要网页内嵌显示用 [embed ...]。

第三站

🗂 存起来以后，它会变成 canvas 结构

前端最终认的不是一句短码，而是标准化后的结构化内容块。

Stored rendering shape
{
  "type": "canvas",
  "preview": {
    "kind": "canvas",
    "surface": "assistant_message",
    "render": "url",
    "viewId": "cv_123",
    "url": "/__openclaw__/canvas/documents/cv_123/index.html",
    "title": "Status",
    "preferredHeight": 320
  }
}
surface

说明这块内容放在 assistant message 里。

render: "url"

说明它通过 URL 加载和渲染。

viewId 和 url

一个像编号，一个像地址，前端靠它们找到要显示的内容。

别写旧形状

present_view 不被识别。存储和渲染请走 canvas shape。

最后总结

🎈 把 Rich Output Protocol 压成一句话

富输出指令要分工明确：附件、语音和回复标签管投递元数据；Control UI 的内嵌网页展示只用 [embed ...]，最终存成 canvas 内容块。