Gruppi di trasmissione

Stato: Sperimentale. Aggiunto nella versione 2026.1.9. Solo WhatsApp (canale web).

Panoramica

I gruppi broadcast eseguono più agenti sullo stesso messaggio in arrivo. Ogni agente elabora il messaggio nella propria sessione isolata e pubblica la propria risposta, quindi un singolo numero WhatsApp può ospitare un team di agenti specializzati in un’unica chat di gruppo o in un messaggio diretto. I gruppi broadcast vengono valutati dopo le liste di elementi consentiti del canale e le regole di attivazione dei gruppi. Nei gruppi WhatsApp, il broadcast avviene quando OpenClaw risponderebbe normalmente (ad esempio, in caso di menzione, a seconda delle impostazioni del gruppo). Modificano solo quali agenti vengono eseguiti, mai l’idoneità di un messaggio all’elaborazione. Il flusso QA WhatsApp live include whatsapp-broadcast-group-fanout, che verifica che un singolo messaggio di gruppo con menzione possa produrre risposte visibili distinte da due agenti configurati.

Configurazione

Configurazione di base

Aggiungi una sezione broadcast di primo livello (accanto a bindings). Le chiavi sono gli ID dei peer WhatsApp, mentre i valori sono array di ID agente:

chat di gruppo: JID del gruppo (ad es. 120363403215116621@g.us)
messaggi diretti: numero di telefono E.164 del mittente (ad es. +15551234567)

{
  "broadcast": {
    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
  }
}

Risultato: quando OpenClaw risponderebbe in questa chat, esegue tutti e tre gli agenti. Ogni ID agente elencato deve esistere in agents.list: la convalida della configurazione segnala gli ID sconosciuti e il runtime li ignora con un avviso Broadcast agent <id> not found in agents.list; skipping.

Strategia di elaborazione

broadcast.strategy stabilisce come gli agenti elaborano il messaggio:

Strategia	Comportamento
`parallel` (predefinita)	Tutti gli agenti elaborano simultaneamente; le risposte arrivano in qualsiasi ordine.
`sequential`	Gli agenti elaborano nell’ordine dell’array; ciascuno attende il completamento del precedente.

{
  "broadcast": {
    "strategy": "sequential",
    "120363403215116621@g.us": ["alfred", "baerbel"]
  }
}

Esempio completo

{
  "agents": {
    "list": [
      {
        "id": "code-reviewer",
        "name": "Code Reviewer",
        "workspace": "/path/to/code-reviewer",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "security-auditor",
        "name": "Security Auditor",
        "workspace": "/path/to/security-auditor",
        "sandbox": { "mode": "all" }
      },
      {
        "id": "docs-generator",
        "name": "Documentation Generator",
        "workspace": "/path/to/docs-generator",
        "sandbox": { "mode": "all" }
      }
    ]
  },
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
    "120363424282127706@g.us": ["support-en", "support-de"],
    "+15555550123": ["assistant", "logger"]
  }
}

Funzionamento

Flusso dei messaggi

Arriva un messaggio in ingresso

Arriva un messaggio da un gruppo WhatsApp o da un messaggio diretto.

Instradamento e ammissione

OpenClaw applica le liste di elementi consentiti del canale, le regole di attivazione dei gruppi e la proprietà dei binding ACP configurati.

Verifica del broadcast

Se nessun binding ACP configurato è proprietario della route, OpenClaw verifica se l’ID del peer è presente in broadcast.

Se si applica il broadcast

Tutti gli agenti elencati elaborano il messaggio.
Ogni agente dispone della propria chiave di sessione e di un contesto isolato.
Gli agenti elaborano in parallelo (impostazione predefinita) o in sequenza.
Gli allegati audio vengono trascritti una sola volta prima della distribuzione, così gli agenti condividono un’unica trascrizione anziché effettuare chiamate STT separate.

Se il broadcast non si applica

OpenClaw inoltra alla route ordinaria o alla route della sessione ACP configurata selezionata durante l’instradamento.

I gruppi broadcast non ignorano le liste di elementi consentiti del canale né le regole di attivazione dei gruppi (menzioni/comandi/ecc.). Modificano solo quali agenti vengono eseguiti quando un messaggio è idoneo all’elaborazione.

Isolamento delle sessioni

Ogni agente in un gruppo broadcast mantiene completamente separati:

Chiavi di sessione (agent:alfred:whatsapp:group:120363... rispetto a agent:baerbel:whatsapp:group:120363...)
Cronologia della conversazione (un agente non vede le risposte degli altri agenti)
Area di lavoro (sandbox separate, se configurate)
Accesso agli strumenti (elenchi di autorizzazioni/divieti differenti)
Memoria/contesto (IDENTITY.md, SOUL.md e così via separati)

Un’eccezione è intenzionalmente condivisa: il buffer del contesto di gruppo (i messaggi recenti del gruppo utilizzati come contesto) è condiviso per peer, quindi tutti gli agenti broadcast vedono lo stesso contesto quando vengono attivati. Viene svuotato una volta al termine della distribuzione. Ciò consente a ogni agente di avere personalità, modelli, Skills e accesso agli strumenti differenti (ad esempio, sola lettura rispetto a lettura e scrittura).

Esempio: sessioni isolate

Nel gruppo 120363403215116621@g.us con gli agenti ["alfred", "baerbel"]:

Contesto di Alfred
Contesto di Baerbel

Session: agent:alfred:whatsapp:group:120363403215116621@g.us
History: [user message, alfred's previous responses]
Workspace: ~/openclaw-alfred/
Tools: read, write, exec

Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
History: [user message, baerbel's previous responses]
Workspace: ~/openclaw-baerbel/
Tools: read only

Casi d’uso

Team di agenti specializzati: un gruppo di sviluppo in cui code-reviewer, security-auditor, test-generator e docs-checker rispondono ciascuno allo stesso messaggio dalla propria prospettiva.
Supporto multilingue: un’unica chat di supporto con support-en, support-de e support-es che rispondono nelle rispettive lingue.
Garanzia della qualità: support-agent risponde mentre qa-agent esamina la risposta e interviene solo quando rileva problemi.
Automazione delle attività: task-tracker, time-logger e report-generator elaborano tutti lo stesso aggiornamento di stato.

Procedure consigliate

1. Mantieni gli agenti focalizzati

Assegna a ciascun agente un’unica responsabilità chiara (formatter, linter, tester) anziché utilizzare un agente generico “dev-helper”.

2. Usa ID e nomi descrittivi

{
  "agents": {
    "list": [
      { "id": "security-scanner", "name": "Security Scanner" },
      { "id": "code-formatter", "name": "Code Formatter" },
      { "id": "test-generator", "name": "Test Generator" }
    ]
  }
}

3. Configura accessi agli strumenti differenti

{
  "agents": {
    "list": [
      { "id": "reviewer", "tools": { "allow": ["read", "exec"] } },
      { "id": "fixer", "tools": { "allow": ["read", "write", "edit", "exec"] } }
    ]
  }
}

reviewer dispone dell’accesso in sola lettura. fixer può leggere e scrivere.

4. Monitora le prestazioni

Con molti agenti, preferisci "strategy": "parallel" (impostazione predefinita), limita i gruppi broadcast a pochi agenti e usa modelli più veloci per gli agenti più semplici.

5. Gli errori restano isolati

Gli agenti possono generare errori in modo indipendente. L’errore di un agente viene registrato (Broadcast agent <id> failed: ...) e non blocca gli altri.

Compatibilità

Provider

I gruppi broadcast sono attualmente implementati solo per WhatsApp (canale web). Gli altri canali ignorano la configurazione broadcast.

Instradamento

I gruppi broadcast funzionano insieme all’instradamento esistente:

{
  "bindings": [
    {
      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
      "agentId": "alfred"
    }
  ],
  "broadcast": {
    "GROUP_B": ["agent1", "agent2"]
  }
}

GROUP_A: risponde solo alfred (instradamento normale).
GROUP_B: rispondono agent1 E agent2 (broadcast).

Precedenza: broadcast ha priorità sui binding di route ordinari. I binding ACP configurati (bindings[].type="acp") sono esclusivi: quando uno corrisponde, OpenClaw inoltra alla sessione ACP configurata anziché eseguire la distribuzione broadcast.

Risoluzione dei problemi

Gli agenti non rispondono

Verifica:

Gli ID agente esistono in agents.list (la convalida della configurazione rifiuta gli ID sconosciuti).
Il formato dell’ID peer è corretto (un JID di gruppo come 120363403215116621@g.us oppure un numero E.164 come +15551234567 per i messaggi diretti).
Il messaggio ha superato i normali controlli di ammissione (le regole di menzione/attivazione continuano ad applicarsi).

Debug:

openclaw logs --follow | grep -i broadcast

Una distribuzione riuscita registra Broadcasting message to <n> agents (<strategy>).

Risponde un solo agente

Causa: l’ID peer potrebbe essere presente nei binding di route ordinari ma non in broadcast, oppure potrebbe corrispondere a un binding ACP configurato esclusivo.Soluzione: aggiungi alla configurazione broadcast i peer associati a route ordinarie oppure rimuovi/modifica il binding ACP configurato se desideri la distribuzione broadcast.

Problemi di prestazioni

Se le prestazioni sono lente con molti agenti: riduci il numero di agenti per gruppo, usa modelli più leggeri e controlla il tempo di avvio della sandbox.

Esempi

Esempio 1: Team di revisione del codice

{
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": [
      "code-formatter",
      "security-scanner",
      "test-coverage",
      "docs-checker"
    ]
  },
  "agents": {
    "list": [
      {
        "id": "code-formatter",
        "workspace": "~/agents/formatter",
        "tools": { "allow": ["read", "write"] }
      },
      {
        "id": "security-scanner",
        "workspace": "~/agents/security",
        "tools": { "allow": ["read", "exec"] }
      },
      {
        "id": "test-coverage",
        "workspace": "~/agents/testing",
        "tools": { "allow": ["read", "exec"] }
      },
      { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
    ]
  }
}

Un singolo frammento di codice nel gruppo produce quattro risposte: correzioni di formattazione, un problema di sicurezza, una lacuna nella copertura e un’osservazione minore sulla documentazione.

Esempio 2: Pipeline multilingue

{
  "broadcast": {
    "strategy": "sequential",
    "+15555550123": ["detect-language", "translator-en", "translator-de"]
  },
  "agents": {
    "list": [
      { "id": "detect-language", "workspace": "~/agents/lang-detect" },
      { "id": "translator-en", "workspace": "~/agents/translate-en" },
      { "id": "translator-de", "workspace": "~/agents/translate-de" }
    ]
  }
}

Riferimento API

Schema di configurazione

interface OpenClawConfig {
  broadcast?: {
    strategy?: "parallel" | "sequential";
    [peerId: string]: string[];
  };
}

Campi

"parallel" | "sequential"

predefinito:"\"parallel\""

Modalità di elaborazione degli agenti. parallel esegue tutti gli agenti simultaneamente; sequential li esegue nell’ordine dell’array.

string[]

JID del gruppo WhatsApp o numero di telefono E.164. Il valore è l’array degli ID degli agenti che devono elaborare tutti i messaggi provenienti da quel peer.

Limitazioni

Numero massimo di agenti: non esiste un limite rigido, ma molti agenti (10 o più) possono rallentare l’elaborazione.
Contesto condiviso: gli agenti non vedono le risposte reciproche (per progettazione).
Ordine dei messaggi: le risposte parallele possono arrivare in qualsiasi ordine.
Limiti di frequenza: tutte le risposte provengono da un unico account WhatsApp, quindi la risposta di ogni agente contribuisce agli stessi limiti di frequenza di WhatsApp.

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Gruppi di trasmissione

Panoramica

Configurazione

Configurazione di base

Strategia di elaborazione

Esempio completo

Funzionamento

Flusso dei messaggi

Isolamento delle sessioni

Esempio: sessioni isolate

Casi d’uso

Procedure consigliate

Compatibilità

Provider

Instradamento

Risoluzione dei problemi

Esempi

Riferimento API

Schema di configurazione

Campi

Limitazioni

Argomenti correlati

​Panoramica

​Configurazione

​Configurazione di base

​Strategia di elaborazione

​Esempio completo

​Funzionamento

​Flusso dei messaggi

​Isolamento delle sessioni

​Esempio: sessioni isolate

​Casi d’uso

​Procedure consigliate

​Compatibilità

​Provider

​Instradamento

​Risoluzione dei problemi

​Esempi

​Riferimento API

​Schema di configurazione

​Campi

​Limitazioni

​Argomenti correlati

Panoramica

Configurazione

Configurazione di base

Strategia di elaborazione

Esempio completo

Funzionamento

Flusso dei messaggi

Isolamento delle sessioni

Esempio: sessioni isolate

Casi d’uso

Procedure consigliate

Compatibilità

Provider

Instradamento

Risoluzione dei problemi

Esempi

Riferimento API

Schema di configurazione

Campi

Limitazioni

Argomenti correlati