媒体理解——入站（2026-01-17）

OpenClaw 可在回复流程运行前对入站媒体（图片/音频/视频）进行摘要。它会自动检测本地工具或 provider 密钥是否可用，也可以禁用或自定义。若理解功能关闭，模型仍会照常收到原始文件/URL。

厂商特定媒体行为由厂商插件注册，OpenClaw 核心负责共享的 tools.media 配置、回退顺序和回复流程集成。

目标

可选：将入站媒体预处理为简短文本，加快路由速度并改善命令解析。
始终将原始媒体传递给模型（不变）。
支持 provider API 和 CLI 回退。
允许多个模型按顺序回退（错误/大小/超时）。

整体行为

收集入站附件（MediaPaths、MediaUrls、MediaTypes）。
对每个启用的功能（image/audio/video），按策略选择附件（默认：第一个）。
选择第一个符合条件的模型条目（大小 + 功能 + 认证）。
若模型失败或媒体过大，回退到下一个条目。
成功后：
- Body 变为 [Image]、[Audio] 或 [Video] 块。
- 音频设置；有标题时用标题解析命令，否则用转录内容。
- 标题保留为块内的 User text: 文本。

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

配置概览

tools.media 支持共享模型加各功能独立覆盖：

tools.media.models：共享模型列表（用 capabilities 限定适用功能）。
tools.media.image / tools.media.audio / tools.media.video：
- 默认值（prompt、maxChars、maxBytes、timeoutSeconds、language）
- provider 覆盖（baseUrl、headers、providerOptions）
- Deepgram 音频选项（tools.media.audio.providerOptions.deepgram）
- 音频转录回显控制（echoTranscript，默认 false；echoFormat）
- 可选的每功能 models 列表（优先于共享模型）
- attachments 策略（mode、maxAttachments、prefer）
- scope（可选的频道/chatType/会话键限定）
tools.media.concurrency：最大并发功能运行数（默认 2）。

json5

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

模型条目

每个 models[] 条目可以是 provider 或 CLI 类型：

json5

{
  type: "provider", // 省略时默认
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // 可选，用于多模态条目
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

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 模板还可使用：

（媒体文件所在目录）
（为本次运行创建的临时目录）
（临时文件基础路径，不含扩展名）

默认值与限制

推荐默认值：

maxChars：图片/视频为 500（简短，便于命令解析）
maxChars：音频不设置（全量转录，除非需要限制）
maxBytes：
- 图片：10 MB
- 音频：20 MB
- 视频：50 MB

规则：

若媒体超过 maxBytes，跳过该模型，尝试下一个。
小于 1024 字节 的音频文件被视为空/损坏，在 provider/CLI 转录前跳过。
模型返回内容超过 maxChars 时，输出被截断。
prompt 默认为简单的"描述此{媒体}。"加 maxChars 说明（仅图片/视频）。
若 <capability>.enabled: true 但未配置任何模型，且活跃回复模型的 provider 支持该功能，OpenClaw 会尝试使用当前回复模型。

自动检测媒体理解（默认）

若 tools.media.<capability>.enabled 未设为 false 且未配置模型，OpenClaw 按以下顺序自动检测并在第一个可用选项处停止：

本地 CLI（仅音频；如已安装）
- sherpa-onnx-offline（需要 SHERPA_ONNX_MODEL_DIR，含 encoder/decoder/joiner/tokens）
- whisper-cli（whisper-cpp；使用 WHISPER_CPP_MODEL 或内置 tiny 模型）
- whisper（Python CLI；自动下载模型）
Gemini CLI（gemini，使用 read_many_files）
Provider 密钥
- 音频：OpenAI → Groq → Deepgram → Google
- 图片：OpenAI → Anthropic → Google → MiniMax
- 视频：Google

要禁用自动检测，设置：

json5

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

注意：二进制检测在 macOS/Linux/Windows 上属于尽力而为；请确保 CLI 在 PATH 中（支持 ~ 扩展），或设置带完整路径的显式 CLI 模型条目。

代理环境支持（provider 模型）

启用基于 provider 的音频和视频媒体理解时，OpenClaw 会遵循标准出站代理环境变量：

HTTPS_PROXY
HTTP_PROXY
https_proxy
http_proxy

未设置代理时，媒体理解使用直连。代理值格式错误时，OpenClaw 记录警告并回退到直连。

功能（capabilities，可选）

设置 capabilities 后，条目仅对指定媒体类型生效。对于共享列表，OpenClaw 可推断默认值：

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

CLI 条目请显式设置 capabilities 以避免意外匹配。省略 capabilities 时，条目适用于其所在列表的所有类型。

Provider 支持矩阵（OpenClaw 集成）

功能	Provider 集成	备注
图片	OpenAI、Anthropic、Google、MiniMax、Moonshot、Z.AI	厂商插件针对核心媒体理解注册图片支持。
音频	OpenAI、Groq、Deepgram、Google、Mistral	Provider 转录（Whisper/Deepgram/Gemini/Voxtral）。
视频	Google、Moonshot	厂商插件提供 provider 视频理解。

模型选型建议

对质量和安全性要求高时，优先为每个媒体功能选择最强的最新模型。
处理不可信输入的工具 agent，避免使用较旧/较弱的媒体模型。
每个功能至少保留一个回退以保证可用性（高质量模型 + 更快/更便宜的模型）。
CLI 回退（whisper-cli、whisper、gemini）在 provider API 不可用时很有用。
parakeet-mlx 说明：使用 --output-dir 时，若输出格式为 txt（或未指定），OpenClaw 读取 <output-dir>/<media-basename>.txt；非 txt 格式回退到 stdout。

附件策略

每个功能的 attachments 控制处理哪些附件：

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

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

配置示例

1) 共享模型列表 + 覆盖

json5

{
  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) 仅音频 + 视频（图片关闭）

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

3) 可选图片理解

json5

{
  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) 多模态单条目（显式 capabilities）

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 包含一行简短摘要：

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

显示各功能的处理结果及选用的 provider/model。

注意事项

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

媒体理解——入站（2026-01-17） ​

目标 ​

整体行为 ​

配置概览 ​

模型条目 ​

默认值与限制 ​

自动检测媒体理解（默认） ​

代理环境支持（provider 模型） ​

功能（capabilities，可选） ​

Provider 支持矩阵（OpenClaw 集成） ​

模型选型建议 ​

附件策略 ​

配置示例 ​

1) 共享模型列表 + 覆盖 ​

2) 仅音频 + 视频（图片关闭） ​

3) 可选图片理解 ​

4) 多模态单条目（显式 capabilities） ​

状态输出 ​

注意事项 ​

相关文档 ​

媒体理解——入站（2026-01-17）

目标

整体行为

配置概览

模型条目

默认值与限制

自动检测媒体理解（默认）

代理环境支持（provider 模型）

功能（capabilities，可选）

Provider 支持矩阵（OpenClaw 集成）

模型选型建议

附件策略

配置示例

1) 共享模型列表 + 覆盖

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

3) 可选图片理解

4) 多模态单条目（显式 capabilities）

状态输出

注意事项

相关文档