Medienverständnis

OpenClaw kann eingehende Medien zusammenfassen (Bild/Audio/Video), bevor die Antwort-Pipeline ausgeführt wird. Es erkennt automatisch, wenn lokale Tools oder Provider-Schlüssel verfügbar sind, und kann deaktiviert oder angepasst werden. Wenn das Verstehen ausgeschaltet ist, erhalten Modelle weiterhin wie gewohnt die ursprünglichen Dateien/URLs.

Anbieterspezifisches Medienverhalten wird von Vendor-Plugins registriert, während der OpenClaw-Core die gemeinsame tools.media-Konfiguration, die Fallback-Reihenfolge und die Integration in die Antwort-Pipeline besitzt.

Ziele

• Optional: eingehende Medien vorab in kurzen Text verdichten, für schnelleres Routing und besseres Command-Parsing.
• Ursprüngliche Medienübermittlung an das Modell beibehalten (immer).
• Provider-APIs und CLI-Fallbacks unterstützen.
• Mehrere Modelle mit geordnetem Fallback erlauben (Fehler/Größe/Timeout).

Verhalten auf hoher Ebene

Wenn das Verstehen fehlschlägt oder deaktiviert ist, läuft der Antwortfluss weiter mit dem ursprünglichen Body und den Anhängen.

Konfigurationsübersicht

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

{  tools: {    media: {      models: [        /* shared list */      ],      image: {        /* optional overrides */      },      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {        /* optional overrides */      },    },  },}

Modelleinträge

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

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

Provider-Anmeldedaten (apiKey)

Provider-Medienverständnis verwendet dieselbe Provider-Authentifizierungsauflösung wie normale Modellaufrufe: Authentifizierungsprofile, Umgebungsvariablen, dann models.providers.<providerId>.apiKey.

tools.media.*.models[]-Einträge akzeptieren kein Inline-Feld apiKey. Der provider-Wert in einem Medienmodelleintrag, zum Beispiel openai oder moonshot, muss über eine der standardmäßigen Provider-Authentifizierungsquellen verfügbare Anmeldedaten haben.

Minimales Beispiel:

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

Die vollständige Referenz zur Provider-Authentifizierung, einschließlich Profilen, Umgebungsvariablen und benutzerdefinierten Basis-URLs, finden Sie unter Tools und benutzerdefinierte Provider.

Standardwerte und Limits

Empfohlene Standardwerte:

• maxChars: 500 für Bild/Video (kurz, befehlsfreundlich)
• maxChars: nicht gesetzt für Audio (vollständiges Transkript, sofern Sie kein Limit festlegen)
• maxBytes:
  • image: 10MB
  • audio: 20MB
  • video: 50MB

Medienverständnis automatisch erkennen (Standard)

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

Um die automatische Erkennung zu deaktivieren, setzen Sie:

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

Proxy-Umgebungsunterstützung (Provider-Modelle)

Wenn Provider-basiertes Audio- und Video-Medienverständnis aktiviert ist, berücksichtigt OpenClaw standardmäßige ausgehende Proxy-Umgebungsvariablen für Provider-HTTP-Aufrufe:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

Wenn keine Proxy-Umgebungsvariablen gesetzt sind, verwendet das Medienverständnis direkten ausgehenden Zugriff. Wenn der Proxy-Wert fehlerhaft formatiert ist, protokolliert OpenClaw eine Warnung und fällt auf direkten Abruf zurück.

Fähigkeiten (optional)

Wenn Sie capabilities setzen, wird der Eintrag nur für diese Medientypen ausgeführt. Für gemeinsam genutzte Listen kann OpenClaw Standardwerte ableiten:

• openai, anthropic, minimax: Bild
• minimax-portal: Bild
• moonshot: Bild + Video
• openrouter: Bild + Audio
• google (Gemini API): Bild + Audio + Video
• qwen: Bild + Video
• mistral: Audio
• zai: Bild
• groq: Audio
• xai: Audio
• deepgram: Audio
• Jeder models.providers.<id>.models[]-Katalog mit einem bildfähigen Modell: Bild

Für CLI-Einträge sollten Sie capabilities explizit setzen, um überraschende Übereinstimmungen zu vermeiden. Wenn Sie capabilities weglassen, ist der Eintrag für die Liste berechtigt, in der er erscheint.

Provider-Unterstützungsmatrix (OpenClaw-Integrationen)

Hinweise zur Modellauswahl

• Bevorzugen Sie für jede Medienfähigkeit das stärkste verfügbare Modell der neuesten Generation, wenn Qualität und Sicherheit wichtig sind.
• Vermeiden Sie für Tool-fähige Agenten, die nicht vertrauenswürdige Eingaben verarbeiten, ältere oder schwächere Medienmodelle.
• Behalten Sie mindestens einen Fallback pro Fähigkeit für die Verfügbarkeit bei (Qualitätsmodell + schnelleres/günstigeres Modell).
• CLI-Fallbacks (whisper-cli, whisper, gemini) sind nützlich, wenn Provider-APIs nicht verfügbar sind.
• Hinweis zu parakeet-mlx: Mit --output-dir liest OpenClaw <output-dir>/<media-basename>.txt, wenn das Ausgabeformat txt ist (oder nicht angegeben wurde); Nicht-txt-Formate fallen auf stdout zurück.

Richtlinie für Anhänge

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

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

Konfigurationsbeispiele

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

Statusausgabe

Wenn Medienverständnis ausgeführt wird, enthält /status eine kurze Zusammenfassungszeile:

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

Dies zeigt Ergebnisse pro Fähigkeit und, sofern zutreffend, den ausgewählten Provider/das ausgewählte Modell.

Hinweise

• Das Verständnis erfolgt nach bestem Bemühen. Fehler blockieren Antworten nicht.
• Anhänge werden weiterhin an Modelle übergeben, auch wenn das Verständnis deaktiviert ist.
• Verwenden Sie scope, um einzuschränken, wo Verständnis ausgeführt wird (z. B. nur in DMs).

Verwandte Themen

• Konfiguration
• Bild- und Medienunterstützung