OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Configuration

Gruppi di trasmissione

Status: experimental

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)
json
{  "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.
json
{  "broadcast": {    "strategy": "sequential",    "120363403215116621@g.us": ["alfred", "baerbel"]  }}

Esempio completo

json
{  "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.

    • 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

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

    Contesto di Baerbel

    text
    Session: agent:baerbel:whatsapp:group:120363403215116621@g.usHistory: [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
    json
    {  "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
    json
    {  "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:

    json
    {  "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).

    Risoluzione dei problemi

    Gli agenti non rispondono

    Verifica:

    1. Gli ID agente esistono in agents.list (la convalida della configurazione rifiuta gli ID sconosciuti).
    2. 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).
    3. Il messaggio ha superato i normali controlli di ammissione (le regole di menzione/attivazione continuano ad applicarsi).

    Debug:

    bash
    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
    json
    {  "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
    json
    {  "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

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

    Campi

    strategy"parallel" | "sequential"default: "parallel"

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

    [peerId]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

    1. Numero massimo di agenti: non esiste un limite rigido, ma molti agenti (10 o più) possono rallentare l'elaborazione.
    2. Contesto condiviso: gli agenti non vedono le risposte reciproche (per progettazione).
    3. Ordine dei messaggi: le risposte parallele possono arrivare in qualsiasi ordine.
    4. 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.

    Argomenti correlati

    Was this useful?
    On this page

    On this page