跳转至

富输出协议

助手输出通过几个专用通道携带投递/渲染指令：

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

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

媒体附件

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

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

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

在 Control UI 聊天中，相对本地引用会相对于会话的工作目录解析，包括选定的项目或 worktree。它们使用与绝对路径相同的经过身份验证的媒体路由；缺失文件会显示附件错误，而不是字面 MEDIA: 行。位于另一个执行主机上的文件必须先作为受管附件投递。

Warning

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

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

对于 message(action=send)，单个附件使用 media，多个附件使用 attachments: [{media: ...}]。下面描述的自动模式模型生成文本兼容性不是一般的工具、插件或块流式传输协议。

旧版 MEDIA: 行

在自动可见回复模式下，最终助手回复仍可使用一个普通的独立 MEDIA: 行附加媒体。WebChat 还支持下面描述的已提交评论兼容性路径。解析器只识别在 Markdown 包装之外以及围栏或缩进代码块之外、修剪后文本以 MEDIA: 开头的行。最多接受三个前导空格；四个空格或制表符缩进遵循 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）。
  • 嵌入短代码仅在助手消息表面渲染。
  • 仅 URL 支持的嵌入会渲染；使用 ref="..." 或 url="..."。
  • 块形式的内联 HTML 嵌入短代码不会渲染。
  • Web UI 会从可见文本中移除短代码，并内联渲染嵌入。

存储的渲染形状

归一化/存储的助手内容块是一个结构化 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