Appearance
OpenClaw 媒体理解在 AI 回复前对图片/音频/视频进行预处理生成文字摘要，帮助更快路由和命令解析。默认自动检测活跃回复模型或自带 CLI（如 whisper-cli、gemini），无需配置即可运行。可分别设置每个模型的最大字节数、超时和回退顺序，音频文件小于 1024 字节会被跳过。通过 /status 可查看各能力处理结果。
OpenClaw 媒体理解配置：图片/音频/视频自动摘要与回退
OpenClaw 可以在回复管道开始前自动摘要传入媒体（图片/音频/视频）。它会自动检测本地工具或 Provider key 是否可用，也支持完全禁用或自定义。即使理解失败或被禁用，模型仍会收到原始文件/URL 附件。
媒体理解的目标
- 可选加速：将传入媒体转化为简短文本，加快路由和命令解析
- 保留原始附件：始终向模型传递原始媒体
- 双模式执行：支持 Provider API 和本地 CLI 回退
- 有序回退：支持多个模型按错误/大小/超时顺序回退
工作流程
收集附件
读取传入附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
按能力选择附件
对每种已启用的能力（图片/音频/视频），按策略选择附件（默认取**第一个**）。
匹配模型
选择第一个符合条件的模型入口（大小 + 能力 + 认证）。
失败回退
若模型失败或媒体过大，**回退到下一个入口**。
成功输出
成功时：
- `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块
- 音频设置 `{{Transcript}}`；命令解析优先用字幕文本，否则用转录文本
- 字幕保留为块内的 `User text:`
若理解失败或被禁用，回复流程继续，使用原始 body + 附件。
配置概览
tools.media 支持共享模型列表和按能力覆盖：
json5
{
tools: {
media: {
models: [
/* 共享列表 */
],
image: {
/* 可选覆盖 */
},
audio: {
/* 可选覆盖 */
echoTranscript: true,
echoFormat: '📝 "{transcript}"',
},
video: {
/* 可选覆盖 */
},
},
},
}模型入口类型
每个 models[] 项可以是 provider 或 CLI：
Provider 入口
```json5
{
type: "provider", // 省略时默认为 provider
provider: "openai",
model: "gpt-5.5",
prompt: "Describe the image in <= 500 chars.",
maxChars: 500,
maxBytes: 10485760,
timeoutSeconds: 60,
capabilities: ["image"],
profile: "vision-profile",
preferredProfile: "vision-fallback",
}
```
CLI 入口
```json5
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
],
maxChars: 500,
maxBytes: 52428800,
timeoutSeconds: 120,
capabilities: ["video", "image"],
}
```
CLI 模板还可使用：
- `{{MediaDir}}`（媒体文件所在目录）
- `{{OutputDir}}`（本次运行的临时目录）
- `{{OutputBase}}`（无扩展名的临时文件基础路径）
默认值与限制
推荐默认值：
maxChars：图片/视频 500（简短，适合命令解析）maxChars：音频 不设限（完整转录，除非你主动设置限制）maxBytes：图片 10MB，音频 20MB，视频 50MB
规则
- 媒体超过 `maxBytes`，跳过该模型，尝试下一个。
- 音频文件小于 **1024 字节** 视为空/损坏，跳过之前不执行 Provider/CLI 转录；回复上下文收到固定占位符，告知智能体笔记太小。
- 模型返回内容超过 `maxChars` 时截断。
- `prompt` 默认为简单的 "Describe the {media}." 加上 `maxChars` 指引（仅图片/视频）。
- 若活跃回复模型原生支持视觉，OpenClaw 跳过 `[Image]` 摘要块，直接将原图传给模型。
- 若 Gateway/WebChat 主模型仅有文本能力，图片附件以 `media://inbound/*` 引用保存，供图片/PDF 工具或配置的图片模型继续检查。
- 显式的 `openclaw infer image describe --model <provider/model>` 请求不同：它直接调用支持图片能力的 Provider/模型，包括 Ollama 引用如 `ollama/qwen2.5vl:7b`。
- 若 `<capability>.enabled: true` 但未配置模型，OpenClaw 会尝试**活跃回复模型**（当它的 Provider 支持该能力时）。
自动检测（默认行为）
若 tools.media.<capability>.enabled 未设为 false 且未配置模型，OpenClaw 按以下顺序自动检测，遇到第一个可用即停止：
活跃回复模型
活跃回复模型（当它的 Provider 支持该能力时）。
agents.defaults.imageModel
`agents.defaults.imageModel` 主/备引用（仅图片）。
优先使用 `provider/model` 引用。裸引用仅当匹配唯一时从配置的图片能力 Provider 模型条目中补齐。
本地 CLI（仅音频）
若已安装：
- `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR` 包含 encoder/decoder/joiner/tokens）
- `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置 tiny 模型）
- `whisper`（Python CLI，自动下载模型）
Gemini CLI
`gemini` 使用 `read_many_files`。
Provider 认证
- 配置的 `models.providers.*` 条目中支持该能力的 Provider 优先于内置回退顺序。
- 仅图片的 config providers 带有图片能力模型时自动注册到媒体理解。
- Ollama 图片理解通过显式选择可用，例如通过 `agents.defaults.imageModel` 或 `openclaw infer image describe --model ollama/<vision-model>`。
内置回退顺序：
- 音频：OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
- 图片：OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
- 视频：Google → Qwen → Moonshot
禁用自动检测：
json5
{
tools: {
media: {
audio: {
enabled: false,
},
},
},
}INFO
二进制检测在 macOS/Linux/Windows 上是尽力而为；确保 CLI 在 PATH 中（我们扩展 ~），或者用完整命令路径设置显式 CLI 模型。
代理环境支持
当基于 Provider 的音频和视频媒体理解启用时，OpenClaw 遵守标准出站代理环境变量：
HTTPS_PROXYHTTP_PROXYALL_PROXYhttps_proxyhttp_proxyall_proxy
若无代理环境变量，媒体理解直接出站。若代理值格式错误，OpenClaw 记录警告并回退到直接请求。
能力限制（可选）
若设置 capabilities，条目仅对指定媒体类型运行。对于共享列表，OpenClaw 可推断默认值：
openai、anthropic、minimax：图片minimax-portal：图片moonshot：图片 + 视频openrouter：图片 + 音频google（Gemini API）：图片 + 音频 + 视频qwen：图片 + 视频mistral：音频zai：图片groq：音频xai：音频deepgram：音频- 任何
models.providers.<id>.models[]中有图片能力模型的：图片
对于 CLI 条目，显式设置 capabilities 以避免意外匹配。若省略 capabilities，条目适用于它所在列表中的所有媒体类型。
Provider 支持矩阵（OpenClaw 集成）
| 能力 | Provider 集成 | 备注 |
|---|---|---|
| 图片 | OpenAI、OpenAI Codex OAuth、Codex app-server、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI、config providers | vendor 插件注册图片支持；openai-codex/* 使用 OAuth provider 管道；codex/* 使用限定的 Codex app-server 回合；MiniMax 和 MiniMax OAuth 均使用 MiniMax-VL-01；图片能力的 config providers 自动注册。 |
| 音频 | OpenAI、Groq、xAI、Deepgram、OpenRouter、Google、SenseAudio、ElevenLabs、Mistral | Provider 转录（Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral）。 |
| 视频 | Google、Qwen、Moonshot | Provider 视频理解通过 vendor 插件；Qwen 视频理解使用标准 DashScope 端点。 |
INFO
MiniMax 说明
minimax、minimax-cn、minimax-portal、minimax-portal-cn的图片理解均来自插件自有的MiniMax-VL-01媒体 Provider。- 即使旧版 MiniMax M2.x 聊天元数据声称支持图片输入，自动图片路由仍始终使用
MiniMax-VL-01。
模型选择建议
- 对于质量和安全性要求高的场景，优先选择每类媒体能力中最强的最新模型。
- 对于处理不可信输入的工具型智能体，避免使用旧/弱媒体模型。
- 每类能力至少保留一个回退模型（质量模型 + 快速/廉价模型）。
- CLI 回退（
whisper-cli、whisper、gemini）在 Provider API 不可用时很有用。 parakeet-mlx说明：使用--output-dir时，OpenClaw 读取<output-dir>/<media-basename>.txt（输出格式为txt或未指定时）；非txt格式回退到 stdout。
附件策略
每种能力支持 attachments 配置：
mode
处理第一个选中的附件还是所有附件。
maxAttachments number
最多处理的附件数量。
prefer
候选附件中的选择偏好。
mode: "all" 时，输出标注为 [Image 1/2]、[Audio 2/2] 等。
文件附件提取行为
- 提取的文件文本在追加到媒体 prompt 前，会被包装为**不可信外部内容**。
- 注入块使用明确边界标记：`<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>` / `<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>` 并包含 `Source: External` 元数据行。
- 此附件提取路径有意省略冗长的 `SECURITY NOTICE:` 横幅，避免媒体 prompt 膨胀；边界标记和元数据仍保留。
- 若文件无可提取文本，OpenClaw 注入 `[No extractable text]`。
- 若 PDF 在此路径中回退到渲染页面图片，媒体 prompt 保留占位符 `[PDF content rendered to images; images not forwarded to model]`，因为此提取步骤转发的是文本块，而非渲染后的 PDF 图片。
配置示例
共享模型列表 + 覆盖
```json5
{
tools: {
media: {
models: [
{ provider: "openai", model: "gpt-5.5", capabilities: ["image"] },
{
provider: "google",
model: "gemini-3-flash-preview",
capabilities: ["image", "audio", "video"],
},
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
],
capabilities: ["image", "video"],
},
],
audio: {
attachments: { mode: "all", maxAttachments: 2 },
},
video: {
maxChars: 500,
},
},
},
}
```
仅音频 + 视频
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
{
type: "cli",
command: "whisper",
args: ["--model", "base", "{{MediaPath}}"],
},
],
},
video: {
enabled: true,
maxChars: 500,
models: [
{ provider: "google", model: "gemini-3-flash-preview" },
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
],
},
],
},
},
},
}
```
仅图片
```json5
{
tools: {
media: {
image: {
enabled: true,
maxBytes: 10485760,
maxChars: 500,
models: [
{ provider: "openai", model: "gpt-5.5" },
{ provider: "anthropic", model: "claude-opus-4-6" },
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
],
},
],
},
},
},
}
```
多模态单条目
```json5
{
tools: {
media: {
image: {
models: [
{
provider: "google",
model: "gemini-3.1-pro-preview",
capabilities: ["image", "video", "audio"],
},
],
},
audio: {
models: [
{
provider: "google",
model: "gemini-3.1-pro-preview",
capabilities: ["image", "video", "audio"],
},
],
},
video: {
models: [
{
provider: "google",
model: "gemini-3.1-pro-preview",
capabilities: ["image", "video", "audio"],
},
],
},
},
},
}
```
状态输出
媒体理解运行时，/status 包含简短摘要行：
📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)显示每种能力的处理结果和使用的 Provider/模型。
注意事项
- 理解是尽力而为的。错误不会阻塞回复。
- 即使理解禁用，附件仍会传递给模型。
- 使用
scope限制理解运行的范围（例如仅 DM）。
相关文档
常见问题
怎么确认媒体理解是否在工作？有没有命令可以查看？
运行 openclaw status 查看媒体摘要行，例如 📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)。如果显示 ok 说明该能力正常执行，skipped 或 failed 表示跳过或失败。
为什么我的音频文件没有被转录？一直显示 skipped？
可能原因：音频文件小于 1024 字节（视为空/损坏），或者文件大小超过了对应模型的 maxBytes（默认音频 20MB）。检查 tools.media.audio.models 中每个条目的 maxBytes 设置，并确认文件大小。
我想对所有传入的图片都进行理解，不只是第一张，怎么配置？
在 tools.media.image 下设置 attachments: { mode: "all", maxAttachments: 5 }（maxAttachments 可根据需要调整）。默认 mode 为 first 只处理第一张。