媒体理解

OpenClaw 可以在回复流水线运行之前概括入站媒体（图片/音频/视频），因此命令解析和路由可以基于短文本而非原始字节工作。理解功能会自动检测本地工具或提供商密钥，或者你也可以配置显式模型。原始媒体始终照常传递给模型；当理解失败或被禁用时，回复流程保持不变。

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

工作原理¶

1. 收集附件

收集有序的入站媒体事实（path、url、contentType 和 kind）。

2. 按能力选择

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

3. 选择模型

选择第一个符合条件的模型条目（大小 + 能力 + 可用认证）。

4. 失败时回退

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

5. 成功后应用

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

配置¶

tools.media 包含一个带有能力标签的模型列表，外加少量按能力划分的控制项：

{
  tools: {
    media: {
      concurrency: 2, // 最大并发能力运行数（默认）
      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）键：

提示词、限制、语言提示、请求覆盖项和提供商选项可以设置为能力默认值，也可以在单个 tools.media.models[] 条目上覆盖。能力默认值也覆盖自动检测到的提供商（当未配置显式模型时）。模型列表用于选择运行哪些条目；它不会将其他已启用的提供商从提供商发现中隐藏。

模型条目¶

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

{
  type: "provider", // 默认，如果省略
  provider: "openai",
  model: "gpt-6-astra",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"],
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  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"],
}

CLI 条目需要非空 command 和非空 args 列表。参数保持为字面量字符串，并可选地进行模板插值；支持现有的字面量文件路径和自定义包装参数。通过诸如 {{AttachmentPath}} 之类的模板或你的命令已有的输入契约传递附件。不支持空参数列表，因为 OpenClaw 不会将附件通过 stdin 提供给 CLI。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

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

{
  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 会根据内置提供商推断默认值：

CLI 条目需要显式的 capabilities；没有有效能力标签的条目会被跳过。没有有效显式标签的提供商条目会使用其已注册的能力元数据。

提供商支持矩阵¶

模型选择指南¶

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

仅处理第一个选中的附件，或处理全部附件。

maxAttachments number (path) 默认: 1

限制处理的数量。

prefer "first" | "last" | "path" | "url" (path)

在候选附件中的选择偏好。

当 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 拥有。过小的音频会保留其占位符转录，而不添加重复标记。

配置示例¶

{
  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,
      },
    },
  },
}

{
  tools: {
    media: {
      models: [
        {
          provider: "google",
          model: "gemini-3.1-pro-preview",
          capabilities: ["image", "video", "audio"],
        },
      ],
    },
  },
}

状态输出¶

当媒体理解运行时，/status 会包含一行按能力划分的摘要：

📎 Media: image ok (openai/gpt-6-astra) · audio ok (whisper-cli observed=metal)

自动检测到的本地音频工具会将解析后的可执行文件路径作为结果的 model 上报，因此状态和详细摘要可以在工具族和后端旁边包含该路径。显式 CLI 条目保留其编写的命令；预检清单保留逻辑工具名称。

对于预检清单，请运行 openclaw capability audio providers。本地行会将本地回退胜出项与全局提供商选择、就绪状态以及独立的 capable/requested/observed 后端字段分开显示。相同的本地选择也可作为信息性 doctor 发现项使用：

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

说明¶

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

相关¶

• 配置
• 图像和媒体支持
• 音频和语音留言
• 相机捕获
• 媒体播放
• 对话模式
• 语音唤醒
• Mistral — Voxtral 音频转录，是上述支持音频的提供商之一
• 媒体概览 — 媒体工具如何协同工作