Cara Setting Custom Provider Model OpenClaw agar Bisa Kenali Gambar, Audio, dan PDF

Kalau Anda pakai custom provider model di OpenClaw, ada satu kesalahan yang sangat sering terjadi: semua capability multimodal dipaksa masuk ke field input model.

Akhirnya config diisi seperti ini:

"input": ["text", "image", "audio", "document"]

Kelihatannya masuk akal, tapi itu justru titik salahnya.

Per source OpenClaw yang saya cek langsung pada 15 April 2026, field input di model registry utama saat ini masih aman untuk text dan image saja. Jadi kalau target Anda adalah bot bisa membaca gambar, voice note, video, atau PDF, jalur config-nya memang tidak semua lewat satu field yang sama.

Kalau harus diringkas cepat:

• gambar bisa lewat model vision dan image pipeline,
• audio / voice note lewat tools.media.audio,
• video lewat tools.media.video,
• PDF lewat pdfModel atau tool pdf,
• dan bukan semuanya lewat models[].input.

Ringkasan Cepat

Kalau Anda hanya ingin konfigurasi yang aman dan practical, pegang mapping ini:

• text-only model → input: ["text"]
• vision model → input: ["text", "image"]
• image analysis → agents.defaults.imageModel + tools.media.image
• audio transcription / voice note → tools.media.audio
• video summary / description → tools.media.video
• PDF / document analysis → agents.defaults.pdfModel

Jadi problem utamanya bukan "OpenClaw tidak support multimodal", tapi layer config-nya memang dipisah.

Kenapa Banyak Orang Salah Paham?

Karena saat melihat custom provider model, orang biasanya fokus ke bagian ini:

• baseUrl
• apiKey
• api
• model id
• input

Lalu muncul asumsi: kalau model mau dibuat bisa baca semua hal, berarti semua capability harus ditulis di input.

Padahal di OpenClaw sekarang, arsitekturnya lebih terpisah.

Ada tiga layer yang perlu dibedakan:

1. model registry utama
2. agent default model untuk tool tertentu
3. media understanding pipeline

Kalau tiga layer ini dicampur jadi satu, config akan terlihat rapi di mata manusia, tapi salah di runtime.

Layer 1: Model Registry Utama

Ini bagian yang biasanya ada di bawah:

models.providers.*.models[]

Contoh paling umum:

{
 "models": {
 "mode": "merge",
 "providers": {
 "custom-openai": {
 "baseUrl": "https://api.example.com/v1",
 "api": "openai-responses",
 "models": [
 {
 "id": "my-model-vision",
 "name": "My Model Vision",
 "reasoning": true,
 "input": ["text", "image"],
 "contextWindow": 128000,
 "maxTokens": 8192
 }
 ]
 }
 }
 }
}

Yang aman dipakai di input

Untuk schema model utama, yang aman saat ini adalah:

• "text"
• "image"

Jadi bentuk valid yang normal biasanya hanya dua ini:

"input": ["text"]

atau:

"input": ["text", "image"]

Yang jangan dipaksa masuk ke sini

Jangan langsung mengandalkan field ini untuk:

• audio
• video
• document

Bukan karena capability itu mustahil dipakai di OpenClaw, tapi karena jalur konfigurasinya bukan di sini.

Layer 2: Image Model dan PDF Model untuk Tool

OpenClaw punya jalur config terpisah untuk tool tertentu. Dua yang paling relevan untuk kasus ini adalah:

• agents.defaults.imageModel
• agents.defaults.pdfModel

imageModel

Ini dipakai untuk tool image atau jalur analisis gambar yang butuh model vision khusus.

Contoh:

{
 "agents": {
 "defaults": {
 "imageModel": {
 "primary": "google/gemini-3-flash-preview"
 }
 }
 }
}

pdfModel

Ini dipakai untuk tool pdf.

Contoh:

{
 "agents": {
 "defaults": {
 "pdfModel": {
 "primary": "google/gemini-3-flash-preview",
 "fallbacks": ["anthropic/claude-opus-4-6"]
 }
 }
 }
}

Ini penting karena di source OpenClaw memang terlihat ada jalur native PDF/tool PDF, termasuk support native PDF untuk provider tertentu seperti Google dan Anthropic. Jadi kalau mau PDF stabil, lebih aman pakai pdfModel daripada memaksa "document" ke field input model utama.

Layer 3: Media Understanding Pipeline

Kalau target Anda adalah attachment yang masuk otomatis dipahami, yang relevan justru bagian ini:

• tools.media.image
• tools.media.audio
• tools.media.video

Di sinilah OpenClaw memisahkan image understanding, audio transcription, dan video description.

Supaya Gambar Bisa Dipahami

Untuk gambar, ada dua pola yang masuk akal.

Opsi A, model utama memang vision

Kalau model utama Anda memang vision-capable, daftarkan model dengan:

"input": ["text", "image"]

Opsi B, aktifkan jalur image understanding

{
 "tools": {
 "media": {
 "image": {
 "enabled": true,
 "models": [
 {
 "provider": "google",
 "model": "gemini-3-flash-preview"
 }
 ]
 }
 }
 }
}

Kalau mau lebih rapi, gabungkan juga dengan agents.defaults.imageModel.

Supaya Voice Note atau Audio Bisa Dipahami

Ini bagian yang paling sering salah.

Audio tidak masuk lewat models[].input.

Jalur yang benar adalah tools.media.audio.

Contoh config:

{
 "tools": {
 "media": {
 "audio": {
 "enabled": true,
 "language": "id",
 "echoTranscript": false,
 "models": [
 {
 "provider": "openai",
 "model": "gpt-4o-transcribe"
 }
 ]
 }
 }
 }
}

Kalau Anda ingin transcript langsung dipantulkan balik ke chat sebelum diproses agent, Anda bisa nyalakan:

{
 "tools": {
 "media": {
 "audio": {
 "enabled": true,
 "language": "id",
 "echoTranscript": true,
 "echoFormat": "📝 {transcript}",
 "models": [
 {
 "provider": "openai",
 "model": "gpt-4o-transcribe"
 }
 ]
 }
 }
 }
}

Jadi kalau ada orang bilang "biar model custom bisa dengar audio, tambahkan audio ke input", jawaban pendeknya: bukan itu jalurnya.

Supaya Video Bisa Dipahami

Video juga tidak dikonfigurasi lewat input model utama.

Pakai jalur ini:

{
 "tools": {
 "media": {
 "video": {
 "enabled": true,
 "models": [
 {
 "provider": "google",
 "model": "gemini-3-flash-preview"
 }
 ]
 }
 }
 }
}

Artinya, secara desain OpenClaw memang memperlakukan video sebagai pipeline media understanding tersendiri.

Supaya PDF Bisa Dianalisis

PDF adalah area yang paling bikin orang kejebak karena di internal catalog memang ada istilah document.

Masalahnya, banyak orang lalu mengira ini berarti mereka aman menulis:

"input": ["text", "image", "document"]

Padahal untuk model registry utama, itu bukan jalur paling aman.

Yang lebih aman adalah:

{
 "agents": {
 "defaults": {
 "pdfModel": {
 "primary": "google/gemini-3-flash-preview",
 "fallbacks": ["anthropic/claude-opus-4-6"]
 }
 }
 }
}

Kalau targetnya memang tool pdf jalan stabil, inilah jalur yang lebih bersih.

Contoh Config yang Paling Practical

Kalau target Anda adalah:

• chat normal bisa baca gambar,
• voice note bisa ditranskrip,
• video bisa diringkas,
• PDF bisa dianalisis,

maka template aman yang cukup practical kira-kira seperti ini:

{
 "agents": {
 "defaults": {
 "model": {
 "primary": "google/gemini-3-flash-preview"
 },
 "imageModel": {
 "primary": "google/gemini-3-flash-preview"
 },
 "pdfModel": {
 "primary": "google/gemini-3-flash-preview",
 "fallbacks": ["anthropic/claude-opus-4-6"]
 }
 }
 },
 "tools": {
 "media": {
 "image": {
 "enabled": true,
 "models": [
 {
 "provider": "google",
 "model": "gemini-3-flash-preview"
 }
 ]
 },
 "audio": {
 "enabled": true,
 "language": "id",
 "echoTranscript": false,
 "models": [
 {
 "provider": "openai",
 "model": "gpt-4o-transcribe"
 }
 ]
 },
 "video": {
 "enabled": true,
 "models": [
 {
 "provider": "google",
 "model": "gemini-3-flash-preview"
 }
 ]
 }
 }
 }
}

Kesalahan yang Paling Sering Terjadi

1. Menganggap semua multimodal capability harus masuk ke input

Ini error paling umum.

2. Menganggap document di internal catalog berarti aman dipakai mentah di model registry utama

Belum tentu. Untuk runtime config yang aman, lebih baik pakai jalur pdfModel / tool pdf.

3. Mencampur model utama dengan pipeline media understanding

Model utama dan media pipeline bisa saling melengkapi, tapi bukan berarti semuanya satu field.

4. Fokus ke provider, lupa ke flow tool

Di OpenClaw, kemampuan nyata bukan cuma soal provider mana yang dipakai, tapi juga jalur runtime mana yang aktif.

Cara Berpikir yang Lebih Benar

Kalau Anda ingin setup custom provider OpenClaw lebih rapi, pikirkan config-nya seperti ini:

• model registry menentukan model apa yang terdaftar dan apakah dia text-only atau vision,
• agent defaults menentukan model mana yang dipakai untuk tool tertentu seperti image atau PDF,
• tools.media menentukan bagaimana attachment seperti gambar, audio, dan video dipahami.

Begitu dipisah seperti ini, config langsung jauh lebih mudah dibaca dan debug-nya juga lebih ringan.

Kesimpulan

Kalau Anda pakai custom provider model di OpenClaw, jangan mulai dari asumsi bahwa semua capability multimodal harus ditulis di satu field input.

Untuk setup yang aman saat ini:

• input model utama: pakai text atau text + image saja
• gambar: pakai vision model dan/atau tools.media.image
• audio: pakai tools.media.audio
• video: pakai tools.media.video
• PDF: pakai agents.defaults.pdfModel atau tool pdf

Singkatnya, gambar, audio, video, dan PDF memang didukung, tapi jalur config-nya berbeda-beda.

Kalau Anda sedang setup custom provider di OpenClaw dan ingin config-nya rapi, stabil, dan tidak misleading sejak awal, RamaDigital bisa bantu audit structure model, mapping capability, dan workflow operasionalnya supaya hasilnya bukan sekadar jalan, tapi enak dipakai di produksi.