---
read_when:
    - Modifica della pipeline multimediale o degli allegati
summary: Regole di gestione di immagini e media per invio, Gateway e risposte degli agenti
title: Supporto per immagini e contenuti multimediali
x-i18n:
    generated_at: "2026-05-06T17:58:55Z"
    model: gpt-5.5
    provider: openai
    source_hash: 069140a3ad3bade166d4576ead604b4675006a01e546672872379ce83291471c
    source_path: nodes/images.md
    workflow: 16
---

Il canale WhatsApp funziona tramite **Baileys Web**. Questo documento descrive le regole attuali di gestione dei contenuti multimediali per invii, Gateway e risposte degli agenti.

## Obiettivi

- Inviare contenuti multimediali con didascalie opzionali tramite `openclaw message send --media`.
- Consentire alle risposte automatiche dalla casella in arrivo web di includere contenuti multimediali insieme al testo.
- Mantenere limiti per tipo sensati e prevedibili.

## Superficie CLI

- `openclaw message send --media <path-or-url> [--message <caption>]`
  - `--media` è opzionale; la didascalia può essere vuota per invii di soli contenuti multimediali.
  - `--dry-run` stampa il payload risolto; `--json` emette `{ channel, to, messageId, mediaUrl, caption }`.

## Comportamento del canale WhatsApp Web

- Input: percorso di file locale **oppure** URL HTTP(S).
- Flusso: carica in un Buffer, rileva il tipo di contenuto multimediale e costruisce il payload corretto:
  - **Immagini:** ridimensionamento e ricompressione in JPEG (lato massimo 2048 px) puntando a `channels.whatsapp.mediaMaxMb` (predefinito: 50 MB).
  - **Audio/voce/video:** pass-through fino a 16 MB; l'audio viene inviato come nota vocale (`ptt: true`).
  - **Documenti:** qualsiasi altra cosa, fino a 100 MB, con nome file preservato quando disponibile.
- Riproduzione in stile GIF su WhatsApp: invia un MP4 con `gifPlayback: true` (CLI: `--gif-playback`) così i client mobili lo riproducono in loop inline.
- Il rilevamento MIME preferisce i magic byte, poi gli header, poi l'estensione del file.
- La didascalia viene da `--message` o `reply.text`; è consentita una didascalia vuota.
- Logging: la modalità non dettagliata mostra `↩️`/`✅`; quella dettagliata include dimensione e percorso/URL di origine.

## Pipeline di risposta automatica

- `getReplyFromConfig` restituisce `{ text?, mediaUrl?, mediaUrls? }`.
- Quando sono presenti contenuti multimediali, il mittente web risolve percorsi locali o URL usando la stessa pipeline di `openclaw message send`.
- Se fornite, più voci multimediali vengono inviate in sequenza.

## Contenuti multimediali in ingresso verso i comandi (Pi)

- Quando i messaggi web in ingresso includono contenuti multimediali, OpenClaw li scarica in un file temporaneo ed espone variabili di templating:
  - pseudo-URL `{{MediaUrl}}` per il contenuto multimediale in ingresso.
  - percorso temporaneo locale `{{MediaPath}}` scritto prima di eseguire il comando.
- Quando è abilitata una sandbox Docker per sessione, i contenuti multimediali in ingresso vengono copiati nello spazio di lavoro della sandbox e `MediaPath`/`MediaUrl` vengono riscritti in un percorso relativo come `media/inbound/<filename>`.
- La comprensione dei contenuti multimediali (se configurata tramite `tools.media.*` o `tools.media.models` condivisi) viene eseguita prima del templating e può inserire blocchi `[Image]`, `[Audio]` e `[Video]` in `Body`.
  - L'audio imposta `{{Transcript}}` e usa la trascrizione per il parsing dei comandi, così i comandi slash continuano a funzionare.
  - Le descrizioni di video e immagini preservano eventuale testo della didascalia per il parsing dei comandi.
  - Se il modello di immagine primario attivo supporta già nativamente la visione, OpenClaw salta il blocco di riepilogo `[Image]` e passa invece l'immagine originale al modello.
- Per impostazione predefinita viene elaborato solo il primo allegato immagine/audio/video corrispondente; imposta `tools.media.<cap>.attachments` per elaborare più allegati.

## Limiti ed errori

**Limiti di invio in uscita (invio web WhatsApp)**

- Immagini: fino a `channels.whatsapp.mediaMaxMb` (predefinito: 50 MB) dopo la ricompressione.
- Audio/voce/video: limite di 16 MB; documenti: limite di 100 MB.
- Contenuti multimediali troppo grandi o illeggibili → errore chiaro nei log e la risposta viene saltata.

**Limiti di comprensione dei contenuti multimediali (trascrizione/descrizione)**

- Immagine predefinita: 10 MB (`tools.media.image.maxBytes`).
- Audio predefinito: 20 MB (`tools.media.audio.maxBytes`).
- Video predefinito: 50 MB (`tools.media.video.maxBytes`).
- I contenuti multimediali troppo grandi saltano la comprensione, ma le risposte vengono comunque inviate con il corpo originale.

## Note per i test

- Coprire i flussi di invio e risposta per i casi immagine/audio/documento.
- Convalidare la ricompressione per le immagini (limite di dimensione) e il flag di nota vocale per l'audio.
- Assicurare che le risposte con più contenuti multimediali si espandano in invii sequenziali.

## Correlati

- [Acquisizione fotocamera](/it/nodes/camera)
- [Comprensione dei contenuti multimediali](/it/nodes/media-understanding)
- [Audio e note vocali](/it/nodes/audio)