Skip to main content
OpenClaw 聊天客户端会在对话中内联播放助手发送的音频和视频附件。Gateway 会将这些附件置于会话范围的访问控制之后，提供可寻址的字节范围，并可针对已识别但并非所有客户端都能安全支持的格式准备便携式播放版本。 本页面介绍 OpenClaw 客户端中的播放功能。频道投递、入站媒体理解和实时语音对话使用独立的路径；请参阅 图像和媒体支持、 媒体理解和对话模式。

​
客户端支持

​
可移植格式

Gateway 将以下格式归类为浏览器、Apple 播放器和 Android Media3 共享的可移植原生格式集： Linux companion 还可以播放其已安装的 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. 如果无法进行检查或转换、操作失败，或超出限制，路由会回退到原始字节。此时客户端可以显示其无法播放媒体的回退界面，并继续提供下载操作。
转码接受最长 20 分钟的源文件，且绝不会提高正常的音频或视频字节上限。缓存的播放版本固定保留七天，Gateway 会在启动时和每小时执行维护，且独立于 attachments.ttlHours。

​
托管附件与访问

Agent 生成的音频和视频会作为托管媒体工件进行存储。图像
保留其独立的托管图像工件系列。本机客户端通过 artifacts.download 解析
该工件：当工件由字节支持时，该方法会返回内联 base64 字节；当工件由
Gateway 管理时，则会返回一个短期有效的、带票据的 URL。 带票据的字节路由支持：
  • 使用 HTTP 206 Partial Content 进行 Range 请求，以支持定位
  • 使用 ETag 和 If-Range 实现安全的续传行为
  • 使用 HEAD 请求获取相同的内容元数据，且不返回响应正文
不要将带票据的 URL 复制到持久化配置中。客户端需要时，应从经过身份验证的 Gateway 重新获取票据。

​
元数据和限制

聊天附件可能包含 sizeBytes、durationMs、width 和 height。 OpenClaw 也会在可用时使用 ffprobe，为媒体信息和 Control UI 的 ?meta=1 可用性探测补充音频时长以及视频时长/尺寸。 探测为尽力而为：缺少探测结果或探测失败时，会保留字段为空， 而不会拒绝该附件。 Gateway 管理的助手附件使用以下每个文件的上限： 这些是播放/存储上限，不同于单独的媒体理解限制。 有关转录和描述限制，请参阅 图像和媒体支持。

​
故障排除

​
缺少时长或尺寸

检查 Gateway 主机上是否已安装 ffprobe，并且可通过其 PATH 找到：
即使没有元数据，仍然可以播放已经是便携格式的文件。

​
已识别的格式被下载而不是播放

检查 Gateway 主机上的两个媒体工具：
ffprobe 用于识别编解码器和时长；ffmpeg 用于创建便携版本。如果任一步骤无法安全处理源文件，OpenClaw 会提供原始文件，客户端则继续使用其回退/下载路径。

​
播放一直停留在准备状态

首次版本请求是异步的。请稍候片刻后重试。对于非常大的、超过 20 分钟的、无法探测的或不受支持的源文件，系统会继续使用原始字节回退方式，而不会阻塞 Gateway。

​
Linux 报告编解码器错误

请使用 Linux 媒体编解码器 中的软件包和源码构建说明。.deb 依赖所需的 GStreamer 插件软件包；AppImage 搭载了发布版本构建时安装的媒体框架和编解码器。

​
Android 在离线时显示媒体行

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

​
相关内容