Gruppi

OpenClaw tratta le chat di gruppo in modo coerente su tutte le superfici: Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo.

Per le stanze sempre attive che devono fornire contesto silenzioso a meno che l'agente non invii esplicitamente un messaggio visibile, consulta Eventi ambientali della stanza.

Introduzione per principianti (2 minuti)

OpenClaw "vive" sui tuoi account di messaggistica. Non esiste un utente bot WhatsApp separato. Se tu sei in un gruppo, OpenClaw può vedere quel gruppo e rispondere lì.

Comportamento predefinito:

• I gruppi sono limitati (groupPolicy: "allowlist").
• Le risposte richiedono una menzione, a meno che tu non disabiliti esplicitamente il gating delle menzioni.
• Le risposte visibili nei gruppi/canali usano lo strumento message per impostazione predefinita.

Traduzione: i mittenti in allowlist possono attivare OpenClaw menzionandolo.

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

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlymention/reply/command/DM -> user requestalways-on group chatter -> user request, or room event when configured

Risposte visibili

Per le normali richieste di gruppo/canale, OpenClaw usa per impostazione predefinita messages.groupChat.visibleReplies: "automatic". Il testo finale dell'assistente viene pubblicato tramite il percorso legacy delle risposte visibili, a meno che tu non configuri la stanza per usare solo l'output tramite strumento message.

Usa messages.groupChat.visibleReplies: "message_tool" quando una stanza condivisa deve lasciare che sia l'agente a decidere quando parlare chiamando message(action=send). Funziona meglio per le stanze di gruppo supportate da modelli di ultima generazione e affidabili con gli strumenti, come GPT 5.5. Se il modello non usa quello strumento e restituisce testo finale sostanziale, OpenClaw mantiene privato quel testo finale invece di pubblicarlo nella stanza.

Usa "automatic" per modelli più deboli o runtime che non comprendono in modo affidabile la consegna solo tramite strumento. In modalità automatica, il testo finale dell'assistente è il percorso della risposta visibile alla fonte, quindi un modello che non riesce a chiamare in modo coerente message(action=send) può comunque rispondere normalmente.

In modalità automatica, le normali risposte finali testuali vengono pubblicate direttamente nella stanza. Se la risposta visibile richiede file, immagini o altri allegati, l'agente può comunque usare message(action=send) per quell'allegato invece di provare a forzarlo nella risposta testuale finale.

Se lo strumento message non è disponibile con la policy degli strumenti attiva, OpenClaw ripiega sulle risposte visibili automatiche invece di sopprimere silenziosamente la risposta. openclaw doctor avvisa di questa mancata corrispondenza.

Per le chat dirette e qualsiasi altro evento sorgente, usa messages.visibleReplies: "message_tool" per applicare globalmente lo stesso comportamento di risposta visibile solo tramite strumento. I turni diretti interni di WebChat usano per impostazione predefinita la consegna automatica della risposta finale, così Pi e Codex ricevono lo stesso contratto di risposta visibile. Imposta messages.visibleReplies: "message_tool" per richiedere intenzionalmente message(action=send) per l'output visibile. messages.groupChat.visibleReplies resta l'override più specifico per le stanze di gruppo/canale.

Questo sostituisce il vecchio schema che costringeva il modello a rispondere NO_REPLY per la maggior parte dei turni in modalità lurk. In modalità solo tramite strumento, il prompt non definisce un contratto NO_REPLY. Non fare nulla di visibile significa semplicemente non chiamare lo strumento message.

I binding di conversazione di proprietà dei Plugin sono l'eccezione. Una volta che un Plugin associa un thread e rivendica il turno in ingresso, la risposta restituita dal Plugin è la risposta visibile del binding; non richiede message(action=send). Quella risposta è output del runtime del Plugin, non testo finale privato del modello.

Gli indicatori di digitazione vengono comunque inviati per le richieste dirette di gruppo. Gli eventi ambientali delle stanze sempre attive, quando abilitati, rimangono rigorosi e silenziosi a meno che l'agente non chiami lo strumento message.

Le sessioni sopprimono per impostazione predefinita i riepiloghi dettagliati di strumenti/avanzamento. Usa /verbose on per mostrare questi riepiloghi per la sessione corrente durante il debug, e /verbose off per tornare al comportamento con sole risposte finali. Lo stesso stato verbose si applica a chat dirette, gruppi, canali e argomenti dei forum.

Per inviare le conversazioni di gruppo sempre attive non menzionate come contesto silenzioso della stanza invece che come richieste utente, usa Eventi ambientali della stanza:

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

L'impostazione predefinita è unmentionedInbound: "user_request".

I messaggi menzionati, i comandi, le richieste di interruzione e i DM rimangono richieste utente.

Per richiedere che l'output visibile passi attraverso lo strumento message per le richieste di gruppo/canale:

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

Il gateway ricarica a caldo la configurazione messages dopo il salvataggio del file. Riavvia solo quando il monitoraggio dei file o il ricaricamento della configurazione è disabilitato nel deployment.

Per richiedere che l'output visibile passi attraverso lo strumento message per ogni chat sorgente:

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

I comandi slash nativi (Discord, Telegram e altre superfici con supporto per comandi nativi) ignorano visibleReplies: "message_tool" e rispondono sempre in modo visibile, così l'interfaccia comandi nativa del canale riceve la risposta prevista. Questo si applica solo ai turni di comando nativi validati; i comandi /... digitati come testo e i normali turni di chat continuano a seguire l'impostazione predefinita del gruppo configurata.

Visibilità del contesto ed elenchi consentiti

Nella sicurezza dei gruppi sono coinvolti due controlli diversi:

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

Per impostazione predefinita, OpenClaw dà priorità al normale comportamento della chat e mantiene il contesto per lo più così come ricevuto. Questo significa che gli elenchi consentiti decidono principalmente chi può attivare azioni, non un confine universale di redazione per ogni frammento citato o storico.

Se vuoi...

Per elenchi consentiti di mittenti riutilizzabili, consulta Gruppi di accesso.

Chiavi di sessione

• Le sessioni di gruppo usano chiavi di sessione agent:<agentId>:<channel>:group:<id> (stanze/canali usano agent:<agentId>:<channel>:channel:<id>).
• Gli argomenti dei forum Telegram aggiungono :topic:<threadId> all'id del gruppo, così ogni argomento ha la propria sessione.
• Le chat dirette usano la sessione principale (o una sessione per mittente, se configurata).
• Gli Heartbeat vengono saltati per le sessioni di gruppo.

Schema: DM personali + gruppi pubblici (agente singolo)

Sì: funziona bene se il traffico "personale" è costituito da DM e il traffico "pubblico" da gruppi.

Motivo: in modalità agente singolo, i DM in genere finiscono nella chiave di sessione principale (agent:main:main), mentre i gruppi usano sempre chiavi di sessione non principali (agent:main:<channel>:group:<id>). Se abiliti il sandboxing con mode: "non-main", quelle sessioni di gruppo vengono eseguite nel backend sandbox configurato mentre la sessione DM principale resta sull'host. Docker è il backend predefinito se non ne scegli uno.

Questo ti dà un unico "cervello" dell'agente (workspace + memoria condivisi), ma due posture di esecuzione:

• DM: strumenti completi (host)
• Gruppi: sandbox + strumenti limitati

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // groups/channels are non-main -> sandboxed        scope: "session", // strongest isolation (one container per group/channel)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // If allow is non-empty, everything else is blocked (deny still wins).        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",          ],        },      },    },  },}

Correlati:

• Chiavi di configurazione e valori predefiniti: Configurazione del Gateway
• Debug del motivo per cui uno strumento è bloccato: Sandbox vs criteri degli strumenti vs elevazione
• Dettagli dei mount bind: Sandboxing

Etichette di visualizzazione

• Le etichette dell'interfaccia usano displayName quando disponibile, formattato come <channel>:<token>.
• #room è riservato a stanze/canali; le chat di gruppo usano g-<slug> (minuscolo, spazi -> -, mantiene #@+._-).

Criterio di gruppo

Controlla come vengono gestiti i messaggi di gruppo/stanza per canale:

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @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: { allow: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { allow: 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 per i messaggi di gruppo):

Gating delle menzioni (predefinito)

I messaggi di gruppo richiedono una menzione, salvo override per gruppo. I valori predefiniti risiedono per sottosistema sotto *.groups."*".

Rispondere a un messaggio del bot conta come menzione implicita quando il canale supporta i metadati di risposta. Anche citare un messaggio del bot può contare come menzione implicita nei canali che espongono metadati di citazione. I casi integrati attuali includono Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser.

{  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 pattern di menzione configurati

I mentionPatterns configurati sono trigger regex di fallback. Usali quando la piattaforma non espone una menzione nativa del bot oppure quando vuoi che testo semplice come openclaw: conti come menzione. Le menzioni native della piattaforma sono separate: quando Discord, Slack, Telegram, Matrix o un altro canale può provare che il messaggio ha menzionato esplicitamente il bot, quella menzione nativa attiva comunque il bot anche se i pattern regex configurati sono negati.

Per impostazione predefinita, i pattern di menzione configurati si applicano ovunque quel canale passi i fatti di provider e conversazione al rilevamento delle menzioni. Per evitare che pattern ampi risveglino l'agente in ogni gruppo, definiscine l'ambito per canale con channels.<channel>.mentionPatterns.

Usa mode: "deny" quando i pattern regex di menzione devono essere disattivati per impostazione predefinita per un canale, poi abilita stanze specifiche con allowIn:

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

Usa il mode: "allow" predefinito (oppure ometti mode) quando i pattern regex di menzione devono applicarsi ampiamente, poi disattivali nelle stanze rumorose con denyIn:

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

Risoluzione del criterio:

Criterio regex con ambito supportato oggi:

Le configurazioni di canale a livello di account possono impostare lo stesso criterio sotto channels.<channel>.accounts.<accountId>.mentionPatterns quando quel canale supporta più account. Il criterio dell'account ha precedenza sul criterio di canale di primo livello per quell'account.

Restrizioni degli strumenti per gruppo/canale (facoltativo)

Alcune configurazioni di canale supportano la limitazione degli strumenti disponibili all'interno di uno specifico gruppo/stanza/canale.

• tools: consente/nega strumenti per l'intero gruppo.
• toolsBySender: override per mittente all'interno del gruppo. Usa prefissi di chiave espliciti: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> e carattere jolly "*". Gli ID canale usano gli ID canale canonici di OpenClaw; alias come teams vengono normalizzati in msteams. Le chiavi legacy senza prefisso sono ancora accettate e corrispondono solo come id:.

Ordine di risoluzione (vince il più specifico):

Esempio (Telegram):

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

Allowlist di gruppo

Quando channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups è configurato, le chiavi agiscono come allowlist di gruppo. Usa "*" per consentire tutti i gruppi continuando a impostare il comportamento predefinito delle menzioni.

Intenti comuni (copia/incolla):

{  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 gruppo:

• /activation mention
• /activation always

Il proprietario è determinato da channels.whatsapp.allowFrom (o dall'E.164 del bot stesso quando non è impostato). Invia il comando come messaggio autonomo. Le altre superfici attualmente ignorano /activation.

Campi di contesto

I payload in ingresso dei gruppi impostano:

• ChatType=group
• GroupSubject (se noto)
• GroupMembers (se noto)
• WasMentioned (risultato del controllo di menzione)
• Anche gli argomenti del forum Telegram includono MessageThreadId e IsForum.

Il prompt di sistema dell'agente include un'introduzione al gruppo al primo turno di una nuova sessione di gruppo. Ricorda al modello di rispondere come una persona, ridurre al minimo le righe vuote e seguire la normale spaziatura della chat, evitando di digitare sequenze letterali \n. I gruppi non Telegram sconsigliano anche le tabelle Markdown; le indicazioni sul testo ricco di Telegram provengono dal prompt del canale Telegram. I nomi dei gruppi e le etichette dei partecipanti provenienti dal canale vengono renderizzati come metadati non attendibili racchiusi in blocchi delimitati, non come istruzioni di sistema in linea.

Specifiche di iMessage

• Preferisci chat_id:<id> per il routing o l'inserimento nella lista consentita.
• Elenca le chat: imsg chats --limit 20.
• Le risposte di gruppo tornano sempre allo stesso chat_id.

Prompt di sistema WhatsApp

Vedi WhatsApp per le regole canoniche dei prompt di sistema WhatsApp, incluse la risoluzione dei prompt di gruppo e diretti, il comportamento dei caratteri jolly e la semantica di override dell'account.

Specifiche di WhatsApp

Vedi Messaggi di gruppo per il comportamento solo WhatsApp (iniezione della cronologia, dettagli sulla gestione delle menzioni).

Correlati

• Gruppi broadcast
• Routing dei canali
• Messaggi di gruppo
• Abbinamento