Media Understanding (Inbound) — 17-01-2026

OpenClaw có thể tóm tắt media đầu vào (image/audio/video) trước khi reply pipeline chạy. Nó tự động phát hiện khi có local tools hoặc provider keys, và có thể tắt hoặc tùy chỉnh. Nếu tắt understanding, models vẫn nhận file/URL gốc như bình thường.

Mục tiêu

  • Tùy chọn: tiền xử lý media đầu vào thành văn bản ngắn để routing nhanh hơn + phân tích lệnh tốt hơn.
  • Giữ nguyên việc gửi media gốc cho model (luôn luôn).
  • Hỗ trợ provider APIs và CLI dự phòng.
  • Cho phép nhiều models với fallback theo thứ tự (lỗi/kích thước/timeout).

Cách hoạt động tổng quan

  1. Thu thập attachments đầu vào (MediaPaths, MediaUrls, MediaTypes).
  2. Với mỗi capability được bật (image/audio/video), chọn attachments theo policy (mặc định: first).
  3. Chọn model entry đủ điều kiện đầu tiên (kích thước + capability + auth).
  4. Nếu model thất bại hoặc media quá lớn, fallback sang entry tiếp theo.
  5. Khi thành công:
    • Body trở thành block [Image], [Audio], hoặc [Video].
    • Audio set {{Transcript}}; command parsing dùng caption text khi có, nếu không thì dùng transcript.
    • Captions được giữ lại dạng User text: bên trong block.

Nếu understanding thất bại hoặc bị tắt, reply flow vẫn tiếp tục với body + attachments gốc.

Tổng quan config

tools.media hỗ trợ shared models cộng với overrides theo từng capability:

  • tools.media.models: danh sách model chung (dùng capabilities để giới hạn).
  • tools.media.image / tools.media.audio / tools.media.video:
    • defaults (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • provider overrides (baseUrl, headers, providerOptions)
    • Deepgram audio options qua tools.media.audio.providerOptions.deepgram
    • tùy chọn danh sách models riêng cho từng capability (ưu tiên trước shared models)
    • attachments policy (mode, maxAttachments, prefer)
    • scope (tùy chọn giới hạn theo channel/chatType/session key)
  • tools.media.concurrency: số capability chạy đồng thời tối đa (mặc định 2).
{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

Model entries

Mỗi entry trong models[] có thể là provider hoặc 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 cũng có thể dùng:

  • {{MediaDir}} (thư mục chứa media file)
  • {{OutputDir}} (thư mục tạm được tạo cho lần chạy này)
  • {{OutputBase}} (đường dẫn base file tạm, không có extension)

Defaults và giới hạn

Defaults được khuyên dùng:

  • maxChars: 500 cho image/video (ngắn, thân thiện với command)
  • maxChars: không set cho audio (transcript đầy đủ trừ khi các bạn set giới hạn)
  • maxBytes:
    • image: 10MB
    • audio: 20MB
    • video: 50MB

Quy tắc:

  • Nếu media vượt quá maxBytes, model đó bị bỏ qua và thử model tiếp theo.
  • Nếu model trả về nhiều hơn maxChars, output sẽ bị cắt bớt.
  • prompt mặc định là “Describe the {media}.” đơn giản cộng với hướng dẫn maxChars (chỉ image/video).
  • Nếu <capability>.enabled: true nhưng không config models, OpenClaw thử active reply model khi provider của nó hỗ trợ capability đó.

Auto-detect media understanding (mặc định)

Nếu tools.media.<capability>.enabled không được set thành false và các bạn chưa config models, OpenClaw tự động phát hiện theo thứ tự này và dừng ở option đầu tiên hoạt động được:

  1. Local CLIs (chỉ audio; nếu đã cài)
    • sherpa-onnx-offline (cần SHERPA_ONNX_MODEL_DIR với encoder/decoder/joiner/tokens)
    • whisper-cli (whisper-cpp; dùng WHISPER_CPP_MODEL hoặc tiny model đi kèm)
    • whisper (Python CLI; tự động download models)
  2. Gemini CLI (gemini) dùng read_many_files
  3. Provider keys
    • Audio: OpenAI → Groq → Deepgram → Google
    • Image: OpenAI → Anthropic → Google → MiniMax
    • Video: Google

Để tắt auto-detection, set:

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

Lưu ý: Binary detection là best-effort trên macOS/Linux/Windows; đảm bảo CLI nằm trong PATH (mình expand ~), hoặc set một CLI model rõ ràng với đường dẫn lệnh đầy đủ.

Capabilities (tùy chọn)

Nếu các bạn set capabilities, entry đó chỉ chạy cho các loại media đó. Với shared lists, OpenClaw có thể suy ra defaults:

  • openai, anthropic, minimax: image
  • google (Gemini API): image + audio + video
  • groq: audio
  • deepgram: audio

Với CLI entries, set capabilities rõ ràng để tránh match không mong muốn. Nếu bỏ qua capabilities, entry đó đủ điều kiện cho list mà nó xuất hiện.

Provider support matrix (OpenClaw integrations)

CapabilityProvider integrationNotes
ImageOpenAI / Anthropic / Google / others via pi-aiBất kỳ model hỗ trợ image nào trong registry.
AudioOpenAI, Groq, Deepgram, GoogleProvider transcription (Whisper/Deepgram/Gemini).
VideoGoogle (Gemini API)Provider video understanding.

Providers được khuyên dùng

Image

  • Ưu tiên active model của các bạn nếu nó hỗ trợ images.
  • Defaults tốt: openai/gpt-5.2, anthropic/claude-opus-4-5, google/gemini-3-pro-preview.

Audio

  • openai/gpt-4o-mini-transcribe, groq/whisper-large-v3-turbo, hoặc deepgram/nova-3.
  • CLI fallback: whisper-cli (whisper-cpp) hoặc whisper.
  • Deepgram setup: Deepgram (audio transcription).

Video

  • google/gemini-3-flash-preview (nhanh), google/gemini-3-pro-preview (chi tiết hơn).
  • CLI fallback: gemini CLI (hỗ trợ read_file trên video/audio).

Attachment policy

attachments theo từng capability kiểm soát attachments nào được xử lý:

  • mode: first (mặc định) hoặc all
  • maxAttachments: giới hạn số lượng được xử lý (mặc định 1)
  • prefer: first, last, path, url

Khi mode: "all", outputs được gắn nhãn [Image 1/2], [Audio 2/2], v.v.

Ví dụ config

1) Shared models list + 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) Chỉ Audio + Video (tắt 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 tùy chọn

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-5" },
          {
            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) Multi-modal single entry (capabilities rõ ràng)

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

Status output

Khi media understanding chạy, /status bao gồm một dòng tóm tắt ngắn:

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

Dòng này hiển thị kết quả theo từng capability và provider/model được chọn khi có.

Lưu ý

  • Understanding là best-effort. Lỗi không chặn replies.
  • Attachments vẫn được gửi cho models ngay cả khi understanding bị tắt.
  • Dùng scope để giới hạn nơi understanding chạy (ví dụ chỉ DMs).

Tài liệu liên quan