本页介绍 OpenClaw 的媒体理解功能：在 AI 回复前，对传入的图片/音频/视频进行预处理，生成文字摘要注入上下文。支持 Provider API 和本地 CLI 两种方式，可按渠道/媒体类型分别配置，自动检测已有工具/API key，无配置即可运行。

OpenClaw 媒体理解

OpenClaw 可在回复流程开始前自动摘要传入媒体（图片/音频/视频）。它会自动检测本地工具或 Provider key 是否可用，也可以禁用或自定义。若理解功能关闭，模型仍会以原始文件/URL 形式收到附件。

工作流程

1. 收集传入附件（MediaPaths、MediaUrls、MediaTypes）
2. 对每种已启用的能力（图片/音频/视频），按策略选择附件（默认：第一个）
3. 选择第一个符合条件的模型入口（尺寸 + 能力 + 认证）
4. 如果模型失败或媒体过大，回退到下一个入口
5. 成功时：
   • Body 变为 [Image]、[Audio] 或 [Video] 块
   • 音频设置 ；命令解析优先用字幕文本，否则用转录文本
   • 字幕保留为块内的 User text:

若理解失败或被禁用，回复流程继续，使用原始 body + 附件。

配置概览

tools.media 支持共享模型列表和按能力覆盖：

{
  tools: {
    media: {
      models: [
        /* 共享列表 */
      ],
      image: {
        /* 可选覆盖 */
      },
      audio: {
        /* 可选覆盖 */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* 可选覆盖 */
      },
    },
  },
}

模型入口类型

Provider 模型：

{
  type: "provider",
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "用不超过 500 字描述这张图片。",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"],
  profile: "vision-profile",
}

CLI 模型：

{
  type: "cli",
  command: "gemini",
  args: [
    "-m", "gemini-3-flash",
    "--allowed-tools", "read_file",
    "读取 {{MediaPath}} 处的媒体，用不超过 {{MaxChars}} 字描述它。",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

CLI 模板还可使用：（媒体文件所在目录）、（本次运行的临时目录）、（无扩展名的临时文件基础路径）

默认值与限制

推荐默认值：

• maxChars：图片/视频 500（简短，适合命令解析）
• maxChars：音频 不设限（完整转录）
• maxBytes：图片 10MB，音频 20MB，视频 50MB

规则：

• 媒体超过 maxBytes → 跳过该模型，尝试下一个
• 音频文件小于 1024 字节 → 视为空/损坏，跳过
• 模型返回内容超过 maxChars → 截断
• 主图像模型原生支持视觉时，OpenClaw 跳过 [Image] 摘要块，直接传原图

自动检测（默认行为）

未设置 enabled: false 且未配置模型时，OpenClaw 按以下顺序自动检测，遇到第一个可用就停止：

1. 活跃回复模型（其 Provider 支持该能力时）
2. agents.defaults.imageModel 主/备引用（仅图片）
3. 本地 CLI（仅音频）
   • sherpa-onnx-offline（需 SHERPA_ONNX_MODEL_DIR）
   • whisper-cli（whisper-cpp；使用 WHISPER_CPP_MODEL 或内置 tiny 模型）
   • whisper（Python CLI，自动下载模型）
4. Gemini CLI（gemini）使用 read_many_files
5. Provider 认证 — 有图像能力的 config providers 自动注册；内置回退顺序：
   • 音频：OpenAI → Groq → Deepgram → Google → Mistral
   • 图片：OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
   • 视频：Google → Qwen → Moonshot

禁用自动检测：

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

代理环境支持

Provider 音频和视频媒体理解启用时，OpenClaw 遵守标准出站代理环境变量：HTTPS_PROXY、HTTP_PROXY、https_proxy、http_proxy。

各 Provider 支持矩阵

能力	支持的 Provider	备注
图片	OpenAI、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI 及 config providers	MiniMax 和 MiniMax OAuth 均使用 MiniMax-VL-01；有图像能力的 config providers 自动注册
音频	OpenAI、Groq、Deepgram、Google、Mistral
视频	Google、Qwen、Moonshot	Qwen 视频理解使用标准 DashScope 端点

MiniMax 说明：

• minimax 和 minimax-portal 图片理解均来自插件自有的 MiniMax-VL-01 媒体 Provider
• 内置 MiniMax 文本目录默认仅限文本；显式配置 models.providers.minimax 条目可启用图像能力的 M2.7 聊天引用

附件策略

每种能力支持 attachments 配置：

• mode：first（默认）或 all
• maxAttachments：处理附件数上限（默认 1）
• prefer：first、last、path、url

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 图片

配置示例

1）共享模型列表 + 各类型覆盖

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

2）仅开启音频 + 视频（关闭图片）

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

3）可选图片理解

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { provider: "anthropic", model: "claude-opus-4-6" },
        ],
      },
    },
  },
}

状态输出

媒体理解运行时，/status 包含摘要行：

📎 Media: image ok (openai/gpt-5.4-mini) · audio skipped (maxBytes)

显示每种能力的处理结果和使用的 Provider/模型。

注意事项

• 理解是尽力而为的，报错不会阻断回复
• 理解禁用时，附件仍会传递给模型
• 用 scope 限制理解运行的范围（如仅 DM）

相关文档

• 网关配置
• 图片与媒体支持

常见问题

Q: 我没有配置任何媒体模型，但图片理解似乎已经在工作，为什么？

A: OpenClaw 自动检测活跃回复模型是否支持视觉能力。如果你用的是 Claude Sonnet 或 GPT-4 系列，它们原生支持图片，OpenClaw 会直接传原图而非生成摘要。

Q: 音频转录结果没有出现在对话中，如何确认转录是否成功？

A: 检查 openclaw status 中的媒体摘要行。如果显示 audio ok，说明转录正常；如显示 audio skipped (maxBytes) 则文件太大被跳过。也可设置 echoTranscript: true 让转录文本直接显示在聊天中。

Q: 想要对所有传入图片都进行理解而不只是第一张，怎么配置？

A: 在图片能力下设置 attachments: { mode: "all", maxAttachments: 5 }（根据需要调整上限数量）。