Media Understanding (eingehend) — 2026-01-17

OpenClaw kann eingehende Medien (Bild/Audio/Video) zusammenfassen, bevor die Antwort-Pipeline läuft. Es erkennt automatisch, wenn lokale Tools oder Provider-Schlüssel verfügbar sind, und kann deaktiviert oder angepasst werden. Wenn Understanding aus ist, erhalten Modelle die Originaldateien/-URLs wie gewohnt.

Ziele

  • Optional: eingehende Medien in kurzen Text vorverdauen für schnelleres Routing + bessere Befehlserkennung.
  • Originale Medienlieferung an das Modell (immer) beibehalten.
  • Provider-APIs und CLI-Fallbacks unterstützen.
  • Mehrere Modelle mit geordnetem Fallback (Fehler/Größe/Timeout) ermöglichen.

Übergeordnetes Verhalten

  1. Eingehende Anhänge sammeln (MediaPaths, MediaUrls, MediaTypes).
  2. Für jede aktivierte Fähigkeit (Bild/Audio/Video) Anhänge nach Richtlinie auswählen (Standard: erster).
  3. Den ersten passenden Modelleintrag wählen (Größe + Fähigkeit + Auth).
  4. Wenn ein Modell fehlschlägt oder das Medium zu groß ist, zum nächsten Eintrag wechseln.
  5. Bei Erfolg:
    • Body wird zu [Image]-, [Audio]- oder [Video]-Block.
    • Audio setzt {{Transcript}}; Befehlserkennung verwendet Bildunterschrift-Text wenn vorhanden, sonst das Transkript.
    • Bildunterschriften werden als User text: innerhalb des Blocks beibehalten.

Wenn Understanding fehlschlägt oder deaktiviert ist, läuft der Antwortfluss weiter mit dem Original-Body + Anhängen.

Konfigurationsübersicht

tools.media unterstützt geteilte Modelle plus pro-Fähigkeits-Overrides:

  • tools.media.models: geteilte Modellliste (nutze capabilities zur Steuerung).
  • tools.media.image / tools.media.audio / tools.media.video:
    • Standardwerte (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • Provider-Overrides (baseUrl, headers, providerOptions)
    • Deepgram-Audio-Optionen über tools.media.audio.providerOptions.deepgram
    • Audio-Transkript-Echo-Steuerung (echoTranscript, Standard false; echoFormat)
    • optionale pro-Fähigkeits-models-Liste (bevorzugt vor geteilten Modellen)
    • attachments-Richtlinie (mode, maxAttachments, prefer)
    • scope (optionale Einschränkung nach Kanal/chatType/Session-Key)
  • tools.media.concurrency: maximale parallele Fähigkeitsläufe (Standard 2).
{
  tools: {
    media: {
      models: [
        /* geteilte Liste */
      ],
      image: {
        /* optionale Overrides */
      },
      audio: {
        /* optionale Overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optionale Overrides */
      },
    },
  },
}

Modelleinträ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 multimodale 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 verwenden:

  • {{MediaDir}} (Verzeichnis mit der Mediendatei)
  • {{OutputDir}} (Scratch-Verzeichnis für diesen Lauf)
  • {{OutputBase}} (Scratch-Dateibasis, ohne Endung)

Standardwerte und Limits

Empfohlene Standardwerte:

  • maxChars: 500 für Bild/Video (kurz, befehlsfreundlich)
  • maxChars: nicht gesetzt für Audio (volles Transkript, es sei denn du setzt ein Limit)
  • maxBytes:
    • Bild: 10 MB
    • Audio: 20 MB
    • Video: 50 MB

Regeln:

  • Wenn Medien maxBytes überschreiten, wird dieses Modell übersprungen und das nächste Modell versucht.
  • Audiodateien kleiner als 1024 Bytes werden als leer/korrupt behandelt und vor der Provider/CLI-Transkription übersprungen.
  • Wenn das Modell mehr als maxChars zurückgibt, wird die Ausgabe gekürzt.
  • prompt hat standardmäßig ein einfaches „Describe the {media}.” plus maxChars-Hinweis (nur Bild/Video).
  • Wenn <capability>.enabled: true, aber keine Modelle konfiguriert sind, versucht OpenClaw das aktive Antwortmodell, wenn dessen Provider die Fähigkeit unterstützt.

Automatische Media-Understanding-Erkennung (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:

  1. Lokale CLIs (nur Audio; wenn 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)
  2. Gemini CLI (gemini) mit read_many_files
  3. Provider-Keys
    • Audio: OpenAI → Groq → Deepgram → Google
    • Bild: OpenAI → Anthropic → Google → MiniMax
    • Video: Google

Um die automatische Erkennung zu deaktivieren, setze:

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

Hinweis: Die Binärerkennung funktioniert plattformübergreifend (macOS/Linux/Windows) nach bestem Bemühen. Stelle sicher, dass die CLI im PATH liegt (wir expandieren ~), oder setze ein explizites CLI-Modell mit vollem Befehlspfad.

Proxy-Unterstützung (Provider-Modelle)

Wenn provider-basiertes Audio- und Video-Media-Understanding aktiviert ist, berücksichtigt OpenClaw die üblichen Proxy-Umgebungsvariablen für ausgehende HTTP-Aufrufe:

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

Wenn keine Proxy-Variablen gesetzt sind, nutzt Media Understanding direkten Zugang. Wenn der Proxy-Wert fehlerhaft ist, loggt OpenClaw eine Warnung und fällt auf direkten Zugriff zurück.

Fähigkeiten (optional)

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

  • openai, anthropic, minimax: Bild
  • google (Gemini API): Bild + Audio + Video
  • groq: Audio
  • deepgram: Audio

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

Provider-Unterstützungsmatrix (OpenClaw-Integrationen)

FähigkeitProvider-IntegrationHinweise
BildOpenAI / Anthropic / Google / andere via pi-aiJedes bildfähige Modell im Registry funktioniert.
AudioOpenAI, Groq, Deepgram, Google, MistralProvider-Transkription (Whisper/Deepgram/Gemini/Voxtral).
VideoGoogle (Gemini API)Provider-Video-Verständnis.

Modellauswahl-Hinweise

  • Bevorzuge das stärkste aktuelle Modell für jede Medienfähigkeit, wenn Qualität und Sicherheit wichtig sind.
  • Für tool-fähige Agents, die nicht vertrauenswürdige Eingaben verarbeiten, vermeide ältere/schwächere Medienmodelle.
  • Halte mindestens einen Fallback pro Fähigkeit für Verfügbarkeit bereit (Qualitätsmodell + schnelleres/günstigeres Modell).
  • CLI-Fallbacks (whisper-cli, whisper, gemini) sind nützlich, wenn Provider-APIs nicht verfügbar sind.
  • parakeet-mlx-Hinweis: Mit --output-dir liest OpenClaw <output-dir>/<media-basename>.txt, wenn das Ausgabeformat txt ist (oder nicht angegeben); andere Formate fallen auf Stdout zurück.

Anhang-Richtlinie

Pro-Fähigkeits-attachments steuert, welche Anhänge verarbeitet werden:

  • mode: first (Standard) oder all
  • maxAttachments: begrenzt die Anzahl der verarbeiteten (Standard 1)
  • prefer: first, last, path, url

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

Konfigurationsbeispiele

1) Geteilte Modellliste + 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 (Bild 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 Bildverständnis

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { 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.",
            ],
          },
        ],
      },
    },
  },
}

4) Multimodaler Einzeleintrag (explizite Fähigkeiten)

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

Statusausgabe

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

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

Diese zeigt Ergebnisse pro Fähigkeit und den gewählten Provider/Modell, wenn zutreffend.

Hinweise

  • Understanding funktioniert nach bestem Bemühen. Fehler blockieren keine Antworten.
  • Anhänge werden auch bei deaktiviertem Understanding weiterhin an Modelle übergeben.
  • Nutze scope, um einzuschränken, wo Understanding läuft (z. B. nur Direktnachrichten).

Verwandte Dokumentation

arrow_back
Zurück
Troubleshooting
Weiter
Images
arrow_forward