Gruppi

OpenClaw applica le stesse regole per i gruppi a tutti i canali che supportano i gruppi, inclusi Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp e Zalo.

Per le stanze sempre attive che devono fornire un contesto discreto, a meno che l'agente non invii esplicitamente un messaggio visibile, vedere Eventi ambientali delle stanze.

Introduzione per principianti (2 minuti)

OpenClaw "vive" negli account di messaggistica dell'utente. Non esiste un utente bot WhatsApp separato: se l'utente fa parte di un gruppo, OpenClaw può vedere quel gruppo e rispondere al suo interno.

Comportamento predefinito:

• I gruppi sono soggetti a restrizioni (groupPolicy: "allowlist"); i mittenti dei gruppi vengono bloccati finché non vengono inseriti nell'elenco consentiti.
• Le risposte richiedono una menzione, a meno che il filtro delle menzioni non venga disabilitato per un gruppo.
• Il testo della risposta finale viene pubblicato automaticamente nella stanza (visibleReplies: "automatic").

In altre parole: i mittenti nell'elenco consentiti possono attivare OpenClaw menzionandolo.

Flusso rapido (cosa accade a un messaggio di gruppo):

groupPolicy? disabled -> ignoragroupPolicy? allowlist -> gruppo consentito? no -> ignorarequireMention? yes -> menzionato? no -> memorizza solo come contestomenzione/risposta/comando/messaggio diretto -> richiesta dell'utenteconversazione di gruppo sempre attiva -> richiesta dell'utente oppure evento della stanza, se configurato

Risposte visibili

Per le normali richieste di gruppo/canale, il valore predefinito di OpenClaw è messages.groupChat.visibleReplies: "automatic": il testo finale dell'assistente viene pubblicato nella stanza come risposta visibile.

Usare messages.groupChat.visibleReplies: "message_tool" quando una stanza condivisa deve consentire all'agente di decidere quando intervenire chiamando message(action=send). Questa modalità funziona meglio con modelli che usano gli strumenti in modo affidabile (ad esempio GPT-5.6 Sol). Se il modello non usa lo strumento e restituisce un testo finale sostanziale, OpenClaw mantiene privato tale testo anziché pubblicarlo nella stanza.

Usare "automatic" per modelli o runtime che non rispettano in modo affidabile la consegna esclusivamente tramite strumenti: i normali testi finali vengono pubblicati direttamente nella stanza e l'agente può comunque chiamare message(action=send) per file, immagini o altri allegati che non possono essere inclusi nel testo finale.

Se lo strumento per i messaggi non è disponibile in base ai criteri degli strumenti attivi, OpenClaw ripiega sulle risposte visibili automatiche anziché sopprimere silenziosamente la risposta. openclaw doctor segnala questa mancata corrispondenza.

Per le chat dirette e qualsiasi altro evento di origine, messages.visibleReplies: "message_tool" applica globalmente lo stesso comportamento esclusivamente tramite strumenti; messages.groupChat.visibleReplies rimane l'override più specifico per le stanze di gruppo/canale. I turni diretti interni di WebChat usano per impostazione predefinita la consegna automatica della risposta finale, affinché Pi e Codex ricevano lo stesso contratto per le risposte visibili.

La modalità esclusivamente tramite strumenti sostituisce il vecchio schema che imponeva al modello di rispondere NO_REPLY per la maggior parte dei turni in modalità di osservazione passiva. In questa modalità, il prompt non definisce un contratto NO_REPLY; non rendere visibile alcunché significa semplicemente non chiamare lo strumento per i messaggi.

I binding delle conversazioni gestiti dai Plugin costituiscono un'eccezione. Dopo che un Plugin associa un thread e prende in carico il turno in ingresso, la risposta restituita dal Plugin è la risposta visibile del binding e non richiede message(action=send). Tale risposta è un output del runtime del Plugin, non il testo finale privato del modello.

Gli indicatori di digitazione vengono comunque inviati per le richieste dirette nei gruppi. Gli eventi ambientali delle stanze sempre attive, quando abilitati, rimangono rigorosamente silenziosi a meno che l'agente non chiami lo strumento per i messaggi.

Per impostazione predefinita, le sessioni sopprimono i riepiloghi dettagliati degli strumenti e dell'avanzamento. Usare /verbose on (o /verbose full) per mostrarli nella sessione corrente durante il debug e /verbose off per tornare al comportamento con sole risposte finali. Lo stato dettagliato è specifico per ogni sessione e funziona allo stesso modo nelle chat dirette, nei gruppi, nei canali e negli argomenti dei forum.

Per inviare le conversazioni di gruppo sempre attive prive di menzioni come contesto discreto della stanza anziché come richieste dell'utente, usare Eventi ambientali delle stanze:

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

Il valore predefinito è unmentionedInbound: "user_request". I messaggi con menzioni, i comandi, le richieste di interruzione e i messaggi diretti rimangono richieste dell'utente.

Per richiedere che l'output visibile delle richieste di gruppo/canale venga inviato tramite lo strumento per i messaggi:

{  messages: {    groupChat: {      visibleReplies: "message_tool",    },  },}

Per richiederlo per ogni chat di origine:

{  messages: {    visibleReplies: "message_tool",  },}

Il Gateway rileva le modifiche alla configurazione messages senza riavvio dopo il salvataggio del file. Riavviare solo quando il ricaricamento della configurazione è disabilitato (gateway.reload.mode: "off").

I turni di comando ignorano visibleReplies: "message_tool" e rispondono sempre in modo visibile: sia i comandi slash nativi (Discord, Telegram e altre interfacce con supporto nativo dei comandi) sia i comandi testuali /... autorizzati pubblicano la propria risposta nella chat di origine. I turni testuali /... non autorizzati nei gruppi rimangono limitati allo strumento per i messaggi; i normali turni di chat seguono l'impostazione predefinita configurata.

Visibilità del contesto ed elenchi consentiti

La sicurezza dei gruppi prevede due controlli distinti:

• Autorizzazione all'attivazione: chi può attivare l'agente (groupPolicy, groups, groupAllowFrom, elenchi consentiti specifici per canale).
• Visibilità del contesto: quale contesto supplementare viene inserito nel modello (testo di risposte/citazioni, cronologia dei thread, metadati inoltrati).

Per impostazione predefinita, OpenClaw conserva il contesto così come viene ricevuto: gli elenchi consentiti determinano chi può attivare le azioni, non quali frammenti citati o storici siano visibili al modello. Per filtrare anche il contesto supplementare, impostare contextVisibility:

Impostarlo per canale (channels.<channel>.contextVisibility), per account (channels.<channel>.accounts.<accountId>.contextVisibility) o globalmente (channels.defaults.contextVisibility). I canali che recuperano il contesto supplementare (Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp) applicano i criteri durante la creazione del contesto in ingresso; le combinazioni di criteri sconosciute adottano un comportamento restrittivo e omettono il contesto.

Se si desidera...

Per gli elenchi consentiti riutilizzabili dei mittenti, vedere Gruppi di accesso.

Chiavi di sessione

• Le sessioni di gruppo usano chiavi di sessione agent:<agentId>:<channel>:group:<id> (le stanze/i canali usano agent:<agentId>:<channel>:channel:<id>).
• Gli argomenti dei forum di Telegram aggiungono :topic:<threadId> all'id del gruppo, affinché ogni argomento disponga di una propria sessione.
• Le chat dirette usano la sessione principale (oppure sessioni per mittente, se è configurato session.dmScope).
• Gli Heartbeat vengono eseguiti nella sessione Heartbeat configurata (impostazione predefinita: la sessione principale dell'agente); le sessioni di gruppo non eseguono Heartbeat propri.

Schema: messaggi diretti personali + gruppi pubblici (agente singolo)

Sì: questa configurazione funziona bene se il traffico "personale" è costituito da messaggi diretti e quello "pubblico" da gruppi.

Motivo: in modalità con agente singolo, i messaggi diretti vengono generalmente inseriti nella chiave della sessione principale (agent:main:main), mentre i gruppi usano sempre chiavi di sessione non principali (agent:main:<channel>:group:<id>). Se si abilita l'esecuzione in sandbox con mode: "non-main", tali sessioni di gruppo vengono eseguite nel backend sandbox configurato, mentre la sessione principale dei messaggi diretti rimane sull'host. Docker è il backend predefinito se non ne viene scelto uno.

Si ottiene così un unico "cervello" dell'agente (spazio di lavoro + memoria condivisi), ma due modalità di esecuzione:

• Messaggi diretti: strumenti completi (host)
• Gruppi: sandbox + strumenti con restrizioni

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // i gruppi/canali non sono principali -> vengono eseguiti in sandbox        scope: "session", // isolamento massimo (un container per gruppo/canale)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // Se allow non è vuoto, tutto il resto viene bloccato (deny continua ad avere la precedenza).        allow: ["group:messaging", "group:sessions"],        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],      },    },  },}

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",        docker: {          binds: [            // hostPath:containerPath:mode            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

Contenuti correlati:

• Chiavi di configurazione e valori predefiniti: Configurazione del Gateway
• Debug dei motivi per cui uno strumento è bloccato: Sandbox, criteri degli strumenti ed esecuzione con privilegi elevati
• Dettagli sui montaggi bind: Esecuzione in sandbox

Etichette di visualizzazione

• Le etichette dell'interfaccia utente usano displayName quando disponibile, nel formato <channel>:<token>.
• #room è riservato alle stanze/ai canali; le chat di gruppo usano g-<slug> (minuscolo, spazi -> -, mantenere #@+._-). Gli id opachi molto lunghi vengono abbreviati in un token stabile anziché mostrare nell'interfaccia utente gli id completi delle route.

Criteri per i gruppi

Controllare la gestione dei messaggi di gruppo/stanza per ciascun canale:

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // ID utente numerico di Telegram (la configurazione risolve @username)    },    signal: {      groupPolicy: "disabled",      groupAllowFrom: ["+15551234567"],    },    imessage: {      groupPolicy: "disabled",      groupAllowFrom: ["chat_id:123"],    },    msteams: {      groupPolicy: "disabled",      groupAllowFrom: ["user@org.com"],    },    discord: {      groupPolicy: "allowlist",      guilds: {        GUILD_ID: { channels: { help: { enabled: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { enabled: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

Modello mentale rapido (ordine di valutazione dei messaggi di gruppo):

Filtro per menzione (predefinito)

I messaggi di gruppo richiedono una menzione, salvo diversa configurazione per il singolo gruppo. I valori predefiniti si trovano per ogni sottosistema in *.groups."*".

Rispondere a un messaggio del bot vale come menzione implicita quando il canale espone i metadati della risposta; anche citare un messaggio del bot può valere come menzione nei canali che espongono i metadati della citazione. Casi integrati attuali: Discord, Microsoft Teams, QQBot, Slack, Telegram, WhatsApp e Zalo personale.

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },        "123@g.us": { requireMention: false },      },    },    telegram: {      groups: {        "*": { requireMention: true },        "123456789": { requireMention: false },      },    },    imessage: {      groups: {        "*": { requireMention: true },        "123": { requireMention: false },      },    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],          historyLimit: 50,        },      },    ],  },}

Definire l'ambito dei modelli di menzione configurati

I mentionPatterns configurati sono espressioni regolari usate come attivatori di ripiego. Vanno usati quando la piattaforma non espone una menzione nativa del bot o quando si desidera che testo normale come openclaw: valga come menzione. Le menzioni native della piattaforma sono distinte: quando Discord, Slack, Telegram, Matrix, Signal o un altro canale può dimostrare che il messaggio ha menzionato esplicitamente il bot, tale menzione nativa attiva comunque l'agente anche se i modelli di espressioni regolari configurati sono negati.

Per impostazione predefinita, i modelli di menzione configurati si applicano ovunque il canale trasmetta i dati relativi al provider e alla conversazione al rilevamento delle menzioni. Per evitare che modelli generici attivino l'agente in ogni gruppo, definirne l'ambito per canale con channels.<channel>.mentionPatterns.

Usare mode: "deny" quando i modelli di menzione basati su espressioni regolari devono essere disattivati per impostazione predefinita in un canale, quindi abilitarli in stanze specifiche con allowIn:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

Usare il valore predefinito mode: "allow" (oppure omettere mode) quando i modelli di menzione basati su espressioni regolari devono applicarsi in modo esteso, quindi disattivarli nelle stanze molto attive con denyIn:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

Risoluzione del criterio:

Criteri con ambito per espressioni regolari attualmente supportati:

Le configurazioni dei canali a livello di account possono impostare lo stesso criterio in channels.<channel>.accounts.<accountId>.mentionPatterns quando il canale supporta più account. Per tale account, il criterio dell'account ha la precedenza sul criterio del canale di primo livello.

Restrizioni degli strumenti per gruppo/canale (facoltative)

Alcune configurazioni dei canali consentono di limitare gli strumenti disponibili all'interno di uno specifico gruppo/stanza/canale.

• tools: consente/nega gli strumenti per l'intero gruppo (allow, alsoAllow, deny; la negazione prevale).
• toolsBySender: sostituzioni per singolo mittente all'interno del gruppo. Usare prefissi di chiave espliciti: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> e il carattere jolly "*". Gli ID dei canali usano gli ID canonici dei canali OpenClaw; gli alias come teams vengono normalizzati in msteams. Le chiavi legacy senza prefisso sono ancora accettate, corrispondono solo come id: e generano un avviso di deprecazione nel registro.

Ordine di risoluzione (prevale il più specifico):

Esempio (Telegram):

{  channels: {    telegram: {      groups: {        "*": { tools: { deny: ["exec"] } },        "-1001234567890": {          tools: { deny: ["exec", "read", "write"] },          toolsBySender: {            "id:123456789": { alsoAllow: ["exec"] },          },        },      },    },  },}

Elenchi di autorizzazione dei gruppi

Quando è configurato channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups, le chiavi fungono da elenco di autorizzazione dei gruppi. Usare "*" per consentire tutti i gruppi continuando a impostare il comportamento predefinito per le menzioni.

Configurazioni comuni (copiare e incollare):

{  channels: { whatsapp: { groupPolicy: "disabled" } },}

{  channels: {    whatsapp: {      groups: {        "123@g.us": { requireMention: true },        "456@g.us": { requireMention: false },      },    },  },}

{  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

{  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15551234567"],      groups: { "*": { requireMention: true } },    },  },}

Attivazione (solo proprietario)

I proprietari dei gruppi possono attivare o disattivare l'attivazione per ciascun gruppo con un messaggio autonomo:

• /activation mention
• /activation always

/activation è un comando principale riservato al proprietario e si applica solo alle chat di gruppo. Per proprietario si intende un mittente che corrisponde a commands.ownerAllowFrom; gli elenchi allowFrom del canale controllano solo l'accesso ordinario al canale e ai comandi. La modalità memorizzata sostituisce il valore requireMention del gruppo nei canali che la consultano (Google Chat, QQBot, Telegram, WhatsApp) e l'introduzione del prompt di sistema del gruppo riflette ovunque la modalità attiva.

Campi del contesto

I payload in ingresso dei gruppi impostano:

• ChatType=group
• GroupSubject (se noto)
• GroupMembers (se noto)
• WasMentioned (risultato del controllo delle menzioni)
• Gli argomenti dei forum Telegram includono anche MessageThreadId e IsForum.

Il prompt di sistema dell'agente include un'introduzione al gruppo nel primo turno di una nuova sessione di gruppo (e dopo la modifica di /activation). Ricorda al modello di rispondere come una persona, ridurre al minimo le righe vuote, rispettare la normale spaziatura delle chat ed evitare di digitare sequenze letterali \n. I canali la cui modalità tabella dichiarata non conserva le tabelle native o non elaborate sconsigliano anche l'uso delle tabelle Markdown. I nomi dei gruppi e le etichette dei partecipanti provenienti dai canali vengono visualizzati come metadati non attendibili delimitati, non come istruzioni di sistema incorporate.

Dettagli specifici di iMessage

• Preferire chat_id:<id> per l'instradamento o l'inserimento negli elenchi di autorizzazione.
• Elencare le chat: imsg chats --limit 20.
• Le risposte di gruppo vengono sempre inviate allo stesso chat_id.

Prompt di sistema di WhatsApp

Consultare WhatsApp per le regole canoniche dei prompt di sistema di WhatsApp, incluse la risoluzione dei prompt di gruppo e diretti, il comportamento dei caratteri jolly e la semantica delle sostituzioni a livello di account.

Dettagli specifici di WhatsApp

Consultare Messaggi di gruppo per il comportamento specifico di WhatsApp (inserimento della cronologia e dettagli sulla gestione delle menzioni).

Argomenti correlati

• Gruppi di trasmissione
• Instradamento dei canali
• Messaggi di gruppo
• Associazione