Pemahaman media

OpenClaw dapat merangkum media masuk (gambar/audio/video) sebelum alur balasan berjalan. OpenClaw mendeteksi otomatis saat alat lokal atau kunci penyedia tersedia, dan dapat dinonaktifkan atau disesuaikan. Jika pemahaman dinonaktifkan, 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 alur balasan.

Tujuan

Opsional: cerna awal media masuk menjadi teks pendek 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 (kesalahan/ukuran/batas waktu).

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 menggunakan transkrip.
Keterangan dipertahankan sebagai User text: di dalam blok.

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

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 echo 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 proses kapabilitas serentak (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"],
}

Templat 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)

Default dan batas

Default yang direkomendasikan:

maxChars: 500 untuk gambar/video (singkat, ramah perintah)
maxChars: tidak disetel untuk audio (transkrip lengkap 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 dianggap 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, keluaran dipangkas.
prompt default ke “Describe the .” sederhana ditambah 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 ref media://inbound/* yang dioffload 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 berkapabilitas gambar secara langsung, termasuk ref Ollama seperti ollama/qwen2.5vl:7b.
Jika <capability>.enabled: true tetapi tidak ada model yang dikonfigurasi, OpenClaw mencoba model balasan aktif saat 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 saat penyedianya mendukung kapabilitas tersebut.

agents.defaults.imageModel

Ref utama/fallback agents.defaults.imageModel (hanya gambar). Lebih pilih ref provider/model. Ref polos dikualifikasi dari entri model penyedia berkapabilitas gambar yang dikonfigurasi hanya jika 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 berkapabilitas gambar didaftarkan 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 upaya-terbaik lintas macOS/Linux/Windows; pastikan CLI ada di PATH (kami memperluas ~), atau setel model CLI eksplisit dengan path perintah lengkap.

Dukungan lingkungan proxy (model penyedia)

Saat 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 env proxy yang disetel, pemahaman media menggunakan egress langsung. Jika nilai proxy salah format, OpenClaw mencatat peringatan dan fallback ke fetch langsung.

Kapabilitas (opsional)

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

openai, anthropic, minimax: gambar
minimax-portal: gambar
moonshot: gambar + video
openrouter: gambar + audio
google (Gemini API): 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 berkapabilitas gambar: gambar

Untuk entri CLI, setel capabilities secara eksplisit untuk menghindari kecocokan yang mengejutkan. Jika Anda menghilangkan capabilities, entri memenuhi syarat untuk daftar tempat entri itu 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-codex/` menggunakan plumbing penyedia OAuth; `codex/` menggunakan giliran Codex app-server terbatas; MiniMax dan MiniMax OAuth sama-sama menggunakan `MiniMax-VL-01`; penyedia konfigurasi berkapabilitas gambar didaftarkan 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 dan minimax-portal berasal dari penyedia media MiniMax-VL-01 milik plugin.
Katalog teks MiniMax bawaan tetap dimulai sebagai hanya teks; entri eksplisit models.providers.minimax mematerialisasi ref chat M2.7 berkapabilitas gambar.

Panduan pemilihan model

Lebih pilih model generasi terbaru terkuat yang tersedia untuk setiap kapabilitas media saat kualitas dan keamanan penting.
Untuk agen berkemampuan alat yang menangani input tidak tepercaya, hindari model media yang lebih lama/lebih lemah.
Pertahankan setidaknya satu fallback per kapabilitas untuk ketersediaan (model berkualitas + model 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 kapabilitas mengontrol lampiran mana yang diproses:

mode

"first" | "all"

default:"first"

Apakah akan memproses lampiran terpilih pertama atau semuanya.

maxAttachments

number

default:"1"

Batasi jumlah yang diproses.

prefer

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

Preferensi pemilihan di antara lampiran kandidat.

Saat mode: "all", keluaran diberi label [Image 1/2], [Audio 2/2], dll.

File-attachment extraction behavior

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 panjang SECURITY NOTICE: agar prompt media tidak membengkak; 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, prompt media mempertahankan placeholder [PDF content rendered to images; images not forwarded to model] karena langkah ekstraksi lampiran ini meneruskan blok teks, bukan gambar PDF yang dirender.

Contoh konfigurasi

Shared models + overrides
Audio + video only
Image-only
Multi-modal single entry

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

Keluaran status

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

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

Ini menampilkan hasil per kapabilitas 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).

Gateway

Remote access

Security

Nodes and media

Web interfaces

Tujuan

Perilaku tingkat tinggi

Ikhtisar konfigurasi

Entri model

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 konfigurasi

Keluaran status

Catatan

Terkait

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Tujuan

​Perilaku tingkat tinggi

​Ikhtisar konfigurasi

​Entri model

​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 konfigurasi

​Keluaran status

​Catatan

​Terkait

Tujuan

Perilaku tingkat tinggi

Ikhtisar konfigurasi

Entri model

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 konfigurasi

Keluaran status

Catatan

Terkait