Bild- & Medien-Support — 05.12.2025

Der WhatsApp Channel läuft über Baileys Web. Dieses Dokument beschreibt die aktuellen Regeln für die Medienverarbeitung beim Senden, im Gateway und bei Agent-Antworten.

Ziele

  • Medien mit optionalen Bildunterschriften über openclaw message send --media versenden.
  • Auto-Antworten aus dem Web-Posteingang können Medien zusammen mit Text enthalten.
  • Pro-Typ-Limits sinnvoll und vorhersehbar halten.

CLI-Oberfläche

  • openclaw message send --media <path-or-url> [--message <caption>]
    • --media ist optional; Bildunterschrift kann leer sein für reine Medien-Sends.
    • --dry-run gibt die aufgelöste Payload aus; --json liefert { channel, to, messageId, mediaUrl, caption }.

WhatsApp Web Channel Verhalten

  • Input: lokaler Dateipfad oder HTTP(S)-URL.
  • Ablauf: Laden in einen Buffer, Medientyp erkennen und die richtige Payload erstellen:
    • Bilder: Größe ändern & neu komprimieren zu JPEG (max. Seitenlänge 2048px), Zielgröße agents.defaults.mediaMaxMb (Standard 5 MB), begrenzt auf 6 MB.
    • Audio/Voice/Video: Durchreichen bis 16 MB; Audio wird als Sprachnachricht gesendet (ptt: true).
    • Dokumente: alles andere, bis 100 MB, mit erhaltenem Dateinamen wenn verfügbar.
  • WhatsApp GIF-Style-Wiedergabe: MP4 mit gifPlayback: true senden (CLI: --gif-playback), damit mobile Clients inline loopen.
  • MIME-Erkennung bevorzugt Magic Bytes, dann Headers, dann Dateiendung.
  • Bildunterschrift kommt von --message oder reply.text; leere Bildunterschrift ist erlaubt.
  • Logging: nicht-verbose zeigt ↩️/✅; verbose enthält Größe und Quellpfad/URL.

Auto-Reply Pipeline

  • getReplyFromConfig gibt { text?, mediaUrl?, mediaUrls? } zurück.
  • Wenn Medien vorhanden sind, löst der Web-Sender lokale Pfade oder URLs mit der gleichen Pipeline wie openclaw message send auf.
  • Mehrere Medieneinträge werden nacheinander gesendet, falls vorhanden.

Eingehende Medien zu Commands (Pi)

  • Wenn eingehende Web-Nachrichten Medien enthalten, lädt OpenClaw diese in eine temporäre Datei herunter und stellt Template-Variablen bereit:
    • {{MediaUrl}} Pseudo-URL für die eingehenden Medien.
    • {{MediaPath}} lokaler Temp-Pfad, der vor dem Ausführen des Befehls geschrieben wird.
  • Wenn eine per-Session Docker Sandbox aktiviert ist, werden eingehende Medien in den Sandbox Workspace kopiert und MediaPath/MediaUrl werden zu einem relativen Pfad wie media/inbound/<filename> umgeschrieben.
  • Media Understanding (falls konfiguriert über tools.media.* oder shared tools.media.models) läuft vor dem Templating und kann [Image], [Audio] und [Video] Blöcke in Body einfügen.
    • Audio setzt {{Transcript}} und nutzt das Transkript für Command-Parsing, sodass Slash-Commands weiterhin funktionieren.
    • Video- und Bildbeschreibungen erhalten jeden Bildunterschriftstext für Command-Parsing.
  • Standardmäßig wird nur das erste passende Image/Audio/Video-Attachment verarbeitet; setze tools.media.<cap>.attachments, um mehrere Attachments zu verarbeiten.

Limits & Fehler

Outbound Send Caps (WhatsApp Web Send)

  • Bilder: ~6 MB Cap nach Rekompression.
  • Audio/Voice/Video: 16 MB Cap; Dokumente: 100 MB Cap.
  • Zu große oder unlesbare Medien → klare Fehlermeldung in den Logs und die Antwort wird übersprungen.

Media Understanding Caps (Transkription/Beschreibung)

  • Bilder Standard: 10 MB (tools.media.image.maxBytes).
  • Audio Standard: 20 MB (tools.media.audio.maxBytes).
  • Video Standard: 50 MB (tools.media.video.maxBytes).
  • Zu große Medien überspringen das Understanding, aber Antworten gehen trotzdem mit dem ursprünglichen Body durch.

Hinweise für Tests

  • Decke Send + Reply Flows für Bild/Audio/Dokument-Fälle ab.
  • Validiere Rekompression für Bilder (Größenbegrenzung) und Voice-Note-Flag für Audio.
  • Stelle sicher, dass Multi-Media-Antworten als sequenzielle Sends ausgefächert werden.