Media Understanding (Eingehend) — 17.01.2026

OpenClaw kann eingehende Medien zusammenfassen (Bild/Audio/Video), bevor die Reply-Pipeline läuft. Es erkennt automatisch, ob lokale Tools oder Provider-Keys verfügbar sind, und kann deaktiviert oder angepasst werden. Wenn das Understanding ausgeschaltet ist, erhalten Modelle die Original-Dateien/URLs wie gewohnt.

Ziele

Optional: Eingehende Medien vorab in kurzen Text umwandeln für schnelleres Routing und besseres Command-Parsing.
Original-Medien werden immer an das Modell weitergegeben.
Unterstützung für Provider-APIs und CLI-Fallbacks.
Mehrere Modelle mit geordnetem Fallback (bei Fehler/Größe/Timeout).

Funktionsweise im Überblick

Eingehende Attachments sammeln (MediaPaths, MediaUrls, MediaTypes).
Für jede aktivierte Fähigkeit (image/audio/video) werden Attachments nach Policy ausgewählt (Standard: first).
Den ersten passenden Model-Eintrag wählen (Größe + Fähigkeit + Auth).
Wenn ein Modell fehlschlägt oder die Medien zu groß sind, zum nächsten Eintrag wechseln.
Bei Erfolg:
- Body wird zu [Image], [Audio] oder [Video] Block.
- Audio setzt {{Transcript}}; Command-Parsing nutzt Caption-Text falls vorhanden, sonst das Transkript.
- Captions werden als User text: im Block gespeichert.

Wenn Understanding fehlschlägt oder deaktiviert ist, läuft der Reply-Flow weiter mit dem Original-Body und Attachments.

Config-Überblick

tools.media unterstützt gemeinsame Modelle plus Overrides pro Fähigkeit:

tools.media.models: Gemeinsame Modell-Liste (nutze capabilities zum Filtern).
tools.media.image / tools.media.audio / tools.media.video:
- Defaults (prompt, maxChars, maxBytes, timeoutSeconds, language)
- Provider-Overrides (baseUrl, headers, providerOptions)
- Deepgram-Audio-Optionen über tools.media.audio.providerOptions.deepgram
- Optional eigene models-Liste pro Fähigkeit (wird vor gemeinsamen Modellen bevorzugt)
- attachments-Policy (mode, maxAttachments, prefer)
- scope (optionales Gating nach Channel/chatType/Session-Key)
tools.media.concurrency: Max. gleichzeitige Capability-Runs (Standard 2).

{
  tools: {
    media: {
      models: [
        /* gemeinsame Liste */
      ],
      image: {
        /* optionale Overrides */
      },
      audio: {
        /* optionale Overrides */
      },
      video: {
        /* optionale Overrides */
      },
    },
  },
}

Model-Einträge

Jeder models[]-Eintrag kann provider oder CLI sein:

{
  type: "provider", // Standard, wenn weggelassen
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, für multi-modale Einträge
  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"],
}

CLI-Templates können auch nutzen:

{{MediaDir}} (Verzeichnis mit der Mediendatei)
{{OutputDir}} (Scratch-Verzeichnis für diesen Run)
{{OutputBase}} (Scratch-Dateipfad ohne Extension)

Defaults und Limits

Empfohlene Defaults:

maxChars: 500 für image/video (kurz, command-freundlich)
maxChars: nicht gesetzt für audio (volles Transkript, außer du setzt ein Limit)
maxBytes:
- image: 10MB
- audio: 20MB
- video: 50MB

Regeln:

Wenn Medien maxBytes überschreiten, wird das Modell übersprungen und das nächste Modell versucht.
Wenn das Modell mehr als maxChars zurückgibt, wird die Ausgabe gekürzt.
prompt ist standardmäßig ein einfaches “Describe the {media}.” plus maxChars-Hinweis (nur image/video).
Wenn <capability>.enabled: true, aber keine Modelle konfiguriert sind, versucht OpenClaw das aktive Reply-Modell, wenn dessen Provider die Fähigkeit unterstützt.

Auto-Detect Media Understanding (Standard)

Wenn tools.media.<capability>.enabled nicht auf false gesetzt ist und du keine Modelle konfiguriert hast, erkennt OpenClaw automatisch in dieser Reihenfolge und stoppt bei der ersten funktionierenden Option:

Lokale CLIs (nur audio; falls installiert)
- sherpa-onnx-offline (benötigt SHERPA_ONNX_MODEL_DIR mit encoder/decoder/joiner/tokens)
- whisper-cli (whisper-cpp; nutzt WHISPER_CPP_MODEL oder das mitgelieferte tiny-Modell)
- whisper (Python-CLI; lädt Modelle automatisch herunter)
Gemini CLI (gemini) mit read_many_files
Provider-Keys
- Audio: OpenAI → Groq → Deepgram → Google
- Image: OpenAI → Anthropic → Google → MiniMax
- Video: Google

Um Auto-Detection zu deaktivieren:

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

Hinweis: Binary-Erkennung ist Best-Effort für macOS/Linux/Windows; stelle sicher, dass das CLI im PATH ist (wir expandieren ~), oder setze ein explizites CLI-Modell mit vollem Command-Pfad.

Capabilities (optional)

Wenn du capabilities setzt, läuft der Eintrag nur für diese Medientypen. Für gemeinsame Listen kann OpenClaw Defaults ableiten:

openai, anthropic, minimax: image
google (Gemini API): image + audio + video
groq: audio
deepgram: audio

Für CLI-Einträge setze capabilities explizit, um überraschende Matches zu vermeiden. Wenn du capabilities weglässt, ist der Eintrag für die Liste geeignet, in der er erscheint.

Provider-Support-Matrix (OpenClaw-Integrationen)

Capability	Provider-Integration	Hinweise
Image	OpenAI / Anthropic / Google / andere via `pi-ai`	Jedes bilderfähige Modell in der Registry funktioniert.
Audio	OpenAI, Groq, Deepgram, Google	Provider-Transkription (Whisper/Deepgram/Gemini).
Video	Google (Gemini API)	Provider-Video-Understanding.

Empfohlene Provider

Image

Bevorzuge dein aktives Modell, wenn es Bilder unterstützt.
Gute Defaults: openai/gpt-5.2, anthropic/claude-opus-4-5, google/gemini-3-pro-preview.

Audio

openai/gpt-4o-mini-transcribe, groq/whisper-large-v3-turbo oder deepgram/nova-3.
CLI-Fallback: whisper-cli (whisper-cpp) oder whisper.
Deepgram-Setup: Deepgram (audio transcription).

Video

google/gemini-3-flash-preview (schnell), google/gemini-3-pro-preview (detaillierter).
CLI-Fallback: gemini CLI (unterstützt read_file für video/audio).

Attachment-Policy

Die attachments-Config pro Fähigkeit steuert, welche Attachments verarbeitet werden:

mode: first (Standard) oder all
maxAttachments: Begrenzt die Anzahl verarbeiteter Attachments (Standard 1)
prefer: first, last, path, url

Bei mode: "all" werden Ausgaben mit [Image 1/2], [Audio 2/2] usw. beschriftet.

Config-Beispiele

1) Gemeinsame Modell-Liste + Overrides

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", 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,
      },
    },
  },
}

2) Nur Audio + Video (image aus)

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

3) Optionales Image-Understanding

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-5" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

4) Multi-modaler Einzeleintrag (explizite Capabilities)

{
  tools: {
    media: {
      image: {
        models: [
          {
            provider: "google",
            model: "gemini-3-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      audio: {
        models: [
          {
            provider: "google",
            model: "gemini-3-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      video: {
        models: [
          {
            provider: "google",
            model: "gemini-3-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
    },
  },
}

Status-Ausgabe

Wenn Media Understanding läuft, zeigt /status eine kurze Zusammenfassung:

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

Das zeigt die Ergebnisse pro Fähigkeit und den gewählten Provider/Modell, falls zutreffend.

Hinweise

Understanding ist Best-Effort. Fehler blockieren keine Replies.
Attachments werden auch dann an Modelle weitergegeben, wenn Understanding deaktiviert ist.
Nutze scope, um einzuschränken, wo Understanding läuft (z.B. nur DMs).