Pemahaman media - OpenClaw

OpenClaw dapat meringkas media masuk (gambar/audio/video) sebelum pipeline balasan berjalan. Ini mendeteksi otomatis ketika alat lokal atau kunci penyedia tersedia, dan dapat dinonaktifkan atau disesuaikan. Jika pemahaman nonaktif, model tetap menerima file/URL asli seperti biasa. Perilaku media khusus vendor didaftarkan oleh Plugin vendor, sementara inti OpenClaw memiliki konfigurasi bersama tools.media, urutan fallback, dan integrasi pipeline balasan.

Tujuan

Opsional: pracerna media masuk menjadi teks singkat untuk perutean lebih cepat + parsing perintah yang lebih baik.
Pertahankan pengiriman media asli ke model (selalu).
Mendukung API penyedia dan fallback CLI.
Mengizinkan beberapa model dengan fallback berurutan (error/ukuran/timeout).

Perilaku tingkat tinggi

Collect attachments

Kumpulkan lampiran masuk (MediaPaths, MediaUrls, MediaTypes).

Select per-capability

Untuk setiap kapabilitas yang diaktifkan (gambar/audio/video), pilih lampiran sesuai kebijakan (default: pertama).

Choose model

Pilih entri model pertama yang memenuhi syarat (ukuran + kapabilitas + auth).

Fallback on failure

Jika model gagal atau media terlalu besar, fallback ke entri berikutnya.

Apply success block

Saat berhasil:

Body menjadi blok [Image], [Audio], atau [Video].
Audio menetapkan {{Transcript}}; parsing perintah menggunakan teks keterangan jika ada, jika tidak transkrip.
Keterangan dipertahankan sebagai User text: di dalam blok.

Jika pemahaman gagal atau dinonaktifkan, alur balasan berlanjut dengan body + lampiran asli.

Ikhtisar konfigurasi

tools.media mendukung model bersama plus override per kapabilitas:

Top-level keys

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

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

Entri model

Setiap entri models[] dapat berupa penyedia atau CLI:

Provider entry
CLI entry

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.5",
  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"],
}

Template CLI juga dapat menggunakan:

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

Kredensial penyedia (`apiKey`)

Pemahaman media penyedia menggunakan resolusi auth penyedia yang sama seperti panggilan model normal: profil auth, variabel lingkungan, lalu models.providers.<providerId>.apiKey. Entri tools.media.*.models[] tidak menerima field apiKey inline. Nilai provider dalam entri model media, seperti openai atau moonshot, harus memiliki kredensial yang tersedia melalui salah satu sumber auth penyedia standar. Contoh minimal:

{
  models: {
    providers: {
      openai: { apiKey: "<OPENAI_API_KEY>" },
      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },
    },
  },
}

Untuk referensi auth penyedia lengkap, termasuk profil, variabel lingkungan, dan URL dasar kustom, lihat Alat dan penyedia kustom.

Default dan batas

Default yang direkomendasikan:

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

Rules

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 penyedia/CLI; konteks balasan masuk menerima transkrip placeholder deterministik agar agen tahu catatan tersebut terlalu kecil.
Jika model mengembalikan lebih dari maxChars, output dipangkas.
prompt default ke “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 meneruskan gambar asli ke model.
Jika model utama Gateway/WebChat hanya teks, lampiran gambar dipertahankan sebagai referensi media://inbound/* yang di-offload sehingga alat gambar/PDF atau model gambar yang dikonfigurasi tetap dapat memeriksanya alih-alih kehilangan lampiran.
Permintaan eksplisit openclaw infer image describe --model <provider/model> berbeda: permintaan tersebut menjalankan penyedia/model yang mampu menangani gambar secara langsung, termasuk referensi Ollama seperti ollama/qwen2.5vl:7b.
Jika <capability>.enabled: true tetapi tidak ada model yang dikonfigurasi, OpenClaw mencoba model balasan aktif ketika penyedianya mendukung kapabilitas tersebut.

Deteksi otomatis pemahaman media (default)

Jika tools.media.<capability>.enabled tidak disetel ke false dan Anda belum mengonfigurasi model, OpenClaw mendeteksi otomatis dalam urutan ini dan berhenti pada opsi pertama yang berfungsi:

Active reply model

Model balasan aktif ketika penyedianya mendukung kapabilitas tersebut.

agents.defaults.imageModel

Referensi primer/fallback agents.defaults.imageModel (hanya gambar). Utamakan referensi provider/model. Referensi polos dikualifikasi dari entri model penyedia yang dikonfigurasi dan mampu menangani gambar hanya ketika kecocokannya unik.

Local CLIs (audio only)

CLI lokal (jika terinstal):

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)

Gemini CLI

gemini menggunakan read_many_files.

Provider auth

Entri models.providers.* yang dikonfigurasi dan mendukung kapabilitas dicoba sebelum urutan fallback bawaan.
Penyedia konfigurasi khusus gambar dengan model yang mampu menangani gambar mendaftar otomatis untuk pemahaman media meskipun bukan Plugin vendor bawaan.
Pemahaman gambar Ollama tersedia saat dipilih secara eksplisit, misalnya melalui agents.defaults.imageModel atau openclaw infer image describe --model ollama/<vision-model>.

Urutan fallback bawaan:

Audio: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
Gambar: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
Video: Google → Qwen → Moonshot

Untuk menonaktifkan deteksi otomatis, setel:

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

Deteksi biner bersifat best-effort di macOS/Linux/Windows; pastikan CLI ada di PATH (kami memperluas ~), atau setel model CLI eksplisit dengan path perintah lengkap.

Dukungan lingkungan proxy (model penyedia)

Ketika pemahaman media audio dan video berbasis penyedia diaktifkan, OpenClaw menghormati variabel lingkungan proxy keluar standar untuk panggilan HTTP penyedia:

HTTPS_PROXY
HTTP_PROXY
ALL_PROXY
https_proxy
http_proxy
all_proxy

Jika tidak ada variabel lingkungan proxy yang disetel, pemahaman media menggunakan egress langsung. Jika nilai proxy salah bentuk, OpenClaw mencatat peringatan dan fallback ke pengambilan langsung.

Kapabilitas (opsional)

Jika Anda menetapkan capabilities, entri hanya berjalan untuk tipe media tersebut. Untuk daftar bersama, OpenClaw dapat menyimpulkan default:

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

Untuk entri CLI, tetapkan capabilities secara eksplisit untuk menghindari kecocokan yang mengejutkan. Jika Anda menghilangkan capabilities, entri memenuhi syarat untuk daftar tempat entri tersebut muncul.

Matriks dukungan penyedia (integrasi OpenClaw)

Kapabilitas	Integrasi penyedia	Catatan
Gambar	OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, penyedia konfigurasi	Plugin vendor mendaftarkan dukungan gambar; `openai/` dapat menggunakan perutean kunci API atau Codex OAuth; `codex/` menggunakan giliran Codex app-server terbatas; MiniMax dan MiniMax OAuth sama-sama menggunakan `MiniMax-VL-01`; penyedia konfigurasi yang mampu menangani gambar mendaftar otomatis.
Audio	OpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistral	Transkripsi penyedia (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
Video	Google, Qwen, Moonshot	Pemahaman video penyedia melalui Plugin vendor; pemahaman video Qwen menggunakan endpoint Standard DashScope.

Catatan MiniMax

Pemahaman gambar minimax, minimax-cn, minimax-portal, dan minimax-portal-cn berasal dari penyedia media MiniMax-VL-01 milik plugin.
Perutean gambar otomatis tetap menggunakan MiniMax-VL-01 meskipun metadata chat MiniMax M2.x lama mengklaim input gambar.

Panduan pemilihan model

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

Kebijakan lampiran

attachments per kemampuan mengontrol lampiran mana yang diproses:

mode

"first" | "all"

default:"first"

Apakah memproses lampiran pertama yang dipilih atau semuanya.

maxAttachments

number

default:"1"

Batasi jumlah yang diproses.

prefer

"first" | "last" | "path" | "url"

Preferensi pemilihan di antara kandidat lampiran.

Saat mode: "all", output diberi label [Image 1/2], [Audio 2/2], dan seterusnya.

Perilaku ekstraksi lampiran file

Teks file yang diekstrak dibungkus sebagai konten eksternal tidak tepercaya sebelum ditambahkan ke prompt media.
Blok yang disisipkan 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 SECURITY NOTICE: yang panjang untuk menghindari pembesaran prompt media; penanda batas dan metadata tetap ada.
Jika file tidak memiliki teks yang dapat diekstrak, OpenClaw menyisipkan [No extractable text].
Jika PDF fallback ke gambar halaman yang dirender di jalur ini, OpenClaw meneruskan gambar halaman tersebut ke model balasan berkemampuan vision dan mempertahankan placeholder [PDF content rendered to images] di blok file.

Contoh config

Model bersama + override
Hanya audio + video
Hanya gambar
Satu entri multimodal

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

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

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

{
  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

Saat pemahaman media berjalan, /status menyertakan baris ringkasan singkat:

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

Ini menampilkan hasil per kemampuan dan penyedia/model yang dipilih jika berlaku.

Catatan

Pemahaman bersifat upaya terbaik. Error tidak memblokir balasan.
Lampiran tetap diteruskan ke model meskipun pemahaman dinonaktifkan.
Gunakan scope untuk membatasi tempat pemahaman berjalan (misalnya hanya DM).

​Tujuan

​Perilaku tingkat tinggi

​Ikhtisar konfigurasi

​Entri model

​Kredensial penyedia (apiKey)

​Default dan batas

​Deteksi otomatis pemahaman media (default)

​Dukungan lingkungan proxy (model penyedia)

​Kapabilitas (opsional)

​Matriks dukungan penyedia (integrasi OpenClaw)

​Panduan pemilihan model

​Kebijakan lampiran

​Contoh config

​Output status

​Catatan

​Terkait

Tujuan

Perilaku tingkat tinggi

Ikhtisar konfigurasi

Entri model

Kredensial penyedia (`apiKey`)

Default dan batas

Deteksi otomatis pemahaman media (default)

Dukungan lingkungan proxy (model penyedia)

Kapabilitas (opsional)

Matriks dukungan penyedia (integrasi OpenClaw)

Panduan pemilihan model

Kebijakan lampiran

Contoh config

Output status

Catatan

Terkait