Soporte de imágenes y medios — 2025-12-05

El canal de WhatsApp funciona vía Baileys Web. Este documento describe las reglas actuales de manejo de medios para envío, gateway y respuestas del agente.

Objetivos

• Enviar medios con subtítulos opcionales mediante openclaw message send --media.
• Permitir que las respuestas automáticas desde la bandeja web incluyan medios junto con texto.
• Mantener límites por tipo razonables y predecibles.

Superficie CLI

• openclaw message send --media <ruta-o-url> [--message <subtítulo>]
  • --media es opcional; el subtítulo puede estar vacío para envíos de solo medios.
  • --dry-run imprime el payload resuelto; --json emite { channel, to, messageId, mediaUrl, caption }.

Comportamiento del canal WhatsApp Web

• Entrada: ruta de archivo local o URL HTTP(S).
• Flujo: cargar en un Buffer, detectar el tipo de medio y construir el payload correcto:
  • Imágenes: redimensionar y recomprimir a JPEG (lado máximo 2048px) buscando agents.defaults.mediaMaxMb (por defecto 5 MB), con tope en 6 MB.
  • Audio/Voz/Video: paso directo hasta 16 MB; el audio se envía como nota de voz (ptt: true).
  • Documentos: cualquier otra cosa, hasta 100 MB, con nombre de archivo preservado cuando esté disponible.
• Reproducción tipo GIF en WhatsApp: envía un MP4 con gifPlayback: true (CLI: --gif-playback) para que los clientes móviles lo reproduzcan en bucle.
• La detección MIME prefiere bytes mágicos, luego headers, luego extensión de archivo.
• El subtítulo proviene de --message o reply.text; se permite subtítulo vacío.
• Registro: sin verbose muestra ↩️/✅; verbose incluye tamaño y ruta/URL de origen.

Pipeline de respuesta automática

• getReplyFromConfig devuelve { text?, mediaUrl?, mediaUrls? }.
• Cuando hay medios presentes, el remitente web resuelve rutas locales o URLs usando el mismo pipeline que openclaw message send.
• Las entradas de medios múltiples se envían secuencialmente si se proporcionan.

Medios entrantes a comandos (Pi)

• Cuando los mensajes web entrantes incluyen medios, OpenClaw los descarga a un archivo temporal y expone variables de plantilla:
  • {{MediaUrl}} pseudo-URL del medio entrante.
  • {{MediaPath}} ruta temporal local escrita antes de ejecutar el comando.
• Cuando un sandbox Docker por sesión está habilitado, el medio entrante se copia al workspace del sandbox y MediaPath/MediaUrl se reescriben a una ruta relativa como media/inbound/<nombre-archivo>.
• La comprensión de medios (si se configura mediante tools.media.* o tools.media.models compartido) se ejecuta antes del procesamiento de plantillas y puede insertar bloques [Image], [Audio] y [Video] en Body.
  • Audio establece {{Transcript}} y usa la transcripción para el análisis de comandos, de modo que los comandos slash sigan funcionando.
  • Las descripciones de video e imagen preservan cualquier texto de subtítulo para el análisis de comandos.
• Por defecto solo se procesa el primer adjunto coincidente de imagen/audio/video; configura tools.media.<cap>.attachments para procesar múltiples adjuntos.

Límites y errores

Límites de envío saliente (envío web de WhatsApp)

• Imágenes: ~6 MB de tope tras recompresión.
• Audio/voz/video: 16 MB de tope; documentos: 100 MB de tope.
• Medios sobredimensionados o ilegibles → error claro en logs y la respuesta se omite.

Límites de comprensión de medios (transcripción/descripción)

• Imagen por defecto: 10 MB (tools.media.image.maxBytes).
• Audio por defecto: 20 MB (tools.media.audio.maxBytes).
• Video por defecto: 50 MB (tools.media.video.maxBytes).
• Los medios sobredimensionados omiten la comprensión, pero las respuestas siguen con el cuerpo original.

Notas para pruebas

• Cubrir flujos de envío + respuesta para casos de imagen/audio/documento.
• Validar recompresión de imágenes (límite de tamaño) y flag de nota de voz para audio.
• Asegurar que las respuestas con múltiples medios se distribuyan como envíos secuenciales.