> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 媒体播放

OpenClaw 聊天客户端会在对话中内联播放助手发送的音频和视频附件。Gateway
会将这些附件置于会话范围的访问控制之后，提供可寻址的字节范围，并可针对已识别但并非所有客户端都能安全支持的格式准备便携式播放版本。

本页面介绍 OpenClaw 客户端中的播放功能。频道投递、入站媒体理解和实时语音对话使用独立的路径；请参阅
[图像和媒体支持](/nodes/images)、
[媒体理解](/nodes/media-understanding)和[对话模式](/nodes/talk)。

## 客户端支持

| 客户端         | 播放路径                                 | 操作员说明                                                                                                  |
| ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| 控制界面        | 主题化内联音频卡片和原生视频控件                     | 音频卡片提供播放/暂停、定位、已播放和总时长、下载、语音留言标记以及键盘控制。空格键切换播放状态；左/右键向前或向后定位五秒。开始播放一个音频卡片时，之前正在播放的音频会暂停。可从聊天附件选择器上传视频。 |
| iOS 和 macOS | 音频使用 `AVAudioPlayer`，视频使用 `AVPlayer` | 内联媒体会与 Talk 和 Listen 协调，避免两条语音路径相互重叠。对于固定 TLS 的网关，应用会在视频播放前执行有界的身份验证下载，而不是绕过证书固定。                      |
| Android     | Media3 ExoPlayer                     | 应用通过经过身份验证的网关 HTTP 客户端传输视频，请求 Android 音频焦点，并协调附件播放与 Talk/TTS。缓存的转录媒体行在离线时仍保持可见，但播放需要连接以获取新的媒体票据。       |
| Linux 伴侣应用  | 伴侣 WebView 内的控制界面                    | 编解码器可用性来自 GStreamer。发布的软件包会包含或声明预期的编解码器插件；请参阅 [Linux 媒体编解码器](/platforms/linux#media-codecs)。           |

## 可移植格式

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

| 类型 | 可移植原生输入                                             | 可识别的转码输入                                                 | 播放目标                                      |
| -- | --------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------- |
| 音频 | MP3；M4A/MP4 中的 AAC；PCM WAV                          | AAC、AIFF、AMR/AMR-WB、CAF、FLAC、Ogg/Opus/Vorbis、WebM 音频、WMA | M4A 中的 AAC（`audio/mp4`）                   |
| 视频 | 采用可移植配置和 4:2:0 像素格式的 H.264 MP4；存在音频时使用 AAC 或 MP3 音频 | AVI、FLV、Matroska/MKV、QuickTime/MOV、WebM、ASF、WMV          | 采用 4:2:0 像素格式的 H.264/AAC MP4，最高 1920×1080 |

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 管理的助手附件使用以下每个文件的上限：

| 类型 |   最大大小 |
| -- | -----: |
| 图片 | 12 MiB |
| 音频 | 16 MiB |
| 视频 | 16 MiB |

这些是播放/存储上限，不同于单独的媒体理解限制。
有关转录和描述限制，请参阅
[图像和媒体支持](/nodes/images#limits-and-errors)。

## 故障排除

### 缺少时长或尺寸

检查 Gateway 主机上是否已安装 `ffprobe`，并且可通过其
`PATH` 找到：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ffprobe -version
```

即使没有元数据，仍然可以播放已经是便携格式的文件。

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
ffmpeg -version
ffprobe -version
```

`ffprobe` 用于识别编解码器和时长；`ffmpeg` 用于创建便携版本。如果任一步骤无法安全处理源文件，OpenClaw 会提供原始文件，客户端则继续使用其回退/下载路径。

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

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

### Linux 报告编解码器错误

请使用 [Linux 媒体编解码器](/platforms/linux#media-codecs) 中的软件包和源码构建说明。`.deb` 依赖所需的 GStreamer 插件软件包；AppImage 搭载了发布版本构建时安装的媒体框架和编解码器。

### Android 在离线时显示媒体行

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

## 相关内容

* [图像和媒体支持](/nodes/images)
* [音频和语音消息](/nodes/audio)
* [媒体概览](/tools/media-overview)
* [文本转语音](/tools/tts)
* [Linux 应用](/platforms/linux)