Pemahaman media

OpenClaw dapat merangkum media masuk (gambar/audio/video) sebelum alur pemrosesan balasan berjalan, sehingga penguraian perintah dan perutean menggunakan teks pendek, bukan byte mentah. Pemahaman secara otomatis mendeteksi alat lokal atau kunci penyedia, atau Anda dapat mengonfigurasi model secara eksplisit. Media asli selalu dikirimkan ke model seperti biasa; ketika pemahaman gagal atau dinonaktifkan, alur balasan tetap berlanjut tanpa perubahan.

Plugin vendor mendaftarkan metadata kapabilitas (penyedia mana yang mendukung jenis media tertentu, model bawaan, prioritas). Inti OpenClaw memiliki konfigurasi bersama tools.media, urutan fallback, dan integrasi alur pemrosesan balasan.

Cara kerjanya

Konfigurasi

tools.media berisi daftar model bersama beserta penggantian per kapabilitas:

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

Kunci per kapabilitas (image/audio/video):

Opsi khusus Deepgram ditempatkan di bawah providerOptions.deepgram (kolom tingkat atas deepgram: { detectLanguage, punctuate, smartFormat } telah usang, tetapi masih dibaca).

Entri model

Setiap entri models[] merupakan entri penyedia (bawaan) atau entri CLI:

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared 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"],}

Kredensial penyedia

Pemahaman media oleh penyedia menggunakan resolusi autentikasi yang sama seperti panggilan model biasa: profil autentikasi, variabel lingkungan, kemudian models.providers.<providerId>.apiKey. Entri tools.media.*.models[] tidak menerima kolom apiKey sebaris.

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

Lihat Alat dan penyedia khusus untuk profil, variabel lingkungan, dan URL dasar khusus.

Aturan dan perilaku

• Media yang melebihi maxBytes melewati model tersebut dan mencoba model berikutnya.
• Berkas audio di bawah 1024 byte dianggap kosong/rusak dan dilewati sebelum transkripsi; agen menerima transkrip placeholder deterministik sebagai gantinya.
• Jika model gambar utama yang aktif sudah mendukung penglihatan secara native, OpenClaw melewati blok ringkasan [Image] dan meneruskan gambar asli langsung ke model. MiniMax merupakan pengecualian: minimax, minimax-cn, minimax-portal, dan minimax-portal-cn selalu merutekan pemahaman gambar melalui penyedia media MiniMax-VL-01 milik plugin, meskipun metadata obrolan MiniMax M2.x lama mengklaim dukungan masukan gambar (hanya MiniMax-M3 dan versi lebih baru yang dianggap mampu menangani penglihatan secara native).
• Jika model utama Gateway/WebChat hanya mendukung teks, lampiran gambar dipertahankan sebagai referensi media://inbound/* yang dialihkan penyimpanannya agar alat gambar/PDF atau model gambar yang dikonfigurasi tetap dapat memeriksanya, alih-alih kehilangan lampiran tersebut.
• Perintah eksplisit openclaw infer image describe --file <path> --model <provider/model> (alias: openclaw capability image describe) menjalankan penyedia/model berkemampuan gambar tersebut secara langsung, termasuk referensi Ollama seperti ollama/qwen2.5vl:7b ketika model berkemampuan gambar yang cocok dikonfigurasi di bawah models.providers.ollama.models[].
• Jika <capability>.enabled bukan false, tetapi tidak ada model yang dikonfigurasi, OpenClaw mencoba model balasan aktif ketika penyedianya mendukung kapabilitas tersebut.

Deteksi otomatis (bawaan)

Ketika tools.media.<capability>.enabled bukan false dan tidak ada model yang dikonfigurasi, OpenClaw mencoba opsi berikut secara berurutan dan berhenti pada opsi pertama yang berfungsi:

Untuk menonaktifkan deteksi otomatis bagi suatu kapabilitas:

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

Dukungan proksi (panggilan penyedia audio/video)

Pemahaman audio dan video berbasis penyedia mematuhi variabel lingkungan proksi keluar standar, termasuk aturan pengecualian NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Variabel huruf kecil lebih diprioritaskan daripada huruf besar. Jika tidak ada yang ditetapkan, pemahaman media menggunakan akses keluar langsung; jika nilai proksi tidak valid, OpenClaw mencatat peringatan dan beralih ke pengambilan langsung. Pemahaman gambar tidak melalui jalur proksi ini.

Kapabilitas

Tetapkan capabilities pada entri models[] untuk membatasinya ke jenis media tertentu. Untuk daftar bersama, OpenClaw menyimpulkan nilai bawaan per penyedia bawaan:

Untuk entri CLI, tetapkan capabilities secara eksplisit guna menghindari pencocokan yang tidak terduga; jika dihilangkan, entri tersebut memenuhi syarat untuk setiap daftar kemampuan tempat entri itu muncul.

Matriks dukungan penyedia

Panduan pemilihan model

• Utamakan model generasi terkini yang paling andal untuk setiap kemampuan media jika kualitas dan keamanan penting.
• Untuk agen yang mendukung alat dan menangani masukan tidak tepercaya, hindari model media yang lebih lama atau lebih lemah.
• Pertahankan setidaknya satu cadangan untuk setiap kemampuan demi ketersediaan (model berkualitas + model yang lebih cepat/murah).
• Cadangan CLI (whisper-cli, whisper, gemini) membantu ketika API penyedia tidak tersedia.
• Mode keluaran berkas yang diketahui bersifat otoritatif: berkas transkrip hasil inferensi yang kosong atau tidak ada tidak menghasilkan transkrip, alih-alih beralih ke keluaran kemajuan CLI.
• parakeet-mlx: gunakan --output-format txt (atau all) bersama --output-dir dan templat keluaran bawaan {filename}. Variabel lingkungan hulu PARAKEET_OUTPUT_FORMAT dan PARAKEET_OUTPUT_TEMPLATE juga dipatuhi. OpenClaw membaca <output-dir>/<media-basename>.txt; format bawaan srt, format lainnya, dan templat keluaran khusus tetap menggunakan stdout.

Kebijakan lampiran

attachments per kemampuan mengontrol lampiran mana yang diproses:

Ketika mode: "all", keluaran diberi label [Gambar 1/2], [Audio 2/2], dan seterusnya.

Ekstraksi lampiran berkas

• Teks berkas yang diekstrak dibungkus sebagai konten eksternal tidak tepercaya sebelum ditambahkan ke prompt media, menggunakan penanda batas seperti <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> beserta baris metadata Source: External.
• Jalur ini sengaja menghilangkan banner panjang SECURITY NOTICE: agar prompt media tetap ringkas; penanda batas dan metadata tetap diterapkan.
• Berkas tanpa teks yang dapat diekstrak mendapatkan [Tidak ada teks yang dapat diekstrak].
• Jika PDF beralih ke gambar halaman yang dirender, OpenClaw meneruskan gambar tersebut ke model balasan berkemampuan penglihatan dan mempertahankan placeholder [Konten PDF dirender menjadi gambar] dalam blok berkas.

Contoh konfigurasi

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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

Ketika pemahaman media berjalan, /status menyertakan baris ringkasan per kemampuan:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Untuk inventaris prapemeriksaan, jalankan openclaw capability audio providers. Baris lokal menampilkan pilihan cadangan lokal secara terpisah dari pemilihan penyedia global, kesiapan, serta bidang backend mampu/diminta/teramati yang terpisah. Pemilihan lokal yang sama tersedia sebagai temuan informatif doctor:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Catatan

• Pemahaman dilakukan dengan upaya terbaik. Kesalahan tidak menghalangi balasan.
• Lampiran tetap diteruskan ke model meskipun pemahaman dinonaktifkan.
• Gunakan scope untuk membatasi tempat pemahaman berjalan (misalnya, hanya DM).

Terkait

• Konfigurasi
• Dukungan gambar & media