​

Media Understanding - Masuk (2026-01-17)

​

Tujuan

• Opsional: mencerna media masuk menjadi teks singkat sebelumnya untuk routing yang lebih cepat + parsing perintah yang lebih baik.
• Mempertahankan pengiriman media asli ke model (selalu).
• Mendukung API provider dan fallback CLI.
• Memungkinkan beberapa model dengan fallback berurutan (error/ukuran/timeout).

​

Perilaku tingkat tinggi

1. Kumpulkan lampiran masuk (MediaPaths, MediaUrls, MediaTypes).
2. Untuk setiap capability yang diaktifkan (gambar/audio/video), pilih lampiran sesuai kebijakan (default: pertama).
3. Pilih entri model pertama yang memenuhi syarat (ukuran + capability + auth).
4. Jika model gagal atau media terlalu besar, fallback ke entri berikutnya.
5. Jika berhasil:
   • Body menjadi blok [Image], [Audio], atau [Video].
   • Audio menetapkan {{Transcript}}; parsing perintah menggunakan teks caption jika ada, jika tidak, menggunakan transkrip.
   • Caption dipertahankan sebagai User text: di dalam blok.

​

Ringkasan konfigurasi

• tools.media.models: daftar model bersama (gunakan capabilities untuk gating).
• tools.media.image / tools.media.audio / tools.media.video:
  • default (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • override provider (baseUrl, headers, providerOptions)
  • opsi audio Deepgram melalui tools.media.audio.providerOptions.deepgram
  • kontrol echo transkrip audio (echoTranscript, default false; echoFormat)
  • daftar models per capability opsional (diprioritaskan sebelum model bersama)
  • kebijakan attachments (mode, maxAttachments, prefer)
  • scope (gating opsional berdasarkan channel/chatType/kunci sesi)
• tools.media.concurrency: jumlah maksimum eksekusi capability bersamaan (default 2).

{
  tools: {
    media: {
      models: [
        /* daftar bersama */
      ],
      image: {
        /* override opsional */
      },
      audio: {
        /* override opsional */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* override opsional */
      },
    },
  },
}

​

Entri model

{
  type: "provider", // default jika dihilangkan
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // opsional, digunakan untuk entri multi-modal
  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"],
}

• {{MediaDir}} (direktori yang berisi file media)
• {{OutputDir}} (direktori scratch yang dibuat untuk eksekusi ini)
• {{OutputBase}} (jalur dasar file scratch, tanpa ekstensi)

​

Default dan batas

• maxChars: 500 untuk gambar/video (singkat, ramah perintah)
• maxChars: tidak disetel untuk audio (transkrip penuh kecuali Anda menetapkan batas)
• maxBytes:
  • gambar: 10MB
  • audio: 20MB
  • video: 50MB

• Jika media melebihi maxBytes, model tersebut dilewati dan model berikutnya dicoba.
• File audio yang lebih kecil dari 1024 byte diperlakukan sebagai kosong/rusak dan dilewati sebelum transkripsi provider/CLI.
• Jika model mengembalikan lebih dari maxChars, output dipangkas.
• prompt secara default berupa “Describe the .” sederhana plus panduan maxChars (hanya gambar/video).
• Jika model gambar utama aktif sudah mendukung vision secara native, OpenClaw melewati blok ringkasan [Image] dan sebagai gantinya meneruskan gambar asli ke dalam model.
• Jika <capability>.enabled: true tetapi tidak ada model yang dikonfigurasi, OpenClaw mencoba model balasan aktif saat provider-nya mendukung capability tersebut.

​

Deteksi otomatis media understanding (default)

1. Model balasan aktif saat provider-nya mendukung capability tersebut.
2. Ref primary/fallback agents.defaults.imageModel (hanya gambar).
3. CLI lokal (hanya audio; jika terpasang)
   • sherpa-onnx-offline (memerlukan SHERPA_ONNX_MODEL_DIR dengan encoder/decoder/joiner/tokens)
   • whisper-cli (whisper-cpp; menggunakan WHISPER_CPP_MODEL atau model tiny bawaan)
   • whisper (CLI Python; mengunduh model secara otomatis)
4. Gemini CLI (gemini) menggunakan read_many_files
5. Auth provider
   • Entri models.providers.* yang dikonfigurasi dan mendukung capability tersebut dicoba sebelum urutan fallback bawaan.
   • Provider konfigurasi khusus gambar dengan model yang mendukung gambar akan terdaftar otomatis untuk media understanding bahkan saat mereka bukan plugin vendor bawaan.
   • Urutan fallback bawaan:
     • Audio: OpenAI → Groq → Deepgram → Google → Mistral
     • Gambar: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • Video: Google → Qwen → Moonshot

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

​

Dukungan environment proxy (model provider)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Capabilities (opsional)

• openai, anthropic, minimax: image
• minimax-portal: image
• moonshot: image + video
• openrouter: image
• google (Gemini API): image + audio + video
• qwen: image + video
• mistral: audio
• zai: image
• groq: audio
• deepgram: audio
• Katalog models.providers.<id>.models[] apa pun dengan model yang mendukung gambar: image

​

Matriks dukungan provider (integrasi OpenClaw)

• Media understanding gambar minimax dan minimax-portal berasal dari provider media MiniMax-VL-01 milik plugin.
• Katalog teks MiniMax bawaan tetap dimulai sebagai teks saja; entri models.providers.minimax eksplisit mematerialkan ref chat M2.7 yang mendukung gambar.

​

Panduan pemilihan model

• Pilih model generasi terbaru terkuat yang tersedia untuk setiap capability media saat kualitas dan keamanan penting.
• Untuk agen dengan alat yang menangani input tidak tepercaya, hindari model media yang lebih lama/lemah.
• Simpan setidaknya satu fallback per capability untuk ketersediaan (model berkualitas + model lebih cepat/lebih murah).
• Fallback CLI (whisper-cli, whisper, gemini) berguna saat API provider tidak tersedia.
• Catatan parakeet-mlx: dengan --output-dir, OpenClaw membaca <output-dir>/<media-basename>.txt saat format output adalah txt (atau tidak ditentukan); format selain txt akan fallback ke stdout.

​

Kebijakan lampiran

• mode: first (default) atau all
• maxAttachments: membatasi jumlah yang diproses (default 1)
• prefer: first, last, path, url

• Teks file yang diekstrak dibungkus sebagai konten eksternal tidak tepercaya sebelum ditambahkan ke prompt media.
• Blok yang disuntikkan menggunakan penanda batas eksplisit seperti <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> dan menyertakan baris metadata Source: External.
• Jalur ekstraksi lampiran ini sengaja menghilangkan banner panjang SECURITY NOTICE: agar prompt media tidak membengkak; penanda batas dan metadata tetap dipertahankan.
• Jika file tidak memiliki teks yang dapat diekstrak, OpenClaw menyuntikkan [No extractable text].
• Jika PDF fallback ke gambar halaman hasil render di jalur ini, prompt media tetap menyimpan placeholder [PDF content rendered to images; images not forwarded to model] karena langkah ekstraksi lampiran ini meneruskan blok teks, bukan gambar PDF hasil render.

​

Contoh konfigurasi

​

1) Daftar model bersama + override

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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) Hanya audio + video (gambar nonaktif)

{
  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 opsional

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { 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) Entri tunggal multi-modal (capabilities eksplisit)

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

​

Output status

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

​

Catatan

• Understanding bersifat best-effort. Error tidak memblokir balasan.
• Lampiran tetap diteruskan ke model bahkan saat understanding dinonaktifkan.
• Gunakan scope untuk membatasi tempat understanding berjalan (misalnya hanya DM).

​

Dokumentasi terkait

• Configuration
• Image & Media Support