本页内容
本页内容
节点和媒体
媒体播放
OpenClaw 聊天客户端会在对话中内联播放助手发送的音频和视频附件。Gateway 会将这些附件置于会话范围的访问控制之后,提供可寻址的字节范围,并可针对已识别但并非所有客户端都能安全支持的格式准备便携式播放版本。
本页面介绍 OpenClaw 客户端中的播放功能。频道投递、入站媒体理解和实时语音对话使用独立的路径;请参阅 图像和媒体支持、 媒体理解和对话模式。
客户端支持
| 客户端 | 播放路径 | 操作员说明 |
|---|---|---|
| Control UI | 主题内联音频卡和本机视频控件 | 音频卡提供 play/pause、搜索、已用时间和总时间、下载、语音注释标记和键盘控制。空格切换播放; Left/Right 寻道五秒。启动一张声卡会暂停前一张声卡。可以通过聊天附件选择器上传视频。 |
| iOS 和 macOS | 音频使用 AVAudioPlayer,视频使用 AVPlayer |
内联媒体会与 Talk 和 Listen 协调,避免两条语音路径相互重叠。对于固定 TLS 的网关,应用会在视频播放前执行有界的身份验证下载,而不是绕过证书固定。 |
| Android | 媒体3 ExoPlayer | 该应用程序通过经过身份验证的网关 HTTP 客户端流式传输视频,请求 Android 音频焦点,并与 Talk/TTS. 协调附件播放。缓存的转录媒体行在离线状态下仍然可见,但播放需要连接才能获取新的媒体票证。 |
| Linux 伴侣 | Control UI 同伴内部 WebView | 编解码器可用性来自 GStreamer。发布的包包含或声明预期的编解码器插件;请参阅 Linux 媒体编解码器。 |
可移植格式
Gateway 将以下格式归类为浏览器、Apple 播放器和 Android Media3 共享的可移植原生格式集:
| 类型 | 可移植原生输入 | 可识别的转码输入 | 播放目标 |
|---|---|---|---|
| 音频 | MP3; AAC in M4A/MP4; PCM WAV | AAC、AIFF、AMR/AMR-WB、CAF、FLAC、Ogg/Opus/Vorbis、WebM 音频、WMA | AAC in M4A (audio/mp4) |
| 视频 | H.264 MP4 具有便携式配置文件和 4:2:0 像素格式; AAC 或 MP3 音频(如果存在) | AVI, FLV, Matroska/MKV, QuickTime/MOV, WebM, ASF, WMV | H.264/AAC MP4 4:2:0像素格式,最大1920×1080 |
Linux companion 还可以播放其已安装的 GStreamer 插件所支持的格式。浏览器和操作系统更新可能会增加原生格式,但上表是 OpenClaw 面向各客户端的通用契约。
延迟播放版本
Gateway 的两个字节路由都接受 ?playback=1:位于 /api/chat/media/outgoing/.../full 下的托管附件路由,以及 Control UI 的助手媒体路由。附件元数据可以报告 playback: "native" 或 playback: "transcode",以便客户端有意选择相应的播放版本。
播放转换采用延迟处理:
- 原生源保持不变直接传递。
- 已识别的非便携源会启动一个受限的
ffmpeg任务。播放版本准备期间,路由返回 HTTP202以及{ "status": "preparing" }。 - 后续请求会收到缓存的 M4A 或 MP4 播放版本。
- 如果无法进行检查或转换、操作失败,或超出限制,路由会回退到原始字节。此时客户端可以显示其无法播放媒体的回退界面,并继续提供下载操作。
Control UI 在加载内联播放器之前使用 HEAD 检查再现准备情况。当转换挂起时,它会显示 正在准备播放,并在播放不可用时保持下载操作可用。
转码接受最长 20 分钟的源文件,且绝不会提高正常的音频或视频字节上限。缓存的播放版本固定保留七天,Gateway 会在启动时和每小时执行维护,且独立于 attachments.ttlHours。
托管附件与访问
要在助理回复中附加本地文件,请将 MEDIA:/absolute/path/movie.mp4 放在自己的行上。会话的现有媒体访问策略必须允许该路径。 Control UI 阶段允许具有有限流的本地音频和视频,并通过网关的经过身份验证的可搜索媒体路由播放它们。使用应用程序或开发服务器的门户;对文件使用 MEDIA:<path>。
远程 MEDIA: 引用必须是没有凭据的公共 HTTPS URL。被拒绝的引用会产生可见的附件失败,并附有使用允许的 URL 或本地路径的说明;它们不显示为原始指令链接。提及 MEDIA: 的内联散文和围栏代码示例仍为文本。
Agent 生成的音频和视频会作为托管媒体工件进行存储。图像保留其独立的托管图像工件系列。本机客户端通过 artifacts.download 解析该工件:当工件由字节支持时,该方法会返回内联 base64 字节;当工件由 Gateway 管理时,则会返回一个短期有效的、带票据的 URL。
托管下载票证检查当前会话访问权限以及可见历史记录中所选消息的附件引用。对于索引消息,发出票证不会读取原始文件或验证不相关的转录有效负载。 HTTP请求单独传输文件。
托管媒体清理读取有界页面中的转录历史记录。如果单条消息超过 8 MiB 页面限制,清理将保留该会话的媒体并记录警告,同时继续清理其他会话。不完整的历史记录永远不会被视为附件未被引用的证据。
下载文件名保留 Unicode 字符和文字百分比序列,例如 %20。
本机客户端根据连接的网关 URL 解析票据媒体,保留其反向代理路径前缀。到达 wss://gateway.example/openclaw 的网关将加载 https://gateway.example/openclaw/api/chat/media/outgoing/ 下的托管媒体,而不是服务器根目录。
带票据的字节路由支持:
Range请求 HTTP206 Partial Content进行查找ETag和If-Range用于安全恢复不可变的托管原始文件- 使用
HEAD请求获取相同的内容元数据,且不返回响应正文
对于不可变的原件,If-None-Match 使用弱比较来比较完整的引用标签。带引号的标签内的逗号和星号是字面意思;只有独立的 * 才是通配符。不匹配的标签会使正常的完整或范围响应保持不变。
本地助手文件可能会发生变化,并且重试转换后播放再现可能会变得可用。这些响应在没有可重用验证器的情况下重新验证:缓存的 ETag 或修改日期无法抑制新字节,并且 If-Range 请求接收完整表示。普通Range请求仍然支持寻道。托管播放响应对客户端缓存保持私有。
不要将带票据的 URL 复制到持久化配置中。客户端需要时,应从经过身份验证的 Gateway 重新获取票据。
元数据和限制
聊天附件可能包括 sizeBytes、durationMs、width 和 height。 OpenClaw 还使用 ffprobe(如果可用)来填充音频持续时间和视频 duration/dimensions 以获取媒体事实以及 Control UI ?meta=1 可用性检查。视频尺寸考虑了非方形像素和四分之一圈显示旋转;图像尺寸占 EXIF 方向。检查是尽力而为:丢失或失败的检查会使字段不存在,而不是拒绝附件。网关共享同一本地文件的并发元数据检查,并在该文件未更改时重用成功的结果。替换或编辑文件会触发新的检查;失败的检查仍然可以重试。不同的文件在有界检查队列中等待。如果队列已满,元数据会报告暂时不可用,您可以重试,并且播放仍处于准备状态。断开连接的请求停止等待,并且没有剩余查看者的排队检查立即释放其队列槽。排队读取在打开和检查文件之前重新检查当前访问。忙碌的检查员不会丢弃传出的附件;他们的可选播放元数据可以保持不存在。传出回复创建使用立即检查准入,并且不会等待排队的查看器请求。
Control UI 托管助理附件使用以下每个文件上限:
| 类型 | 最大大小 |
|---|---|
| 图像 | 12 MiB |
| 本地音频 | 4 GiB |
| 本地视频 | 4 GiB |
这些是 playback/storage 上限,而不是单独的媒体理解限制。较大的本地文件限制不会更改通道出站限制、远程或数据 URL 摄取限制或基于缓冲区的远程工作区读取器的限制。它也不会增加转码预算;原生MP4大文件无需转换即可直接播放。有关转录和描述限制,请参阅 图像和媒体支持。
故障排查
缺少时长或尺寸
检查 Gateway 主机上是否已安装 ffprobe,并且可通过其 PATH 找到:
即使没有元数据,仍然可以播放已经是便携格式的文件。
已识别的格式被下载而不是播放
检查 Gateway 主机上的两个媒体工具:
ffprobe 对编解码器和持续时间进行分类; ffmpeg 创建便携式演绎版。如果任一步骤都无法安全地处理源,则 OpenClaw 提供原始文件,并且客户端保留其 fallback/download 路径。
播放一直停留在准备状态
首次版本请求是异步的。请稍候片刻后重试。对于非常大的、超过 20 分钟的、无法探测的或不受支持的源文件,系统会继续使用原始字节回退方式,而不会阻塞 Gateway。
Linux 报告编解码器错误
请使用 Linux 媒体编解码器 中的软件包和源码构建说明。.deb 依赖所需的 GStreamer 插件软件包;AppImage 搭载了发布版本构建时安装的媒体框架和编解码器。
Android 在离线时显示媒体行
这是预期行为。Android 会缓存转录元数据,而不会缓存附件字节或其短期下载能力。重新连接,然后再次播放,以便应用请求新的票据。