媒体播放

OpenClaw 聊天客户端会内联播放助手的音频和视频附件。Gateway 会将这些附件置于会话范围访问之后，提供可定位字节范围，并可以为并非在所有客户端都安全的已识别格式准备可移植播放版本。

本页介绍 OpenClaw 客户端中的播放。频道投递、入站媒体理解和实时语音对话使用独立路径；参见 图像和媒体支持、媒体理解 和 Talk 模式。

客户端支持¶

可移植格式¶

Gateway 将这些格式归类为浏览器、Apple 播放器和 Android Media3 共享的可移植原生集合：

Linux 伴侣应用还可以播放其已安装 GStreamer 插件提供的格式。浏览器和操作系统更新可能会添加原生格式，但上表是 OpenClaw 面向跨客户端约定的目标。

延迟播放版本¶

两个 Gateway 字节路由都接受 ?playback=1：位于 /api/chat/media/outgoing/.../full 下的托管附件路由以及 Control UI 助手媒体路由。附件元数据可以报告 playback: "native" 或 playback: "transcode"，以便客户端有意选择播放版本。

播放转换是延迟的：

1. 原生源原样通过。
2. 受识别的非可移植源会启动一个有界 ffmpeg 任务。在准备播放版本期间，路由返回 HTTP 202 和 { "status": "preparing" }。
3. 后续请求会收到缓存的 M4A 或 MP4 播放版本。
4. 如果检查或转换不可用、失败或超出限制，路由会回退到原始字节。然后客户端可以显示其不可播放媒体回退，并保持下载操作可用。

Control UI 在加载内联播放器之前使用 HEAD 检查播放版本就绪状态。转换待处理时，它显示 Preparing playback，并在播放不可用时保持下载操作可用。

转码接受最长 20 分钟的源，并且从不提高常规音频或视频字节上限。缓存的播放版本使用固定的七天保留期，Gateway 维护会在启动时和每小时强制执行，独立于 attachments.ttlHours。

托管附件与访问¶

代理生成的音频和视频作为托管媒体工件存储。图像保留其独立的托管图像工件族。原生客户端通过 artifacts.download 解析工件；当工件由字节支持时，返回内联 base64 字节；当它由 Gateway 管理时，返回短期票据化 URL。

下载文件名保留 Unicode 字符和字面百分号序列，例如 %20。

原生客户端针对已连接的 Gateway URL 解析票据化媒体，并保留其反向代理路径前缀。通过 wss://gateway.example/openclaw 访问的 Gateway 会在 https://gateway.example/openclaw/api/chat/media/outgoing/ 下加载托管媒体，而不是服务器根目录。

带票据的字节路由支持：

• Range 请求，使用 HTTP 206 Partial Content 进行定位
• ETag 和 If-Range，用于安全恢复不可变托管原始文件
• HEAD 请求，具有相同的内容元数据且无响应体

对于不可变原始文件，If-None-Match 使用弱比较来比较完整的带引号标签。带引号标签内的逗号和星号是字面量；只有独立的 * 是通配符。不匹配的标签会保留正常的完整或范围响应。

本地助手文件可能会变化，播放渲染版本也可能在转换重试后变得可用。这些响应在没有可复用验证器的情况下重新验证：缓存的 ETag 或修改日期无法抑制新鲜字节，并且 If-Range 请求会收到完整表示。普通 Range 请求仍支持定位。托管播放响应保持为客户端缓存私有。

不要将带票据的 URL 复制到持久配置中。客户端在需要时从已认证的 Gateway 重新获取票据。

元数据与限制¶

聊天附件可能包含 sizeBytes、durationMs、width 和 height。 OpenClaw 还会在可用时使用 ffprobe 来填充媒体事实和 Control UI ?meta=1 可用性探测中的音频时长以及视频时长/尺寸。视频尺寸会考虑非方形像素和四分之一圈显示旋转；图像尺寸会考虑 EXIF 方向。探测是尽力而为的：缺失或失败的探测会使字段缺失，而不是拒绝附件。 Gateway 会为同一本地文件共享并发元数据检查，并在该文件未变化时复用成功结果。替换或编辑文件会触发新的检查；失败的探测仍可重试。 不同文件会在有界检查队列中等待。如果队列已满，元数据会报告可重试的临时不可用，并且播放保持准备状态。断开连接的请求停止等待，没有剩余查看者的排队探测会立即释放其队列槽位。排队读取在打开和探测文件之前会重新检查当前访问权限。繁忙的检查器不会丢弃出站附件；其可选播放元数据可以保持缺失。出站回复创建使用立即检查准入，不会排在排队查看者请求之后等待。

Gateway 托管的助手附件使用以下每文件上限：

这些是播放/存储上限，而不是单独的媒体理解限制。 有关转录和描述限制，请参阅 图像和媒体支持。

故障排查¶

时长或尺寸缺失¶

检查 ffprobe 是否已安装在 Gateway 主机上，并且在其 PATH 中可见：

ffprobe -version

即使没有元数据，已可移植文件的播放仍可能正常工作。

已识别格式下载而非播放¶

检查 Gateway 主机上的两个媒体工具：

ffmpeg -version
ffprobe -version

ffprobe 对编解码器和时长进行分类；ffmpeg 创建可移植渲染版本。如果任一步骤无法安全处理源，OpenClaw 会提供原始文件，客户端保留其回退/下载路径。

播放停留在准备状态¶

第一个渲染版本请求是异步的。稍等片刻并重试。非常大的、长于 20 分钟的、无法探测的或不受支持的源会保留在原始字节回退上，而不是阻塞 Gateway。

Linux 报告编解码器错误¶

使用 Linux 媒体编解码器 中的软件包和源码构建说明。.deb 依赖于所需的 GStreamer 插件软件包；AppImage 携带由发布构建安装的媒体框架和编解码器。

Android 离线时显示媒体行¶

这是预期行为。Android 缓存转录元数据，而不是附件字节或其短生命周期的下载能力。重新连接，然后再次播放，以便应用可以请求新票据。

相关¶

• 图像和媒体支持
• 音频和语音留言
• 媒体概览
• 文本转语音
• Linux 应用