OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

媒体与设备

媒体理解

OpenClaw 可以在回复流水线运行前汇总传入媒体（图像/音频/视频），让命令解析和路由基于简短文本而非原始字节进行。媒体理解功能会自动检测本地工具或提供商密钥，你也可以配置明确的模型。原始媒体始终会像往常一样传递给模型；媒体理解失败或被禁用时，回复流程将不受影响地继续运行。

供应商插件会注册能力元数据（哪个提供商支持哪种媒体类型、默认模型和优先级）。OpenClaw 核心负责共享的 tools.media 配置、回退顺序以及回复流水线集成。

工作原理

  • 收集附件

    收集传入附件（MediaPaths、MediaUrls、MediaTypes）。

  • 按能力选择

    对于每项已启用的能力（图像/音频/视频），根据 attachments 策略选择附件（默认：仅第一个附件）。

  • 选择模型

    选择第一个符合条件的模型条目（大小、能力和身份验证均可用）。

  • 失败时回退

    如果模型报错、超时或媒体超过 maxBytes，则尝试下一个条目。

  • 成功时应用

    Body 会变为 [Image]、[Audio] 或 [Video] 块。音频还会设置 {{Transcript}}；存在说明文字时，命令解析使用说明文字，否则使用转录文本。说明文字会作为块内的 User text: 保留。

    • 配置

    tools.media 包含共享模型列表以及按能力设置的覆盖项：

    json5
    {  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

    各能力（image/audio/video）的键：

    键 类型 默认值 说明
    enabled boolean 自动（false 表示禁用） 设为 false 可关闭此能力的自动检测
    models 数组 无 优先于共享的 tools.media.models 列表
    prompt string "Describe the {media}."（加上 maxChars 指引） 默认仅用于图像/视频
    maxChars number 500（图像/视频），未设置（音频） 如果模型返回的内容更多，则会截断输出
    maxBytes number 图像 10485760，音频 20971520，视频 52428800 媒体过大时跳到下一个模型
    timeoutSeconds number 60（图像/音频），120（视频）
    language string 未设置 音频转录语言提示
    baseUrl/headers/providerOptions/request - - 提供商请求覆盖项；参阅工具和自定义提供商
    attachments 对象 { mode: "first", maxAttachments: 1 } 参阅附件策略
    scope 对象 未设置 按渠道/聊天类型/键前缀进行限制
    echoTranscript boolean false 仅限音频：在智能体处理前将转录文本回显到聊天中
    echoFormat string '📝 "{transcript}"' 仅限音频：{transcript} 占位符

    Deepgram 专用选项放在 providerOptions.deepgram 下（顶层的 deepgram: { detectLanguage, punctuate, smartFormat } 字段已弃用，但仍会读取）。

    模型条目

    每个 models[] 条目都是一个提供商条目（默认）或 CLI 条目：

    提供商条目

    json5
    {  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared entries  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}}（暂存文件的基础路径，不含扩展名）。

    提供商凭据

    提供商媒体理解功能使用与普通模型调用相同的身份验证解析顺序：身份验证配置文件、环境变量，然后是 models.providers.<providerId>.apiKey。tools.media.*.models[] 条目不接受内联 apiKey 字段。

    json5
    {  models: {    providers: {      openai: { apiKey: "&lt;OPENAI_API_KEY&gt;" },      moonshot: { apiKey: "&lt;MOONSHOT_API_KEY&gt;" },    },  },}

    有关配置文件、环境变量和自定义基础 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）会直接运行该支持图像的提供商/模型；如果在 models.providers.ollama.models[] 下配置了匹配且支持图像的模型，也包括 ollama/qwen2.5vl:7b 等 Ollama 引用。
    • 如果 <capability>.enabled 不为 false，但未配置模型，那么当当前回复模型的提供商支持该能力时，OpenClaw 会尝试使用当前回复模型。

    自动检测（默认）

    当 tools.media.<capability>.enabled 不为 false 且未配置模型时，OpenClaw 会按以下顺序尝试，并在找到第一个可用选项后停止：

  • 已配置的图像模型（仅限图像）

    使用 agents.defaults.imageModel 的主要/回退引用，除非当前回复模型已经原生支持视觉能力。优先使用 provider/model 引用；只有在已配置且支持图像的提供商模型条目中存在唯一匹配项时，才会补全裸引用。

  • 当前回复模型

    当其提供商支持该能力时，使用当前回复模型。

  • 提供商身份验证（仅限音频，优先于本地 CLI）

    在本地 CLI 之前，尝试已配置且支持音频的 models.providers.* 条目。内置提供商优先级顺序（优先级相同时按提供商 ID 的字母顺序决定）：Groq/OpenAI → xAI → Deepgram → OpenRouter → Google/SenseAudio → Deepinfra/ElevenLabs → Mistral。

  • 本地 CLI（仅限音频）

    已就绪的本地二进制文件会组成有序回退列表：

    • 仅当当前进程中更早的模型调用观测到 Metal 或 CUDA 后，才将 whisper-cli 放在首位
    • 默认使用 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 条目会保留其配置顺序、后端标志和输出标志。

  • 提供商身份验证（图像/视频）

    在内置回退顺序之前，尝试已配置且支持该能力的 models.providers.* 条目。即使仅用于图像配置的提供商不是内置供应商插件，只要它包含支持图像的模型，也会自动注册用于媒体理解。

    内置提供商优先级顺序（优先级相同时按提供商 ID 的字母顺序决定）：

    • 图像：Anthropic/OpenAI → Google → MiniMax → Deepinfra → MiniMax Portal → Z.AI
    • 视频：Google → Qwen → Moonshot

  • Antigravity CLI（仅限图像/视频）

    使用首先安装的 agy 或 antigravity 二进制文件（可通过 OPENCLAW_ANTIGRAVITY_CLI 覆盖），并将其沙箱隔离到媒体所在目录。

    • 要禁用某项能力的自动检测：

    json5
    {  tools: {    media: {      audio: {        enabled: false,      },    },  },}

    代理支持（音频/视频提供商调用）

    基于提供商的音频和视频理解功能遵循标准出站代理环境变量，包括 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 key 或 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 端点。

    模型选择指南

    • 当质量和安全性很重要时，为每种媒体能力优先选择最强的当前代模型。
    • 对于处理不受信任输入且启用了工具的智能体，应避免使用较旧或较弱的媒体模型。
    • 为确保可用性，每种能力至少保留一个回退模型（高质量模型 + 更快或更便宜的模型）。
    • 当提供商 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"default: first

    仅处理第一个选中的附件，或处理所有附件。

    maxAttachmentsnumberdefault: 1

    限制处理的附件数量。

    prefer"first" | "last" | "path" | "url"

    候选附件之间的选择偏好。

    当 mode: "all" 时，输出会标记为 [图像 1/2]、[音频 2/2] 等。

    文件附件提取

    • 提取的文件文本在附加到媒体提示词之前，会被包装为不受信任的外部内容，使用类似 <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> 的边界标记，并包含一行 Source: External 元数据。
    • 此路径有意省略较长的 SECURITY NOTICE: 横幅，以缩短媒体提示词；边界标记和元数据仍然适用。
    • 没有可提取文本的文件会得到 [无可提取文本]。
    • 如果 PDF 回退为渲染后的页面图像，OpenClaw 会将这些图像转发给支持视觉能力的回复模型，并在文件块中保留占位符 [PDF 内容已渲染为图像]。

    配置示例

    共享模型 + 覆盖设置

    json5
    {  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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 会包含一行按能力汇总的信息：

    Code
    📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

    要进行预检清单检查，请运行 openclaw capability audio providers。本地行会将本地回退的胜出项与全局提供商选择、就绪状态，以及相互独立的可用/请求/观测后端字段分开显示。同一本地选择也会作为信息级 Doctor 检查结果提供：

    bash
    openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

    注意事项

    • 理解功能采用尽力而为的方式。错误不会阻止回复。
    • 即使理解功能已禁用，附件仍会传递给模型。
    • 使用 scope 限制理解功能的运行位置（例如仅限私信）。

    相关内容

    Was this useful?
    On this page

    On this page