跳转至

富输出协议

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

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

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

媒体附件

远程附件必须是公开的 https: URL。http:、回环地址、链路本地、私有主机名和内部主机名会被拒绝作为附件指令;服务器端媒体抓取器会在此基础上应用自身的网络防护。

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

已存储的入站附件也接受来自对话历史的 media://inbound/<id> 引用。在结构化附件字段或独立的 MEDIA: 行中使用该引用。Gateway 会将其解析为已存储的文件,并应用与显式本地路径相同的文件读取和沙箱检查。

在 Control UI 聊天中,相对本地引用会相对于会话的工作目录解析,包括所选项目或工作树。它们使用与绝对路径相同的已认证媒体路由;文件缺失时会显示附件错误,而不是字面的 MEDIA: 行。位于其他执行主机上的文件必须首先作为受管附件交付。

Warning

工具、插件、浏览器输出、消息动作和流式块载荷必须使用结构化附件字段,而不是文本命令。回复载荷使用 mediaUrl / mediaUrls:

{ "text": "Here is your image.", "mediaUrl": "/workspace/image.png" }

对于 message(action=send),单个附件使用 media,多个附件使用 attachments: [{media: ...}]。下面提到的自动模式下模型撰写的文本兼容性不是通用的工具、插件或块流式传输协议。

旧版 MEDIA: 行

在自动可见回复模式下,最终助手回复仍然可以通过独立的纯 MEDIA: 行附加媒体。WebChat 还支持下文描述的已提交评论兼容性路径。解析器只识别修剪后文本以 MEDIA: 开头且位于 Markdown 包装器和围栏或缩进代码块之外的行。最多接受三个前导空格;四个空格或制表符缩进遵循 CommonMark 代码块规则。

有效的自动模式助手输出:

Here is the generated image.

MEDIA:/workspace/image.png

以下内容仍然是普通文本,不会附加媒体:

**MEDIA:/workspace/image.png**
`MEDIA:/workspace/image.png`
Here is your image: MEDIA:/workspace/image.png

当标点符号属于路径或 URL 的一部分时,请用双引号括住旧版引用,例如 MEDIA:"https://example.com/video.mp4?token=ends,"。标点符号仍属于引用的一部分;附件验证仍然适用。

WebChat 评论兼容性

在自动模式下,一旦助手消息提交到记录中,WebChat 还可以从模型撰写的评论(进度消息)中附加媒体,而任务仍在继续。这不是对任意流式增量或流式块载荷的解析。

在 before_message_write 钩子运行之前,运行时会捕获模型撰写的引用。只有捕获集合中仍保留在已提交评论中的引用才有资格进行附件准备;由钩子新插入的引用仍然是普通文本。准备过程绑定到确切提交的消息和当前已准入的运行。捕获的引用确立的是交付意图,而非文件访问权限:文件读取策略、媒体验证、认证服务和实时运行/会话所有权检查仍然适用。

这种兼容性不会取代仅消息工具的交付。当解析后的源回复模式为 message_tool_only(通过 messages.visibleReplies: "message_tool" 配置)时,可见输出必须使用 message(action=send) 及其结构化附件字段,而不是评论或最终文本中的旧版 MEDIA: 行。参见 可见回复配置。

结构化载荷与块流式传输

工具、插件、浏览器输出、消息动作和流式块载荷仍然需要如上所述的结构化附件字段。已提交的 WebChat 评论是独立的兼容性路径,不是这些生产者返回文本的例外。

默认情况下,纯 Markdown 图片语法保持为文本。有意将 Markdown 图片回复映射为媒体附件的频道会在其出站适配器中启用此功能;Telegram 就是这样做的,因此 ![alt](url) 仍然可以成为媒体回复。

当启用块流式传输时,流式块中的媒体必须通过结构化 mediaUrl / mediaUrls 字段携带。如果相同的媒体 URL 同时出现在流式块和最终助手载荷中,OpenClaw 只会交付一次,并从最终载荷中去除重复项。

[embed ...]

[embed ...] 是 Control UI 唯一面向代理的富渲染语法。自闭合示例:

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

规则:

  • [view ...] 对新输出无效。[embed ...] 在 2026.4.11 中取代了它(#64104)。
  • Embed 短代码仅在助手消息界面中渲染。
  • 只有 URL 支持的 embed 才会渲染;使用 ref="..." 或 url="..."。
  • 块形式的行内 HTML embed 短代码不会渲染。
  • Web UI 会从可见文本中移除短代码,并以内联方式渲染 embed。

对于 YouTube 视频,直接提供其 URL;无需 HTML 小部件、下载或重新托管:

[embed url="https://www.youtube.com/watch?v=VIDEO_ID" title="Trailer" /]

Control UI 会渲染缩略图卡片,并在用户按下播放时加载 YouTube 播放器。这个专用卡片不需要 gateway.controlUi.allowExternalEmbedUrls;它不允许在 show_widget 内显示任意外部页面或 YouTube iframe。在严格 embed 模式下,它会提供观看链接来代替。在其他界面中使用常规 YouTube 链接。有关受支持的 URL 和隐私行为,请参见 YouTube 视频。

存储的渲染形状

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

{
  "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
  }
}

present_view 不被识别;存储/渲染的富块始终使用此 canvas 形状。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw