Compatibilidad con imágenes y contenido multimedia

El canal de WhatsApp se ejecuta sobre Baileys Web. Esta página abarca las reglas de gestión de contenido multimedia para los envíos, el Gateway y las respuestas del agente.

​

Objetivos

• Enviar contenido multimedia con una leyenda opcional mediante openclaw message send --media.
• Permitir que las respuestas automáticas de la bandeja de entrada web incluyan contenido multimedia junto con texto.
• Mantener límites razonables y predecibles para cada tipo.

​

Superficie de la CLI

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

• --media <path-or-url> — adjunta contenido multimedia (imagen/audio/vídeo/documento); acepta rutas locales o URL. Es opcional; la leyenda puede estar vacía para los envíos que solo contienen contenido multimedia.
• --gif-playback — trata el contenido multimedia de vídeo como una reproducción GIF (solo WhatsApp).
• --force-document — envía el contenido multimedia como documento para evitar la compresión del canal (Telegram, WhatsApp); se aplica a imágenes, GIF y vídeos.
• --reply-to <id>, --thread-id <id>, --pin, --silent — opciones de entrega y organización en hilos compartidas con los envíos de solo texto.
• --dry-run — muestra la carga útil resuelta y omite el envío.
• --json — muestra el resultado como JSON: { action, channel, dryRun, handledBy, messageId?, payload } (payload contiene el resultado del envío específico del canal, incluida cualquier referencia al contenido multimedia).

​

Comportamiento del canal web de WhatsApp

• Entrada: ruta de archivo local o URL HTTP(S).
• Flujo: se carga en un búfer, se detecta el tipo de contenido multimedia y, después, se crea la carga útil saliente correspondiente a cada tipo:
  • Imágenes: se optimizan para que no superen channels.whatsapp.mediaMaxMb (valor predeterminado: 50MB). Las imágenes opacas se vuelven a comprimir como JPEG (la secuencia predeterminada de dimensiones comienza en 2048px y disminuye cuando se incumple reiteradamente el límite de tamaño); las imágenes con transparencia se conservan como PNG. Si el origen ya es un archivo JPEG/PNG/WebP aceptable que respeta los límites de tamaño y longitud de los lados, los bytes originales se conservan sin cambios en lugar de volver a comprimirse. Los GIF animados nunca se vuelven a codificar; solo se comprueba su tamaño.
  • Audio/voz: salvo que ya sea audio de voz nativo (.ogg/.opus o audio/ogg/audio/opus), el audio saliente se transcodifica mediante ffmpeg a Opus/OGG (48kHz mono, 64kbps, limitado a 20 minutos) antes de enviarse como nota de voz (ptt: true).
  • Vídeo: se transmite sin cambios hasta 16MB.
  • Documentos: cualquier otro contenido, hasta 100MB, conservando el nombre del archivo cuando esté disponible.
• Reproducción al estilo GIF de WhatsApp: envía un MP4 con gifPlayback: true (CLI: --gif-playback) para que los clientes móviles lo reproduzcan en bucle en línea.
• La detección MIME da prioridad a los bytes mágicos detectados, después a la extensión del archivo y, por último, a los encabezados de respuesta; un contenedor genérico detectado (application/octet-stream, zip) nunca prevalece sobre una asignación de extensión más específica (por ejemplo, XLSX frente a ZIP).
• La leyenda procede de --message o reply.text; se permite una leyenda vacía.
• Registro: el modo no detallado muestra ↩️/✅; el modo detallado incluye el tamaño y la ruta/URL de origen.

​

Pipeline de respuestas automáticas

• getReplyFromConfig devuelve una carga útil de respuesta (o una matriz de cargas útiles) con text?, mediaUrl? y mediaUrls?, entre otros campos.
• Cuando hay contenido multimedia, el remitente web resuelve las rutas locales o las URL mediante el mismo Pipeline que openclaw message send.
• Si se proporcionan varias entradas de contenido multimedia, se envían de forma secuencial.

​

Contenido multimedia entrante en comandos

• Cuando los mensajes web entrantes incluyen contenido multimedia, OpenClaw lo descarga en un archivo temporal y expone variables de plantilla:
  • {{AttachmentUrl}} — URL original o referencia del proveedor correspondiente al archivo adjunto actual.
  • {{AttachmentPath}} — ruta temporal local escrita antes de ejecutar el comando.
  • {{AttachmentContentType}} — tipo de contenido MIME.
  • {{AttachmentDir}} — directorio que contiene la ruta local.
  • {{AttachmentIndex}} — índice de origen basado en cero.
• Cuando se habilita un entorno aislado de Docker por sesión, el contenido multimedia entrante se copia en el espacio de trabajo del entorno aislado y la ruta/referencia del archivo adjunto se reescribe como una ruta relativa al entorno aislado, como media/inbound/<filename>.
• {{MediaPath}}, {{MediaUrl}}, {{MediaType}} y {{MediaDir}} siguen siendo alias de compatibilidad obsoletos durante el período de migración del SDK de plugins.
• La comprensión de contenido multimedia (configurada mediante tools.media.* o el elemento compartido tools.media.models) se ejecuta antes de aplicar las plantillas y puede insertar bloques [Image], [Audio] y [Video] en Body.
  • El audio establece {{Transcript}} y utiliza la transcripción para analizar los comandos, de modo que los comandos de barra diagonal sigan funcionando.
  • Las descripciones de vídeos e imágenes conservan cualquier texto de la leyenda para analizar los comandos.
  • Si el modelo principal activo ya admite visión de forma nativa, OpenClaw omite el bloque de resumen [Image] y, en su lugar, pasa la imagen original al modelo.
• De forma predeterminada, solo se procesa el primer archivo adjunto coincidente de imagen/audio/vídeo; utilice tools.media.<capability>.attachments para seleccionar varios archivos adjuntos.

​

Límites y errores

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

• Imágenes: hasta channels.whatsapp.mediaMaxMb (valor predeterminado: 50MB) después de la optimización.
• Audio/vídeo: límite de 16MB (valor predeterminado compartido; se reemplaza por mediaMaxMb al enviar mediante WhatsApp).
• Documentos: límite de 100MB (valor predeterminado compartido; se reemplaza por mediaMaxMb al enviar mediante WhatsApp).
• El contenido multimedia demasiado grande o ilegible genera un error claro en los registros y se omite la respuesta.

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

• Valor predeterminado para imágenes: 10MB (se puede reemplazar con tools.media.image.maxBytes o, para cada entrada tools.media.models[], con maxBytes).
• Valor predeterminado para audio: 20MB (se puede reemplazar con tools.media.audio.maxBytes o por entrada).
• Valor predeterminado para vídeo: 50MB (se puede reemplazar con tools.media.video.maxBytes o por entrada).
• El contenido multimedia demasiado grande omite la fase de comprensión, pero la respuesta sigue procesándose con el cuerpo original.

​

Notas para las pruebas

• Cubrir los flujos de envío y respuesta para los casos de imagen, audio y documento.
• Validar los límites de tamaño después de la optimización de imágenes y el indicador de nota de voz para el audio.
• Garantizar que las respuestas con varios elementos multimedia se distribuyan como envíos secuenciales.

​

Contenido relacionado

• Captura de cámara
• Comprensión de contenido multimedia
• Audio y notas de voz