Medienverständnis

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

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

Funktionsweise

Konfiguration

tools.media enthält eine einzige nach Fähigkeiten gekennzeichnete Modellliste sowie kompakte Steuerungsoptionen pro Fähigkeit:

{  tools: {    media: {      concurrency: 2, // maximale Anzahl gleichzeitiger Fähigkeitsausführungen (Standard)      models: [        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["image", "video"] },      ],      image: { preferredModel: "google/gemini-3-flash-preview" },      audio: { enabled: true },      video: { enabled: true },    },  },}

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

Prompts, Limits, Sprachhinweise, Anfrageüberschreibungen und Provider-Optionen können als Standardwerte einer Fähigkeit festgelegt oder in einzelnen tools.media.models[]-Einträgen überschrieben werden. Die Standardwerte einer Fähigkeit gelten auch für automatisch erkannte Provider, wenn kein explizites Modell konfiguriert ist.

Modelleinträge

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

{  type: "provider", // Standard, wenn nicht angegeben  provider: "openai",  model: "gpt-5.6-sol",  prompt: "Beschreiben Sie das Bild in <= 500 Zeichen.",  maxChars: 500,  maxBytes: 10485760,  timeoutSeconds: 60,  capabilities: ["image"],  profile: "vision-profile",  preferredProfile: "vision-fallback",}

{  type: "cli",  command: "gemini",  args: [    "-m",    "gemini-3-flash",    "--allowed-tools",    "read_file",    "Lesen Sie das Medium unter {{AttachmentPath}} und beschreiben Sie es in <= {{MaxChars}} Zeichen.",  ],  maxChars: 500,  maxBytes: 52428800,  timeoutSeconds: 120,  capabilities: ["video", "image"],}

Provider-Anmeldedaten

Das Medienverständnis über Provider verwendet dieselbe Authentifizierungsauflösung wie normale Modellaufrufe: Authentifizierungsprofile, Umgebungsvariablen und anschließend models.providers.<providerId>.apiKey. tools.media.models[]-Einträge akzeptieren kein eingebettetes apiKey-Feld.

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

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

Regeln und Verhalten

• Medien, die maxBytes überschreiten, werden für dieses Modell übersprungen; anschließend wird das nächste versucht.
• Audiodateien mit weniger als 1024 Bytes werden als leer/beschädigt behandelt und vor der Transkription übersprungen; der Agent erhält stattdessen ein deterministisches Platzhaltertranskript.
• Wenn das aktive primäre Bildmodell Vision bereits nativ unterstützt, überspringt OpenClaw den [Image]-Zusammenfassungsblock und übergibt das Originalbild direkt an das Modell. MiniMax bildet eine Ausnahme: minimax, minimax-cn, minimax-portal und minimax-portal-cn leiten das Bildverständnis immer über den Plugin-eigenen Medien-Provider MiniMax-VL-01, selbst wenn ältere MiniMax-M2.x-Chatmetadaten Bildeingaben angeben (nur MiniMax-M3 und neuere Versionen gelten als nativ visionfähig).
• Wenn ein primäres Gateway-/WebChat-Modell nur Text unterstützt, bleiben Bildanhänge als ausgelagerte media://inbound/*-Referenzen erhalten, damit Bild-/PDF-Tools oder ein konfiguriertes Bildmodell sie weiterhin untersuchen können, statt den Anhang zu verlieren.
• Ein explizites openclaw infer image describe --file <path> --model <provider/model> (Alias: openclaw capability image describe) führt diesen bildfähigen Provider bzw. dieses Modell direkt aus, einschließlich Ollama-Referenzen wie ollama/qwen2.5vl:7b, 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)

Provider-basiertes Audio- und Video-Understanding berücksichtigt die üblichen 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 Kleinbuchstaben haben Vorrang vor solchen in Großbuchstaben. Wenn keine festgelegt sind, verwendet das Medienverständnis einen direkten ausgehenden Zugriff. Ist der Proxy-Wert fehlerhaft, protokolliert OpenClaw eine Warnung und greift auf einen direkten Abruf zurück. Das Bildverständnis verwendet diesen Proxy-Pfad nicht.

Fähigkeiten

Legen Sie capabilities in einem models[]-Eintrag fest, um ihn auf bestimmte Medientypen zu beschränken. Für gemeinsam genutzte Listen leitet OpenClaw die Standardwerte pro gebündeltem Provider ab:

Legen Sie für CLI-Einträge capabilities explizit fest, um unerwartete Übereinstimmungen zu vermeiden; wird die Angabe ausgelassen, kommt der Eintrag für jede Funktionsliste infrage, in der er erscheint.

Provider-Unterstützungsmatrix

Hinweise zur Modellauswahl

• Bevorzugen Sie für jede Medienfunktion das leistungsstärkste 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.
• Halten Sie für die Verfügbarkeit mindestens ein Ausweichmodell pro Funktion bereit (Qualitätsmodell + schnelleres/günstigeres Modell).
• CLI-Ausweichlösungen (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 CLI-Fortschrittsausgabe zurückzugreifen.
• parakeet-mlx: Verwenden Sie --output-format txt (oder all) mit --output-dir und der standardmäßigen Ausgabevorlage {filename}. Die vorgelagerten Umgebungsvariablen PARAKEET_OUTPUT_FORMAT und PARAKEET_OUTPUT_TEMPLATE werden ebenfalls berücksichtigt. OpenClaw liest <output-dir>/<media-basename>.txt; das standardmäßige Format srt, andere Formate und benutzerdefinierte Ausgabevorlagen verwenden weiterhin stdout.

Richtlinie für Anhänge

Die funktionsspezifische Einstellung attachments steuert, welche Anhänge verarbeitet werden:

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

Extraktion aus Dateianhängen

• Extrahierter Dateitext wird als nicht vertrauenswürdiger externer Inhalt umschlossen, bevor er an den Medien-Prompt angehängt wird. Dabei 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 gelten weiterhin.
• Eine Datei ohne extrahierbaren Text erhält [No extractable text].
• Wenn bei einer PDF-Datei ersatzweise gerenderte Seitenbilder verwendet werden, leitet OpenClaw diese Bilder an antwortende Modelle mit Bildverarbeitung weiter und behält den Platzhalter [PDF content rendered to images] 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",            "Lies die Mediendatei unter {{AttachmentPath}} und beschreibe sie in höchstens {{MaxChars}} Zeichen.",          ],          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", "{{AttachmentPath}}"],          },        ],      },      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",              "Lies die Mediendatei unter {{AttachmentPath}} und beschreibe sie in höchstens {{MaxChars}} Zeichen.",            ],          },        ],      },    },  },}

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.6-sol" },          { provider: "anthropic", model: "claude-opus-5" },          {            type: "cli",            command: "gemini",            args: [              "-m",              "gemini-3-flash",              "--allowed-tools",              "read_file",              "Lies die Mediendatei unter {{AttachmentPath}} und beschreibe sie in höchstens {{MaxChars}} Zeichen.",            ],          },        ],      },    },  },}

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

📎 Medien: Bild ok (openai/gpt-5.6-sol) · Audio ok (whisper-cli beobachtet=metal)

Führen Sie für die Vorab-Bestandsaufnahme openclaw capability audio providers aus. Lokale Zeilen zeigen die lokale Ausweichlösung getrennt von der globalen Provider-Auswahl, der Bereitschaft und den separaten Feldern für fähiges/angefordertes/beobachtetes Backend. Dieselbe lokale Auswahl ist als informative Doctor-Feststellung 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 auch dann an Modelle übergeben, 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