# 富输出协议

> 用于结构化媒体、嵌入内容、音频提示和回复的富输出协议

- 网址：https://funcoding.ai/agents/openclaw/reference/rich-output-protocol/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/reference/rich-output-protocol

---
助手输出通过几个专用渠道携带交付/渲染指令：

- 用于附件交付的结构化 `mediaUrl` / `mediaUrls` 字段。
- `[[audio_as_voice]]` 用于音频呈现提示。
- `[[reply_to_current]]` / `[[reply_to:<id>]]` 用于回复元数据。
- `[embed ...]` 用于 Control UI 富渲染。

结构化媒体字段和 `[[...]]` 标签是交付元数据。`[embed ...]` 是单独的仅限 Web 的富渲染路径；它不是媒体别名。

## 媒体附件

远程附件必须是公开的 `https:` URL。`http:`、loopback、链路本地、私有和内部主机名会被拒绝作为附件指令；除此之外，服务端媒体获取器还会应用自身的网络防护措施。

本地附件接受绝对路径、工作区相对路径或主目录相对的 `~/` 路径。交付前，它们仍需通过智能体文件读取策略和媒体类型检查。

<div class="callout callout-warning">

不要从工具、插件、流式传输块、浏览器输出或消息操作中发出附件文本命令。请改用结构化媒体字段：

```json
{ "message": "这是你的图片。", "mediaUrl": "/workspace/image.png" }
```

为保持兼容性，旧版最终回复文本仍可进行规范化，但这不是通用的插件/工具协议。

</div>

默认情况下，纯 Markdown 图片语法（`![alt](url)`）仍作为文本处理。若渠道希望将 Markdown 图片视为媒体回复，可在其出站适配器中选择启用；Telegram 已启用此行为，因此 `![alt](url)` 会成为媒体附件。

启用分块流式传输后，媒体必须通过结构化载荷字段传递。如果同一媒体 URL 既出现在流式传输块中，又再次出现在最终助手载荷中，OpenClaw 只会交付一次，并从最终载荷中移除重复项。

## `[embed ...]`

`[embed ...]` 是 Control UI 唯一面向智能体的富渲染语法。自闭合示例：

```text
[embed ref="cv_123" title="Status" /]
```

规则：

- `[view ...]` 不再适用于新输出。
- 嵌入短代码仅在助手消息界面中渲染。
- 仅渲染由 URL 支持的嵌入；请使用 `ref="..."` 或 `url="..."`。
- 块形式的内联 HTML 嵌入短代码不会渲染。
- Web UI 会从可见文本中移除短代码，并以内联方式渲染嵌入内容。

## 存储的渲染结构

规范化/存储后的助手内容块是一个结构化的 `canvas` 项：

```json
{
  "type": "canvas",
  "preview": {
    "kind": "canvas",
    "surface": "assistant_message",
    "render": "url",
    "viewId": "cv_123",
    "url": "/__openclaw__/canvas/documents/cv_123/index.html",
    "title": "状态",
    "preferredHeight": 320
  }
}
```

无法识别 `present_view`；存储/渲染的富内容块始终使用此 `canvas` 结构。

## 相关内容

- [RPC 适配器](https://funcoding.ai/agents/openclaw/reference/rpc/)
- [Typebox](https://funcoding.ai/agents/openclaw/concepts/typebox/)