Medienverständnis

OpenClaw kann eingehende Medien (Bilder/Audio/Video) zusammenfassen, bevor die Antwort-Pipeline ausgeführt wird. Dadurch arbeiten Befehlsanalyse und Routing mit kurzem Text statt mit Rohdaten. Die Medienanalyse erkennt lokale Werkzeuge oder Provider-Schlüssel automatisch; alternativ können Sie explizite Modelle konfigurieren. Die Originalmedien werden dem Modell wie gewohnt immer bereitgestellt. Wenn die Analyse fehlschlägt oder deaktiviert ist, wird der Antwortablauf unverändert fortgesetzt.

Hersteller-Plugins registrieren Metadaten zu ihren Fähigkeiten (welcher Provider welchen Medientyp unterstützt, Standardmodell, Priorität). Der OpenClaw-Kern verwaltet die gemeinsame Konfiguration tools.media, die Fallback-Reihenfolge und die Integration in die Antwort-Pipeline.

Funktionsweise

Konfiguration

tools.media enthält eine gemeinsame Modellliste sowie fähigkeitsspezifische Überschreibungen:

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

Schlüssel pro Fähigkeit (image/audio/video):

Deepgram-spezifische Optionen gehören unter providerOptions.deepgram (das Feld deepgram: { detectLanguage, punctuate, smartFormat } auf oberster Ebene ist veraltet, wird aber weiterhin gelesen).

Modelleinträge

Jeder Eintrag in models[] ist ein Provider-Eintrag (Standard) oder ein CLI-Eintrag:

{  type: "provider", // default if omitted  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Describe the image in <= 500 chars.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"], // optional, for multi-modal shared 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"],}

Provider-Anmeldedaten

Die Provider-basierte Medienanalyse verwendet dieselbe Authentifizierungsauflösung wie normale Modellaufrufe: Authentifizierungsprofile, Umgebungsvariablen und anschließend models.providers.<providerId>.apiKey. Einträge in tools.media.*.models[] akzeptieren kein direkt eingebettetes Feld apiKey.

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

Informationen zu Profilen, Umgebungsvariablen und benutzerdefinierten Basis-URLs finden Sie unter Werkzeuge und benutzerdefinierte Provider.

Regeln und Verhalten

• Medien, die maxBytes überschreiten, überspringen dieses Modell und verwenden das nächste.
• Audiodateien unter 1024 Byte werden als leer oder beschädigt behandelt und vor der Transkription übersprungen; der Agent erhält stattdessen ein deterministisches Platzhaltertranskript.
• Wenn das aktive primäre Bildmodell bereits nativ Bildverarbeitung unterstützt, überspringt OpenClaw den Zusammenfassungsblock [Image] und übergibt das Originalbild direkt an das Modell. MiniMax bildet eine Ausnahme: minimax, minimax-cn, minimax-portal und minimax-portal-cn leiten die Bildanalyse immer über den Plugin-eigenen Medien-Provider MiniMax-VL-01, selbst wenn veraltete Chat-Metadaten von MiniMax M2.x die Unterstützung von Bildeingaben angeben (nur MiniMax-M3 und spätere Versionen gelten als nativ bildverarbeitungsfähig).
• Wenn ein primäres Gateway-/WebChat-Modell nur Text unterstützt, bleiben Bildanhänge als ausgelagerte Referenzen vom Typ media://inbound/* erhalten. Dadurch können Bild-/PDF-Werkzeuge oder ein konfiguriertes Bildmodell sie weiterhin untersuchen, statt dass der Anhang verloren geht.
• Der explizite Aufruf openclaw infer image describe --file <path> --model <provider/model> (Alias: openclaw capability image describe) führt den bildfähigen Provider bzw. das bildfähige Modell direkt aus. Dies schließt Ollama-Referenzen wie ollama/qwen2.5vl:7b ein, wenn unter models.providers.ollama.models[] ein passendes bildfähiges Modell konfiguriert ist.
• Wenn <capability>.enabled nicht false ist, aber keine Modelle konfiguriert sind, versucht OpenClaw das aktive Antwortmodell, sofern dessen Provider die Fähigkeit unterstützt.

Automatische Erkennung (Standard)

Wenn tools.media.<capability>.enabled nicht false ist und keine Modelle konfiguriert sind, versucht OpenClaw die folgenden Optionen der Reihe nach und beendet die Suche bei der ersten funktionierenden Option:

So deaktivieren Sie die automatische Erkennung für eine Fähigkeit:

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

Proxy-Unterstützung (Provider-Aufrufe für Audio/Video)

Die Provider-basierte Analyse von Audio und Video berücksichtigt standardmäßige Umgebungsvariablen für ausgehende Proxys einschließlich der Umgehungsregeln NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Variablen in Kleinschreibung haben Vorrang vor solchen in Großschreibung. Wenn keine gesetzt ist, verwendet die Medienanalyse eine direkte ausgehende Verbindung. Ist der Proxy-Wert fehlerhaft, protokolliert OpenClaw eine Warnung und greift auf direkten Abruf zurück. Die Bildanalyse verwendet diesen Proxy-Pfad nicht.

Fähigkeiten

Legen Sie capabilities für einen Eintrag in models[] fest, um ihn auf bestimmte Medientypen zu beschränken. Bei gemeinsamen Listen leitet OpenClaw die Standardwerte für jeden mitgelieferten Provider ab:

Legen Sie für CLI-Einträge capabilities explizit fest, um unerwartete Zuordnungen zu vermeiden. Wird die Option ausgelassen, ist der Eintrag für jede Funktionsliste geeignet, in der er vorkommt.

Provider-Unterstützungsmatrix

Hinweise zur Modellauswahl

• Bevorzugen Sie für jede Medienfunktion das leistungsfähigste Modell der aktuellen Generation, wenn Qualität und Sicherheit wichtig sind.
• Vermeiden Sie bei Agenten mit Werkzeugzugriff, die nicht vertrauenswürdige Eingaben verarbeiten, ältere oder schwächere Medienmodelle.
• Behalten Sie für jede Funktion mindestens eine Ausweichoption zur Sicherstellung der Verfügbarkeit bei (Qualitätsmodell + schnelleres/günstigeres Modell).
• CLI-Ausweichoptionen (whisper-cli, whisper, gemini) helfen, wenn Provider-APIs nicht verfügbar sind.
• Bekannte Dateiausgabemodi sind maßgeblich: Eine leere oder fehlende abgeleitete Transkriptdatei erzeugt kein Transkript, statt auf die Fortschrittsausgabe der CLI zurückzugreifen.
• parakeet-mlx: Verwenden Sie --output-format txt (oder all) zusammen mit --output-dir und der standardmäßigen Ausgabevorlage {filename}. Die Upstream-Umgebungsvariablen PARAKEET_OUTPUT_FORMAT und PARAKEET_OUTPUT_TEMPLATE werden ebenfalls berücksichtigt. OpenClaw liest <output-dir>/<media-basename>.txt; beim Standardformat srt, bei anderen Formaten und bei benutzerdefinierten Ausgabevorlagen wird weiterhin die Standardausgabe verwendet.

Richtlinie für Anhänge

Das funktionsspezifische Feld attachments steuert, welche Anhänge verarbeitet werden:

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

Extraktion von Dateianhängen

• Extrahierter Dateitext wird als nicht vertrauenswürdiger externer Inhalt eingeschlossen, bevor er an den Medien-Prompt angehängt wird. Dazu werden Begrenzungsmarkierungen wie <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> sowie eine Metadatenzeile Source: External verwendet.
• Dieser Pfad lässt das lange Banner SECURITY NOTICE: absichtlich aus, um den Medien-Prompt kurz zu halten; die Begrenzungsmarkierungen und Metadaten werden weiterhin angewendet.
• Eine Datei ohne extrahierbaren Text erhält [Kein extrahierbarer Text].
• Wenn bei einer PDF-Datei ersatzweise gerenderte Seitenbilder verwendet werden, leitet OpenClaw diese Bilder an antwortende Modelle mit Bildverarbeitungsfähigkeit weiter und behält den Platzhalter [PDF-Inhalt als Bilder gerendert] im Dateiblock bei.

Konfigurationsbeispiele

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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"],          },        ],      },    },  },}

Statusausgabe

Wenn die Medienanalyse ausgeführt wird, enthält /status eine Zusammenfassungszeile je Funktion:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Führen Sie für die Vorabinventarisierung openclaw capability audio providers aus. Lokale Zeilen zeigen die ausgewählte lokale Ausweichoption getrennt von der globalen Provider-Auswahl, der Bereitschaft sowie den separaten Feldern für fähige, angeforderte und beobachtete Backends an. Dieselbe lokale Auswahl ist als informativer Doctor-Befund verfügbar:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Hinweise

• Die Analyse erfolgt nach bestem Bemühen. Fehler blockieren keine Antworten.
• Anhänge werden weiterhin an Modelle übergeben, auch wenn die Analyse deaktiviert ist.
• Verwenden Sie scope, um einzuschränken, wo die Analyse ausgeführt wird, beispielsweise nur in Direktnachrichten.

Verwandte Themen

• Konfiguration
• Unterstützung für Bilder und Medien