Media Understanding（入站）— 2026-01-17

Media Understanding（入站）— 2026-01-17

OpenClaw 可以在回复流水线运行之前，先对入站媒体（image/audio/video）做摘要理解。它会在检测到本地工具或 provider keys 可用时自动启用，也可以被禁用或自定义。若 understanding 关闭，models 仍会像平常一样收到原始文件/URLs。

各 vendor 专属的媒体行为由 vendor plugins 注册，而 OpenClaw core 负责统一的 tools.media 配置、fallback 顺序以及与 reply pipeline 的集成。

目标

可选：先将入站媒体预处理为简短文本，以便更快路由并提升命令解析效果。
始终保留原始媒体传递给 model（永远如此）。
支持 provider APIs 和 CLI fallbacks。
允许多个 model 按顺序 fallback（基于 error/size/timeout）。

高层行为

收集入站附件（MediaPaths、MediaUrls、MediaTypes）。
对每个启用的 capability（image/audio/video），按照策略选择附件（默认：first）。
选择第一个符合条件的 model entry（基于 size + capability + auth）。
如果某个 model 失败，或媒体过大，则回退到下一个 entry。
成功时：
- Body 会变成 [Image]、[Audio] 或 [Video] block。
- Audio 会设置 {{Transcript}}；命令解析优先使用 caption text，如无 caption，则使用 transcript。
- Captions 会以 User text: 的形式保留在 block 中。

如果 understanding 失败或被禁用，reply flow 仍会继续，并使用原始 body + attachments。

配置概览

tools.media 支持 共享 models 以及按 capability 的覆盖配置：

tools.media.models：共享 model 列表（使用 capabilities 做约束）。
tools.media.image / tools.media.audio / tools.media.video：
- 默认值（prompt、maxChars、maxBytes、timeoutSeconds、language）
- provider overrides（baseUrl、headers、providerOptions）
- Deepgram audio 选项通过 tools.media.audio.providerOptions.deepgram
- audio transcript echo 控制（echoTranscript，默认 false；echoFormat）
- 可选的 按 capability 单独定义的 models 列表（优先于 shared models）
- attachments 策略（mode、maxAttachments、prefer）
- scope（可选，用于按 channel/chatType/session key 做限制）
tools.media.concurrency：最大并发 capability 运行数（默认 2）。

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

Model entries

每个 models[] entry 都可以是 provider 或 CLI：

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, used for multi-modal entries
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  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 templates 还可以使用：

{{MediaDir}}（包含该媒体文件的目录）
{{OutputDir}}（本次运行创建的 scratch dir）
{{OutputBase}}（scratch 文件基础路径，不带扩展名）

默认值与限制

推荐默认值：

maxChars：image/video 推荐 500（简短、便于命令处理）
maxChars：audio 推荐 不设置（默认输出完整 transcript，除非你手动设置限制）
maxBytes：
- image：10MB
- audio：20MB
- video：50MB

规则：

如果媒体超过 maxBytes，该 model 会被跳过，并尝试下一个 model。
小于 1024 bytes 的 audio 文件会被视为空或损坏，并在 provider/CLI transcription 之前直接跳过。
如果 model 返回内容超过 maxChars，输出会被截断。
prompt 默认是简单的 “Describe the {media}.”，并附带 maxChars 指引（仅 image/video）。
如果 <capability>.enabled: true，但没有配置 models，OpenClaw 会尝试使用当前激活的 reply model，前提是它的 provider 支持该 capability。

自动检测 media understanding（默认）

如果 tools.media.<capability>.enabled 未被显式设置为 false，且你也没有配置 models，OpenClaw 会按以下顺序自动检测，并在找到第一个可用方案后停止：

本地 CLI（仅 audio；若已安装）
- sherpa-onnx-offline（要求设置 SHERPA_ONNX_MODEL_DIR，其中包含 encoder/decoder/joiner/tokens）
- whisper-cli（whisper-cpp；使用 WHISPER_CPP_MODEL 或内置 tiny model）
- whisper（Python CLI；会自动下载 models）
Gemini CLI（gemini），使用 read_many_files
Provider keys
- Audio：OpenAI → Groq → Deepgram → Google
- Image：OpenAI → Anthropic → Google → MiniMax
- Video：Google

如需关闭自动检测，可设置：

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

注意：二进制检测在 macOS/Linux/Windows 上是 best-effort；请确保 CLI 已加入 PATH（我们会展开 ~），或者显式配置一个带完整命令路径的 CLI model。

代理环境支持（provider models）

启用基于 provider 的 audio 和 video media understanding 时，OpenClaw 会遵循标准的出站代理环境变量，用于 provider HTTP 调用：

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

如果未设置任何 proxy 环境变量，media understanding 会直接出网。如果 proxy 值格式错误，OpenClaw 会记录 warning，并回退为 direct fetch。

Capabilities（可选）

如果你设置了 capabilities，该 entry 只会用于这些媒体类型。对于 shared lists，OpenClaw 可以推断默认值：

openai、anthropic、minimax：image
moonshot：image + video
google（Gemini API）：image + audio + video
mistral：audio
zai：image
groq：audio
deepgram：audio

对于 CLI entries，建议显式设置 capabilities，以避免意外匹配。如果省略 capabilities，该 entry 会默认适用于它所在的列表。

Provider 支持矩阵（OpenClaw integrations）

Capability	Provider integration	说明
Image	OpenAI、Anthropic、Google、MiniMax、Moonshot、Z.AI	Vendor plugins 会把 image support 注册到 core media understanding。
Audio	OpenAI、Groq、Deepgram、Google、Mistral	provider transcription（Whisper/Deepgram/Gemini/Voxtral）。
Video	Google、Moonshot	通过 vendor plugins 提供 provider video understanding。

Model 选择建议

当质量和安全性重要时，优先为每种 media capability 选择当前最强、最新一代的 model。
对于处理不可信输入且启用了 tool 的 agents，避免使用较旧或较弱的 media models。
每种 capability 至少保留一个 fallback，以提高可用性（高质量 model + 更快/更便宜的 model）。
CLI fallbacks（whisper-cli、whisper、gemini）在 provider APIs 不可用时很有帮助。
parakeet-mlx 说明：配合 --output-dir 使用时，如果输出格式为 txt（或未指定），OpenClaw 会读取 <output-dir>/<media-basename>.txt；非 txt 格式则回退到 stdout。

附件策略

每个 capability 下的 attachments 用于控制要处理哪些附件：

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

当 mode: "all" 时，输出会标记为 [Image 1/2]、[Audio 2/2] 等。

配置示例

1）共享 models 列表 + overrides

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", 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,
      },
    },
  },
}

2）仅启用 Audio + Video（关闭 image）

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

3）可选的 image understanding

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { 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.",
            ],
          },
        ],
      },
    },
  },
}

4）多模态单一 entry（显式 capabilities）

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

状态输出

当 media understanding 运行时，/status 会包含一行简要摘要：

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

这会显示各 capability 的结果，以及实际选用的 provider/model（如适用）。

说明

Understanding 是 best-effort 的。即使出错，也不会阻塞 replies。
即使 understanding 被禁用，attachments 仍然会传递给 models。
可以使用 scope 来限制 understanding 的运行范围（例如只在 DMs 中启用）。

OpenClaw 开发文档 - 帮助手册 - 教程

多媒体内容理解（入站）