Pemahaman media

OpenClaw dapat meringkas media masuk (gambar/audio/video) sebelum pipeline balasan berjalan. OpenClaw otomatis mendeteksi ketika alat lokal atau kunci penyedia tersedia, dan dapat dinonaktifkan atau disesuaikan. Jika pemahaman dimatikan, 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: pra-cerna media masuk menjadi teks singkat untuk routing yang lebih cepat + parsing perintah yang lebih baik.
• Pertahankan pengiriman media asli ke model (selalu).
• Mendukung API penyedia dan fallback CLI.
• Memungkinkan beberapa model dengan fallback berurutan (galat/ukuran/timeout).

# Perilaku tingkat tinggi

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

# Ikhtisar konfigurasi

tools.media mendukung model bersama plus override per kapabilitas:

{
  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:

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

# Default dan batas

Default yang direkomendasikan:

• maxChars: 500 untuk gambar/video (singkat, ramah perintah)
• maxChars: tidak diatur untuk audio (transkrip penuh kecuali Anda menetapkan batas)
• maxBytes:
  • gambar: 10MB
  • audio: 20MB
  • video: 50MB

# 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:

Untuk menonaktifkan deteksi otomatis, setel:

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

# 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 env 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 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
• 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 berkemampuan gambar: gambar

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

# Matriks dukungan penyedia (integrasi OpenClaw)

# Panduan pemilihan model

• Pilih model generasi terbaru terkuat yang tersedia untuk setiap kapabilitas media ketika kualitas dan keamanan penting.
• Untuk agen beralat yang menangani input tidak tepercaya, hindari model media 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 ketika API penyedia tidak tersedia.
• Catatan parakeet-mlx: dengan --output-dir, OpenClaw membaca <output-dir>/<media-basename>.txt ketika format output adalah txt (atau tidak ditentukan); format non-txt fallback ke stdout.

# Kebijakan lampiran

attachments per kapabilitas mengontrol lampiran mana yang diproses:

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

# Contoh konfigurasi

{
  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. Kesalahan tidak memblokir balasan.
• Lampiran tetap diteruskan ke model meskipun pemahaman dinonaktifkan.
• Gunakan scope untuk membatasi tempat pemahaman berjalan (misalnya hanya DM).

# Terkait

• Konfigurasi
• Dukungan gambar & media