前言
现代即时通讯不仅限于文字。用户可能发送图片请求 AI 描述内容，发送语音让 AI 转写，或上传文档让 AI 分析。OpenClaw 作为多频道 AI 网关，需要统一处理来自不同平台的多媒体消息，而各平台的媒体能力又各不相同。本文将详细讲解 OpenClaw 的多媒体消息处理机制和配置方法。
支持的媒体类型
OpenClaw 目前支持以下四大类多媒体内容：
| 媒体类型 | 支持的格式 | 处理方式 |
|---|---|---|
| 图片 | JPG, PNG, GIF, WebP | 直接传递给支持视觉的模型 |
| 音频 | MP3, OGG, WAV, M4A | 使用 STT 引擎转写后作为文本输入 |
| 文档 | PDF, TXT, DOCX, CSV | 提取文本内容后作为上下文输入 |
| 视频 | MP4, WebM | 提取关键帧后作为图片序列处理 |
全局媒体配置
在 openclaw.json 中，媒体处理的全局配置位于 advanced.media 段：
{
"advanced": {
"media": {
"enabled": true,
"maxFileSize": "20mb",
"tempDir": "~/.openclaw/temp/media",
"cleanupInterval": "1h",
"image": {
"enabled": true,
"maxResolution": "2048x2048",
"autoResize": true,
"compressionQuality": 85
},
"audio": {
"enabled": true,
"sttProvider": "whisper",
"sttModel": "whisper-1",
"maxDuration": 300
},
"document": {
"enabled": true,
"maxPages": 50,
"ocrEnabled": false
},
"video": {
"enabled": false,
"maxDuration": 60,
"keyframeInterval": 5
}
}
}
}
关键参数说明
maxFileSize：允许处理的文件大小上限，超出的文件将被忽略并返回提示autoResize：当图片分辨率超出模型限制时自动缩放sttProvider：语音转文字服务提供商，支持whisper（OpenAI）和local（本地模型）maxDuration：音频和视频的最大时长限制（秒）
图片消息处理流程
当用户发送图片时，OpenClaw 的处理流程如下：
- 接收：从频道 API 下载图片到临时目录
- 预处理：检查格式、大小；必要时转换格式和缩放尺寸
- 路由：检查当前 Agent 配置的模型是否支持视觉输入
- 发送：以 Base64 或 URL 形式将图片附加到 API 请求中
- 清理：处理完成后按
cleanupInterval周期删除临时文件
如果当前模型不支持视觉能力，OpenClaw 有两种应对策略：
{
"advanced": {
"media": {
"image": {
"fallbackOnNoVision": "describe",
"visionFallbackModel": "claude"
}
}
}
}
"describe"：自动切换到支持视觉的模型描述图片内容，再将描述文本传递给原模型"reject"：直接告知用户当前模型不支持图片输入
音频消息处理
音频消息会先经过语音转文字（STT）处理，再作为文本消息传递给模型：
用户发送语音 → 下载音频文件 → STT 转写 → 将文字作为用户消息 → 发给模型
STT 结果会附带在会话记录的 metadata 字段中，方便回溯：
{
"id": "msg_010",
"role": "user",
"content": "明天下午三点帮我订个会议室",
"metadata": {
"originalType": "audio",
"sttConfidence": 0.95,
"audioDuration": 4.2
}
}
文档消息处理
用户上传的文档会被提取文本内容，然后作为上下文注入到对话中：
{
"advanced": {
"media": {
"document": {
"enabled": true,
"maxPages": 50,
"extractionMethod": "auto",
"injectAs": "system"
}
}
}
}
injectAs 控制文档内容在上下文中的角色：
"system"：作为系统消息注入，模型会视为背景知识"user"：作为用户消息的一部分，附加在用户文字后面
各频道媒体支持差异
不同即时通讯平台对媒体消息的支持差异显著，以下是 OpenClaw 适配的情况：
| 频道 | 图片接收 | 图片发送 | 音频接收 | 文档接收 | 备注 |
|---|---|---|---|---|---|
| Telegram | 完整支持 | 完整支持 | 完整支持 | 完整支持 | 最全面的媒体支持 |
| 完整支持 | 完整支持 | 完整支持 | 完整支持 | 需要 Business API | |
| Discord | 完整支持 | 完整支持 | 有限支持 | 完整支持 | 语音消息需要额外配置 |
| Slack | 完整支持 | 完整支持 | 不支持 | 完整支持 | 文件通过 Files API |
| iMessage | 完整支持 | 完整支持 | 完整支持 | 有限支持 | 依赖 BlueBubbles 桥接 |
| Signal | 完整支持 | 完整支持 | 完整支持 | 有限支持 | 通过 signal-cli |
| Web Dashboard | 完整支持 | 完整支持 | 不支持 | 完整支持 | 通过浏览器上传 |
| Matrix | 完整支持 | 完整支持 | 完整支持 | 完整支持 | 完整 Matrix 媒体 API |
频道级媒体覆盖
如果你希望在某些频道上禁用特定的媒体功能，可以在频道配置中覆盖全局设置：
{
"channels": {
"telegram": {
"enabled": true,
"token": "your-token",
"mediaSupport": {
"image": true,
"audio": true,
"document": true,
"video": false
}
},
"slack": {
"enabled": true,
"mediaSupport": {
"image": true,
"audio": false,
"document": true,
"video": false
}
}
}
}
模型的媒体能力
并非所有模型都支持多媒体输入。OpenClaw 内部维护了一张模型能力表：
| 模型 | 图片输入 | 音频输入 | 文档输入 |
|---|---|---|---|
| Claude Sonnet/Opus | 支持 | 不支持（需 STT） | 支持 PDF |
| GPT-4o | 支持 | 支持（原生） | 不支持（需提取） |
| Gemini 2.0 Flash | 支持 | 支持（原生） | 支持 |
| Ollama (LLaVA) | 支持 | 不支持 | 不支持 |
OpenClaw 会根据模型能力自动决定是否需要预处理。例如，发给 GPT-4o 的音频可以直接传递，而发给 Claude 的音频需要先经过 STT 转写。
媒体文件清理
为了避免临时文件无限增长，OpenClaw 会定期清理：
# 手动清理媒体缓存
openclaw media cleanup
# 查看媒体缓存占用
openclaw media stats
总结
OpenClaw 的多媒体处理系统在统一抽象的基础上，充分适配了各频道的差异化能力。通过合理配置，你可以让 AI 助手在不同平台上无缝处理图片、音频和文档，同时控制资源消耗。关键是根据实际使用的频道和模型，配置合适的媒体处理参数和回退策略。