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

OpenClaw makin sering dipakai untuk chat teks, membaca gambar, menganalisis PDF, memahami audio, dan generate media. Karena itu, config provider model tidak boleh asal copy dari contoh lama. Di versi April dan Mei 2026, model catalog, plugin provider, media tools, dan image generation default sudah lebih rapi, tetapi path config-nya harus tepat.

Artikel ini adalah versi terbaru untuk OpenClaw 4.xx dan 5.xx. Fokusnya: format config yang aman, mudah divalidasi, dan kompatibel dengan provider custom.

Ringkasan perubahan update Mei 2026

Perubahan penting dibanding artikel lama:

1. Model catalog modern ada di agents.defaults.models untuk daftar model yang bisa dipilih agent.
2. Provider credential sebaiknya tidak ditulis langsung di artikel, repo, atau config publik. Gunakan env atau SecretRef.
3. Image understanding, audio understanding, dan shared media model memakai tools.media.*.
4. PDF model punya default sendiri di agents.defaults.pdfModel.
5. Image generation punya default sendiri di agents.defaults.imageGenerationModel.
6. Plugin provider sekarang bisa masuk lewat plugins.entries., termasuk provider dari ClawHub.
7. Untuk OpenClaw 5.xx, models list, models status, dan plugin catalog lebih baik dipakai sebagai validasi.

Versi yang disarankan:

• OpenClaw 4.xx: pakai versi April akhir.
• OpenClaw 5.xx: pakai 2026.5.4 ke atas. Untuk plugin-heavy install, 2026.5.12 atau 2026.5.18 lebih stabil.

Prinsip dasar

Pisahkan tiga hal:

• Provider: koneksi ke API atau plugin.
• Model catalog: daftar model yang dikenal OpenClaw.
• Default tool model: model yang dipakai untuk image, audio, PDF, atau image generation.

Jangan campur semuanya di satu field.

Cek schema lokal dulu

Jalankan:

openclaw config get agents.defaults.models
openclaw config get agents.defaults.imageGenerationModel
openclaw config get agents.defaults.pdfModel
openclaw config get tools.media
openclaw config validate

Untuk melihat daftar model:

openclaw models status
openclaw models list

Jika provider datang dari plugin:

openclaw plugins list
openclaw plugins doctor

Format model catalog

Model catalog bisa ditambah lewat agents.defaults.models. Kuncinya adalah model ref penuh, biasanya provider/model.

Contoh:

{
 "agents": {
 "defaults": {
 "models": {
 "custom/gpt-5.5": {
 "alias": "Custom GPT-5.5",
 "streaming": true,
 "params": {}
 }
 }
 }
 }
}

Kalau memakai command:

openclaw config set agents.defaults.models '{"custom/gpt-5.5":{"alias":"Custom GPT-5.5","streaming":true,"params":{}}}' --strict-json --merge
openclaw config validate

Pakai --merge supaya entry lama tidak ketimpa.

Default image understanding

Image understanding adalah kemampuan membaca atau menjelaskan gambar. Ini beda dari image generation.

Config yang relevan:

{
 "tools": {
 "media": {
 "image": {
 "enabled": true,
 "models": [
 "openai/gpt-5.5"
 ],
 "maxBytes": 12000000,
 "timeoutSeconds": 60
 }
 }
 }
}

Untuk model multimodal custom, ganti model dengan ref yang benar:

{
 "tools": {
 "media": {
 "image": {
 "enabled": true,
 "models": [
 "growthcircle/gpt-5.5"
 ]
 }
 }
 }
}

Pastikan model memang menerima input image. Jangan hanya melihat nama model.

Default audio understanding

Audio understanding dipakai untuk voice note, audio clip, atau transcript:

{
 "tools": {
 "media": {
 "audio": {
 "enabled": true,
 "models": [
 "openai/gpt-5.5"
 ],
 "language": "id",
 "timeoutSeconds": 90,
 "maxChars": 12000
 }
 }
 }
}

Kalau provider audio memakai endpoint transkripsi khusus, cek schema provider-nya. Jangan memaksa chat model biasa untuk transkripsi jika provider tidak mendukung audio input.

Default PDF model

PDF analysis punya default sendiri:

{
 "agents": {
 "defaults": {
 "pdfModel": "anthropic/claude-opus-4-7"
 }
 }
}

Kalau memakai provider lain:

{
 "agents": {
 "defaults": {
 "pdfModel": "growthcircle/gpt-5.5"
 }
 }
}

Pilih model yang kuat di long context dan document reasoning. PDF sering lebih berat dari image tunggal.

Default image generation

Image generation berbeda dari image understanding. Untuk generator gambar:

{
 "agents": {
 "defaults": {
 "imageGenerationModel": {
 "primary": "growthcircle/gpt-image-2",
 "timeoutMs": 180000
 }
 }
 }
}

Kalau provider memakai model resmi OpenAI:

{
 "agents": {
 "defaults": {
 "imageGenerationModel": {
 "primary": "openai/gpt-image-2",
 "timeoutMs": 180000
 }
 }
 }
}

Jika butuh fallback:

{
 "agents": {
 "defaults": {
 "imageGenerationModel": {
 "primary": "growthcircle/gpt-image-2",
 "fallbacks": [
 "openai/gpt-image-2",
 "google/gemini-3-pro-image-preview"
 ],
 "timeoutMs": 180000
 }
 }
 }
}

Gunakan fallback hanya jika semua model itu benar-benar tersedia dan punya auth.

Provider plugin dan allowlist

Jika provider berasal dari plugin, contoh path-nya:

{
 "plugins": {
 "entries": {
 "gc-provider": {
 "enabled": true,
 "config": {}
 }
 }
 }
}

Kalau install memakai plugin allowlist:

{
 "plugins": {
 "allow": [
 "gc-provider"
 ]
 }
}

Jika sudah ada plugin lain, jangan replace seluruh allowlist. Gabungkan entry baru dengan yang lama.

Contoh config gabungan

Contoh untuk host yang ingin memakai GrowthCircle sebagai provider teks dan image generation, sambil tetap punya PDF default:

{
 "plugins": {
 "entries": {
 "gc-provider": {
 "enabled": true
 }
 }
 },
 "agents": {
 "defaults": {
 "models": {
 "growthcircle/gpt-5.5": {
 "alias": "GrowthCircle GPT-5.5",
 "streaming": true
 },
 "growthcircle/claude-opus-4-7": {
 "alias": "GrowthCircle Claude Opus 4.7",
 "streaming": true
 }
 },
 "pdfModel": "growthcircle/gpt-5.5",
 "imageGenerationModel": {
 "primary": "growthcircle/gpt-image-2",
 "timeoutMs": 180000
 }
 }
 },
 "tools": {
 "media": {
 "image": {
 "enabled": true,
 "models": [
 "growthcircle/gpt-5.5"
 ]
 },
 "audio": {
 "enabled": true,
 "models": [
 "growthcircle/gpt-5.5"
 ],
 "language": "id"
 }
 }
 }
}

Verifikasi

Setelah patch:

openclaw config validate
openclaw gateway restart
openclaw models list
openclaw models status
openclaw plugins doctor

Untuk image generation, test dari chat:

/tool image_generate action=generate model=growthcircle/gpt-image-2 prompt="A clean product mockup" aspectRatio=1:1 count=1

Untuk PDF, kirim PDF lalu minta ringkasan. Untuk image understanding, kirim gambar lalu minta agent menjelaskan isi gambar.

Kesimpulan

Di OpenClaw 4.xx dan 5.xx, config custom provider harus dipisah dengan rapi. Pakai agents.defaults.models untuk catalog, tools.media.* untuk understanding, agents.defaults.pdfModel untuk PDF, dan agents.defaults.imageGenerationModel untuk generate gambar.

Sebelum publish config ke server, selalu jalankan openclaw config validate, openclaw models status, dan test kecil dari channel yang benar. Ini jauh lebih aman daripada menebak field dari artikel lama.