Bild- & Medienunterstützung — 2025-12-05

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

Ziele

• Medien mit optionaler Bildunterschrift über openclaw message send --media senden.
• 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 optional; Bildunterschrift kann für reine Mediensendungen leer sein.
  • --dry-run gibt den aufgelösten Payload aus; --json liefert { channel, to, messageId, mediaUrl, caption }.

WhatsApp-Web-Kanalverhalten

• Eingabe: lokaler Dateipfad oder HTTP(S)-URL.
• Ablauf: In einen Buffer laden, Medienart erkennen und den korrekten Payload erstellen:
  • Bilder: Größe ändern & als JPEG rekomprimieren (max. Seite 2048px), Ziel agents.defaults.mediaMaxMb (Standard 5 MB), begrenzt auf 6 MB.
  • Audio/Voice/Video: Durchreichung bis 16 MB; Audio wird als Sprachnachricht gesendet (ptt: true).
  • Dokumente: alles andere, bis 100 MB, mit Dateinamen wenn verfügbar.
• WhatsApp-GIF-Wiedergabe: Ein MP4 mit gifPlayback: true senden (CLI: --gif-playback), damit mobile Clients es als Schleife inline abspielen.
• MIME-Erkennung bevorzugt Magic Bytes, dann Header, dann Dateiendung.
• Bildunterschrift kommt von --message oder reply.text; leere Bildunterschrift ist erlaubt.
• Logging: Ohne Verbose wird ↩️/✅ angezeigt; Verbose enthält Größe und Quellpfad/-URL.

Auto-Antwort-Pipeline

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

Eingehende Medien zu Befehlen (Pi)

• Wenn eingehende Web-Nachrichten Medien enthalten, lädt OpenClaw sie in eine temporäre Datei herunter und stellt Template-Variablen bereit:
  • {{MediaUrl}} Pseudo-URL für das eingehende Medium.
  • {{MediaPath}} lokaler temporärer Pfad, der vor dem Befehl geschrieben wird.
• Wenn eine sitzungsbezogene Docker-Sandbox aktiviert ist, werden eingehende Medien in den Sandbox-Workspace kopiert und MediaPath/MediaUrl werden auf einen relativen Pfad wie media/inbound/<filename> umgeschrieben.
• Media Understanding (wenn über tools.media.* oder geteilte tools.media.models konfiguriert) läuft vor dem Templating und kann [Image]-, [Audio]- und [Video]-Blöcke in Body einfügen.
  • Audio setzt {{Transcript}} und verwendet das Transkript für die Befehlserkennung, sodass Slash-Befehle weiterhin funktionieren.
  • Video- und Bildbeschreibungen bewahren jeglichen Bildunterschrift-Text für die Befehlserkennung.
• Standardmäßig wird nur der erste passende Bild-/Audio-/Video-Anhang verarbeitet; setze tools.media.<cap>.attachments, um mehrere Anhänge zu verarbeiten.

Limits und Fehler

Ausgehende Sendelimits (WhatsApp-Web-Versand)

• Bilder: ~6 MB Limit nach Rekomprimierung.
• Audio/Voice/Video: 16 MB Limit; Dokumente: 100 MB Limit.
• Zu große oder nicht lesbare Medien → klarer Fehler in den Logs und die Antwort wird übersprungen.

Media-Understanding-Limits (Transkription/Beschreibung)

• Bild-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 werden trotzdem mit dem Original-Body gesendet.

Hinweise für Tests

• Sende- und Antwort-Flows für Bild-/Audio-/Dokument-Fälle abdecken.
• Rekomprimierung für Bilder (Größenlimit) und Sprachnachrichten-Flag für Audio validieren.
• Sicherstellen, dass Multi-Media-Antworten als sequenzielle Sendungen aufgefächert werden.