媒体理解
OpenClaw 可以在回复流水线运行之前总结入站媒体(image/audio/video),因此命令解析和路由基于短文本而非原始字节进行。Understanding 会自动检测本地工具或提供商密钥,也可以配置显式模型。在 OpenClaw 管理的回复路径中,成功描述的图片会以文本表示,而不会再次作为原生图片附加。失败、禁用或未选中的图片仍符合正常原生图片投递条件;Understanding 错误不会阻止回复。
供应商插件注册能力元数据(哪个提供商支持哪种媒体类型、默认模型、优先级)。OpenClaw 核心负责共享的 tools.media 配置、回退顺序以及回复流水线集成。
工作原理¶
1. 收集附件
收集有序的入站媒体事实(path、url、contentType 和 kind)。
2. 按能力选择
对于每个已启用的能力(image/audio/video),按照 attachments 策略选择附件(默认:仅第一个附件)。
3. 选择模型
选择第一个符合条件的模型条目(大小 + 能力 + 认证可用)。
4. 失败时回退
如果模型出错、超时,或媒体超过 maxBytes,则尝试下一个条目。
5. 成功时应用
Body 会变为 [Image]、[Audio] 或 [Video] 块。音频还会设置 {{Transcript}};命令解析在存在说明文字时使用说明文字,否则使用转录文本。说明文字会作为 User text: 保留在块内。
配置¶
tools.media 包含一个带能力标签的模型列表,以及少量按能力划分的控制项:
{
tools: {
media: {
concurrency: 2, // max concurrent capability runs (default)
models: [
{ provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },
{ provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },
],
image: { preferredModel: "google/gemini-3-flash-preview" },
audio: { enabled: true },
video: { enabled: true },
},
},
}
按能力(image/audio/video)的键:
| Key | Type | Default | Notes |
|---|---|---|---|
enabled |
boolean |
自动(false 禁用) |
设置 false 可关闭此能力的自动检测 |
preferredModel |
string |
第一个兼容条目 | 优先使用 provider/model、模型 id、provider:<id> 或 cli:command |
prompt |
string |
能力默认值 | 当条目未覆盖时使用的默认 Prompt |
maxChars |
number |
500 image/video,audio 未设置 |
默认输出限制 |
maxBytes |
number |
image 10MB,audio 20MB,video 50MB | 默认输入限制 |
timeoutSeconds |
number |
60 image/audio,120 video |
默认请求超时 |
language |
string |
未设置 | 音频转录提示 |
scope |
object | 未设置 | 按 channel/chat 类型/source key 进行门控 |
attachments |
object | { mode: "first", maxAttachments: 1 } |
选择要处理哪些匹配的附件 |
echoTranscript |
boolean |
false |
仅音频:在代理处理前回显转录文本 |
echoFormat |
string |
'📝 "{transcript}"' |
仅音频:回显转录文本的格式 |
Prompt、限制、语言提示、请求覆盖和提供商选项可以设置为能力默认值,也可以在单个 tools.media.models[] 条目上覆盖。能力默认值还会覆盖未配置显式模型时自动检测到的提供商。模型列表选择要运行哪些条目;它不会从提供商发现中隐藏其他已启用的提供商。
模型条目¶
每个 models[] 条目都是 provider 条目(默认)或 CLI 条目:
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{AttachmentPath}} and describe it in <= {{MaxChars}} characters.",
],
maxChars: 500,
maxBytes: 52428800,
timeoutSeconds: 120,
capabilities: ["video", "image"],
}
占位符会按字面替换到每个参数中,未设置的占位符会变成 空参数,而不是被丢弃。{{Language}} 仅对 audio 填充,当语言从请求、条目的 language 或 tools.media.audio.language 解析得到时;如果均未设置,["--language", "{{Language}}"] 会执行为 --language ""。拒绝空语言的转录器应同时省略该标志及其值,并依赖自动检测。{{Prompt}} 会回退到内置默认 Prompt,因此通常会被填充。相同的空替换也适用于其他没有值的占位符,例如对于没有 MIME 类型的附件的 {{AttachmentContentType}}。
CLI 模板还可以使用 {{AttachmentUrl}}、{{AttachmentContentType}}、{{AttachmentDir}}、{{AttachmentIndex}}、{{OutputDir}}(为本次运行创建的临时目录)和 {{OutputBase}}(临时文件基础路径,无扩展名)。{{Attachment*}} 名称在 2026.8.1 中替换了 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}}。旧名称在 media-legacy-projection 记录下仍保留为已弃用的兼容别名:其已批准的 removeAfter 日期为 2026-10-01,并且移除还受一次干净的已发布插件产物扫描门控。请在此日期之前迁移 - 参见 媒体旧版投影。
CLI 条目需要一个非空白的 command 和一个非空的 args 列表。参数保持为字面字符串,并支持可选的模板插值;现有的字面文件路径和自定义包装器参数均受支持。请通过模板(例如 {{AttachmentPath}})或命令现有的输入契约传递附件。由于 OpenClaw 不会将附件输入到 CLI stdin,因此不支持空的参数列表。openclaw doctor 会报告缺失的命令或参数,并给出确切的配置路径和手动修复方法;它不会凭空生成命令或重写这些条目。在运行时,不完整的条目会记录一次失败,而不会启动二进制文件,然后尝试下一个已配置的模型。如果没有任何模型成功,附件会获得失败结果,并记录一条警告。对于这些字段,配置验证仍然保持宽松,以便现有配置在更新后仍能启动 Gateway。
远程附件仅当 CLI 需要文件路径时,才会被暂存为临时文件。媒体理解运行拥有这些文件,并在处理完成后删除它们;暂存失败不会使其他已暂存的附件不可用。现有本地附件会就地读取并保留。
提供商凭据¶
提供商媒体理解使用与普通模型调用相同的身份验证解析:身份验证配置文件、环境变量,然后是 models.providers.<providerId>.apiKey。tools.media.models[] 条目不接受内联 apiKey 字段。
{
models: {
providers: {
openai: { apiKey: "<OPENAI_API_KEY>" },
moonshot: { apiKey: "<MOONSHOT_API_KEY>" },
},
},
}
有关配置文件、环境变量和自定义基础 URL,请参阅 工具和自定义提供商。
规则与行为¶
- 超过
maxBytes的媒体会跳过该模型并尝试下一个模型。 - 小于 1024 字节的音频文件会被视为空/损坏,并在转录前跳过;代理会收到一个确定性的占位转录文本。
- 如果活动的主要图像模型已原生支持视觉,OpenClaw 会跳过
[Image]摘要块,并将原始图像直接传入模型。MiniMax 是例外:minimax、minimax-cn、minimax-portal和minimax-portal-cn始终通过插件拥有的MiniMax-VL-01媒体提供商路由图像理解,即使旧版 MiniMax M2.x 聊天元数据声称支持图像输入(只有MiniMax-M3及以后版本被视为原生支持视觉)。 - 如果 Gateway/WebChat 主要模型仅支持文本,图像附件会作为已卸载的
media://inbound/*引用保留,这样图像/PDF 工具或已配置的图像模型仍可以检查它们,而不是丢失附件。 - 显式
openclaw infer image describe --file <path> --model <provider/model>(别名:openclaw capability image describe)会直接运行该支持图像的提供商/模型,包括 Ollama 引用(例如ollama/qwen2.5vl:7b),前提是已在models.providers.ollama.models[]下配置了匹配的支持图像的模型。 - 如果
<capability>.enabled不为false,但未配置任何模型,OpenClaw 会在其提供商支持该能力时尝试活动的回复模型。
自动检测(默认)¶
当 tools.media.<capability>.enabled 不为 false 且未配置任何模型时,OpenClaw 会按以下顺序尝试,并在第一个可用选项处停止:
1. 已配置图像模型(仅图像)
agents.defaults.imageModel 主/回退引用,除非活动回复模型已原生支持视觉。优先使用 provider/model 引用;裸引用仅当匹配唯一时,才会从已配置的支持图像的提供商模型条目中限定。
2. 活动回复模型
当活动回复模型的提供商支持该能力时,使用该活动回复模型。
3. 提供商身份验证(仅音频,在本地 CLI 之前)
支持音频的已配置 models.providers.* 条目会在本地 CLI 之前尝试。捆绑提供商优先级顺序(平局按提供商 id 的字母顺序打破):Groq/OpenAI → xAI → Deepgram → OpenRouter → Google/SenseAudio → Deepinfra/ElevenLabs → Mistral。
4. 本地 CLI(仅音频)
就绪的本地二进制文件会形成一个有序回退列表:
- whisper-cli 只有在当前进程中更早的模型调用观察到 Metal 或 CUDA 后才优先
- CPU 默认的 sherpa-onnx-offline(需要 SHERPA_ONNX_MODEL_DIR 包含 tokens.txt/encoder.onnx/decoder.onnx/joiner.onnx)
- 当加速仅具备构建能力或未被观察到时,使用 whisper-cli
- 在 Apple Silicon 上使用 parakeet-mlx(支持 MLX,设备使用未被观察到)
- whisper(Python CLI;默认使用 turbo 模型,会自动下载)
后端能力检查会被缓存,并且不会加载模型。构建能力、请求的后端标志以及从真实调用中观察到的后端保持独立。自动检测的 whisper.cpp 会保持模型运行日志启用,以便记录上游选定的后端行。显式 CLI 条目会保留其配置顺序、后端标志和输出标志。
5. 提供商身份验证(图像/视频)
支持该能力的已配置 models.providers.* 条目会在捆绑回退顺序之前尝试。即使不是捆绑的供应商插件,仅图像的配置提供商如果具有支持图像的模型,也会自动注册用于媒体理解。
捆绑提供商优先级顺序(平局按提供商 id 的字母顺序打破): - 图像:Anthropic/OpenAI → Google → MiniMax → Deepinfra → MiniMax Portal → Z.AI - 视频:Google → Qwen → Moonshot
要禁用某个能力的自动检测:
Note
二进制检测在 macOS/Linux/Windows 上是尽力而为的;请确保 CLI 位于 PATH 上(~ 会被展开),或设置一个带有完整命令路径的显式 CLI 模型条目。
代理支持(音频/视频提供商调用)¶
基于提供商的 音频 和 视频 理解会遵循标准出站代理环境变量,包括 NO_PROXY/no_proxy 绕过规则:HTTPS_PROXY、HTTP_PROXY、ALL_PROXY、https_proxy、http_proxy、all_proxy。小写变量优先于大写变量。如果未设置任何变量,媒体理解将使用直接出站;如果代理值格式错误,OpenClaw 会记录警告并回退到直接获取。图像理解不经过此代理路径。
功能¶
在 models[] 条目上设置 capabilities,以将其限制为特定媒体类型。对于共享列表,OpenClaw 会按捆绑提供商推断默认值:
| 提供商 | 功能 |
|---|---|
openai, anthropic, minimax |
图像 |
minimax-portal |
图像 |
moonshot |
图像 + 视频 |
openrouter |
图像 + 音频 |
google(Gemini API) |
图像 + 音频 + 视频 |
qwen |
图像 + 视频 |
deepinfra |
图像 + 音频 |
mistral |
音频 |
zai |
图像 |
groq, xai, deepgram, senseaudio |
音频 |
任何包含支持图像模型的 models.providers.<id>.models[] 目录 |
图像 |
CLI 条目需要显式 capabilities;没有有效功能标签的条目会被跳过。没有有效显式标签的提供商条目会使用其注册的功能元数据。
提供商支持矩阵¶
| 功能 | 提供商 | 说明 |
|---|---|---|
| 图像 | Anthropic, Codex app-server, Deepinfra, Google, MiniMax, MiniMax Portal, Moonshot, OpenAI, OpenAI Codex OAuth, OpenRouter, Qwen, Z.AI, 配置提供商 | 厂商插件注册图像支持;openai/* 可使用 API 密钥或 Codex OAuth 路由;codex/* 使用有界的 Codex app-server 轮次;支持图像的配置提供商会自动注册。 |
| 音频 | Deepgram, Deepinfra, ElevenLabs, Google, Groq, Mistral, OpenAI, OpenRouter, SenseAudio, xAI | 提供商转录(Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral)。 |
| 视频 | Google, Moonshot, Qwen | 通过厂商插件提供商视频理解;Qwen 视频理解使用标准 DashScope 端点。 |
Note
MiniMax 说明:minimax、minimax-cn、minimax-portal 和 minimax-portal-cn 的图像理解始终来自插件拥有的 MiniMax-VL-01 媒体提供商,即使旧版 MiniMax M2.x 聊天元数据声称支持图像输入。
模型选择指南¶
- 当质量和安全性重要时,优先为每种媒体功能选择当前代最强的模型。
- 对于处理不可信输入的工具启用代理,避免使用较旧/较弱的媒体模型。
- 为每种功能至少保留一个回退项以保证可用性(高质量模型 + 更快/更便宜的模型)。
- 当提供商 API 不可用时,CLI 回退项(
whisper-cli、whisper、gemini)会有帮助。 - 已知的文件输出模式具有权威性:空或缺失的推断转录文件不会产生转录,而不是回退到 CLI 进度输出。
parakeet-mlx:使用--output-format txt(或all)配合--output-dir和默认{filename}输出模板。上游PARAKEET_OUTPUT_FORMAT和PARAKEET_OUTPUT_TEMPLATE环境变量也会被遵循。OpenClaw 读取<output-dir>/<media-basename>.txt;默认srt格式、其他格式以及自定义输出模板继续使用 stdout。
附件策略¶
按功能划分的 attachments 控制处理哪些附件:
mode"first" | "all"(路径)默认值:first- 仅处理第一个选中的附件,或处理全部附件。
maxAttachmentsnumber(路径)默认值:1- 限制处理数量。
prefer"first" | "last" | "path" | "url"(路径)- 在候选附件中的选择偏好。
当 mode: "all" 时,输出会标记为 [Image 1/2]、[Audio 2/2] 等。
本地附件必须保持在会话允许的媒体根目录内。当打开的文件仍位于这些根目录内时,会接受 macOS /tmp 和 /private/tmp 等目录别名;它们不会授予访问同级沙箱工作区的权限。
文件附件提取¶
- 每个传入的文档附件最终都会形成一个模型可见的文件块。被路由到图像、音频或视频理解的附件不在此契约范围内;这些阶段负责其结果。
- 提取的文件文本在追加到媒体提示之前,会被包装为不可信外部内容,使用诸如
<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>/<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>的边界标记,外加一行Source: External元数据。 - 此路径有意省略一行数据边界说明,以保持媒体提示简短;边界标记和元数据仍然适用。
- 保存在本地磁盘上的不支持文件,仅在回复运行时证明其可以读取主机本地路径时(目前为非沙箱嵌入式会话)才会获得自助指导。该路径被围栏为不可信外部元数据;可信指导会告知代理使用其自身工具提取文件,现代 Office 文件会获得解压缩提示。通用 ACP 后端、仅 URL 附件以及沙箱会话保留纯文本
[Unsupported document format: <mime>. PDF and plain-text attachments can be read.]标记。 - 被操作员配置的允许列表拒绝的文件永远不会包含自助路径;策略拒绝不应指导代理绕过操作员的决定。
- 被操作员配置的
allowedMimes列表拒绝的文件会改为获得[Attachment type not allowed: <mime>],因此提示永远不会声称支持当前配置已禁用的内容。 - 读取失败会获得
[Attachment could not be read]。 - 当 URL 文件源被禁用时,URL 附件会获得
[Attachment skipped: URL file sources are disabled]。 - 没有可提取文本的文件(包括空的本地文本文件)会获得
[No extractable text],并且不会消耗跳过标记预算。 - 每条消息最多渲染五个跳过标记;更多被跳过的附件会合并为一个原因中立的
[<n> more attachments skipped]摘要,以便垃圾附件不会使提示无限增长。文件以及图像、音频或视频标记共享此五个标记预算。 - 如果 PDF 回退到渲染的页面图像,OpenClaw 会将这些图像转发给支持视觉的回复模型,并在文件块中保留占位符
[PDF content rendered to images]。 - 如果页面、文本或图像限制导致文档提取不完整,文件块会以有界的
[Partial document: ...]标记开头,以免回复模型将可见前缀误认为完整附件。 - 图像、音频和视频决策会为每个附件候选记录一个明确的最终处置:已处理、交给原生视觉、在附件限制后未选中、已禁用、缺少模型、被聊天范围拒绝或失败。
- 未处理的媒体会获得有界的模型可见标记。交给原生视觉的图像不会添加标记。当原生 harness 拥有该轮次且 OpenClaw 仅运行音频预处理时,失败或跳过的音频仍会获得标记;图像、视频和文档输入仍由 harness 拥有。过小的音频会保留其占位符转录,而不添加重复标记。
视觉模型与图像重放成本¶
在 OpenClaw 管理的回复路径中,具备视觉能力的回复模型通常直接接收原生图像,无需单独的图像描述处理。保留在后续请求中的图像可能计入输入成本;具体金额取决于提供商以及当前运行时的上下文处理方式。有关适用的清理行为,请参阅会话修剪。
对于不需要持续访问像素的识别或提取任务,tools.media.models[] 中的图像能力条目会选择启用图像理解,即使回复模型支持视觉。对于每个成功生成描述的已选图像,回复将接收描述文本以替代该原生图像。这并不保证所有附加图像都会被转换,也不保证后续请求中不包含图像。
{
tools: {
media: {
models: [{ provider: "google", model: "gemini-3-flash-preview", capabilities: ["image"] }],
},
},
}
权衡与边界:
- 选择默认仅针对第一个匹配的图像。使用现有的
tools.media.image.attachments策略可选择更多图像,并设置显式的maxAttachments上限。失败或未选择的图像仍可以原生方式传递。 - 成功生成的描述会在当前回复轮次中替换该图像的像素。当回复模型需要直接检查像素时,应避免这样做,例如截图、UI 审查或可视化调试。
- 显式的图像能力
tools.media.models[]条目会覆盖原生视觉跳过,但受现有启用、范围、大小和附件限制约束。仅tools.media.image.preferredModel不会覆盖该跳过。 tools.media.image.enabled: false会禁用图像理解;它不会禁用原生图像传递。- 这描述的是 OpenClaw 管理的预处理。拥有图像处理权限的原生框架具有自己的传递和上下文规则;不要假设此设置会控制其图像重放或计费。
配置示例¶
{
tools: {
media: {
models: [
{ provider: "openai", model: "gpt-6-astra", 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 {{AttachmentPath}} and describe it in <= {{MaxChars}} characters.",
],
capabilities: ["image", "video"],
},
],
audio: {
attachments: { mode: "all", maxAttachments: 2 },
},
video: {
maxChars: 500,
},
},
},
}
{
tools: {
media: {
models: [
{
provider: "openai",
model: "gpt-4o-mini-transcribe",
capabilities: ["audio"],
},
{
type: "cli",
command: "whisper",
args: ["--model", "base", "{{AttachmentPath}}"],
capabilities: ["audio"],
},
{
provider: "google",
model: "gemini-3-flash-preview",
capabilities: ["video"],
},
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{AttachmentPath}} and describe it in <= {{MaxChars}} characters.",
],
capabilities: ["video"],
},
],
audio: {
enabled: true,
},
video: {
enabled: true,
maxChars: 500,
},
},
},
}
{
tools: {
media: {
models: [
{ provider: "openai", model: "gpt-6-astra", capabilities: ["image"] },
{ provider: "anthropic", model: "claude-opus-5", capabilities: ["image"] },
{
type: "cli",
command: "gemini",
args: [
"-m",
"gemini-3-flash",
"--allowed-tools",
"read_file",
"Read the media at {{AttachmentPath}} and describe it in <= {{MaxChars}} characters.",
],
capabilities: ["image"],
},
],
image: {
enabled: true,
maxBytes: 10485760,
maxChars: 500,
},
},
},
}
状态输出¶
当媒体理解运行时,/status 会包含按能力划分的摘要行:
自动检测到的本地音频工具会将解析后的可执行文件路径作为结果的 model 报告,因此状态和详细摘要可以在工具族和后端旁边包含该路径。显式 CLI 条目会保留其编写的命令;预检清单会保留逻辑工具名称。
对于预检清单,运行 openclaw capability audio providers。本地行会将本地回退获胜者与全局提供商选择、就绪状态以及独立的 capable/requested/observed 后端字段分开显示。相同的本地选择也可作为信息性 doctor 发现提供:
备注¶
- 理解功能采用尽力而为的方式。错误不会阻止回复。
- 即使禁用理解功能,附件仍会传递给模型。
- 使用
scope限制理解功能的运行范围(例如,仅限私信)。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw