Gruppi

OpenClaw gestisce le chat di gruppo in modo coerente tra le piattaforme: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams, Zalo.

Introduzione per principianti (2 minuti)

OpenClaw “vive” sui tuoi account di messaggistica. Non c’e un utente bot WhatsApp separato. Se tu sei in un gruppo, OpenClaw puo vedere quel gruppo e rispondere li.

Comportamento predefinito:

I gruppi sono limitati (groupPolicy: "allowlist").
Le risposte richiedono una menzione a meno che tu non disabiliti esplicitamente il gating menzione.

Traduzione pratica: i mittenti in allowlist possono attivare OpenClaw menzionandolo.

TL;DR

Accesso DM e controllato da *.allowFrom.

Accesso gruppi e controllato da *.groupPolicy + allowlist (*.groups, *.groupAllowFrom).

Attivazione risposte e controllata dal gating menzione (requireMention, /activation).

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

groupPolicy? disabled -> scarta
groupPolicy? allowlist -> gruppo consentito? no -> scarta
requireMention? yes -> menzionato? no -> salva solo come contesto
altrimenti -> rispondi

Flusso messaggi di gruppo

Se vuoi…

Obiettivo	Cosa impostare
Consentire tutti i gruppi ma rispondere solo alle @menzioni	`groups: { "*": { requireMention: true } }`
Disabilitare tutte le risposte nei gruppi	`groupPolicy: "disabled"`
Solo gruppi specifici	`groups: { "<group-id>": { ... } }` (nessuna chiave `"*"`)
Solo tu puoi attivare nei gruppi	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Chiavi di sessione

Le sessioni di gruppo usano chiavi di sessione agent:<agentId>:<channel>:group:<id> (le stanze/canali usano agent:<agentId>:<channel>:channel:<id>).
I topic dei forum Telegram aggiungono :topic:<threadId> all’id del gruppo cosi ogni topic ha la sua sessione.
Le chat dirette usano la sessione principale (o per mittente se configurato).
Gli heartbeat sono saltati per le sessioni di gruppo.

Pattern: DM personali + gruppi pubblici (agent singolo)

Si — funziona bene se il tuo traffico “personale” sono DM e il tuo traffico “pubblico” sono gruppi.

Perche: in modalita agent singolo, i DM tipicamente finiscono nella chiave di sessione main (agent:main:main), mentre i gruppi usano sempre chiavi di sessione non-main (agent:main:<channel>:group:<id>). Se abiliti il sandboxing con mode: "non-main", quelle sessioni di gruppo girano in Docker mentre la tua sessione DM principale resta sull’host.

Questo ti da un “cervello” dell’agent (workspace + memoria condivisi), ma due posture di esecuzione:

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

Se hai bisogno di workspace/personaggi veramente separati (“personale” e “pubblico” non devono mai mescolarsi), usa un secondo agent + binding. Vedi Routing multi-agent.

Esempio (DM sull’host, gruppi in sandbox + solo strumenti di messaggistica):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // gruppi/canali sono non-main -> sandboxati
        scope: "session", // isolamento piu forte (un container per gruppo/canale)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // Se allow non e vuoto, tutto il resto e bloccato (deny vince comunque).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

Vuoi “i gruppi possono vedere solo la cartella X” invece di “nessun accesso host”? Mantieni workspaceAccess: "none" e monta solo i percorsi consentiti nel sandbox:

{
  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 gateway
Debug perche uno strumento e bloccato: Sandbox vs Tool Policy vs Elevated
Dettagli bind mount: Sandboxing

Etichette di visualizzazione

Le etichette UI usano displayName quando disponibile, formattate come <channel>:<token>.
#room e riservato per stanze/canali; le chat di gruppo usano g-<slug> (minuscolo, spazi -> -, mantieni #@+._-).

Policy di gruppo

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

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // id utente Telegram numerico (il wizard puo risolvere @username)
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["[email protected]"],
    },
    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": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

Policy	Comportamento
`"open"`	I gruppi bypassano le allowlist; il gating menzione resta attivo.
`"disabled"`	Blocca tutti i messaggi di gruppo.
`"allowlist"`	Consenti solo gruppi/stanze che corrispondono all’allowlist configurata.

Note:

groupPolicy e separato dal gating menzione (che richiede @menzioni).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: usano groupAllowFrom (fallback: allowFrom esplicito).
Le approvazioni pairing DM (*-allowFrom nel store) si applicano solo all’accesso DM; l’autorizzazione mittente dei gruppi resta esplicita nelle allowlist di gruppo.
Discord: l’allowlist usa channels.discord.guilds.<id>.channels.
Slack: l’allowlist usa channels.slack.channels.
Matrix: l’allowlist usa channels.matrix.groups (ID stanza, alias o nomi). Usa channels.matrix.groupAllowFrom per limitare i mittenti; sono supportate anche allowlist users per stanza.
I DM di gruppo sono controllati separatamente (channels.discord.dm.*, channels.slack.dm.*).
L’allowlist Telegram puo corrispondere a ID utente ("123456789", "telegram:123456789", "tg:123456789") o username ("@alice" o "alice"); i prefissi sono case-insensitive.
Il valore predefinito e groupPolicy: "allowlist"; se la tua allowlist di gruppo e vuota, i messaggi di gruppo sono bloccati.
Sicurezza runtime: quando un blocco provider manca completamente (channels.<provider> assente), la policy di gruppo torna a una modalita fail-closed (tipicamente allowlist) invece di ereditare channels.defaults.groupPolicy.

Modello mentale rapido (ordine di valutazione per i messaggi di gruppo):

groupPolicy (open/disabled/allowlist)
allowlist di gruppo (*.groups, *.groupAllowFrom, allowlist specifiche del canale)
gating menzione (requireMention, /activation)

Gating menzione (predefinito)

I messaggi di gruppo richiedono una menzione a meno che non venga sovrascritta 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). Questo si applica a Telegram, WhatsApp, Slack, Discord e Microsoft Teams.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { 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,
        },
      },
    ],
  },
}

Note:

I mentionPatterns sono regex case-insensitive.
Le piattaforme che forniscono menzioni esplicite passano comunque; i pattern sono un fallback.
Sovrascrittura per agent: agents.list[].groupChat.mentionPatterns (utile quando piu agent condividono un gruppo).
Il gating menzione e applicato solo quando il rilevamento menzione e possibile (menzioni native o mentionPatterns sono configurati).
I valori predefiniti Discord risiedono in channels.discord.guilds."*" (sovrascrivibili per guild/canale).
Il contesto storico di gruppo e wrappato uniformemente tra i canali ed e solo pending (messaggi saltati per gating menzione); usa messages.groupChat.historyLimit per il valore globale predefinito e channels.<channel>.historyLimit (o channels.<channel>.accounts.*.historyLimit) per le sovrascritture. Imposta 0 per disabilitare.

Restrizioni strumenti per gruppo/canale (opzionale)

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

tools: consenti/nega strumenti per l’intero gruppo.
toolsBySender: sovrascritture per mittente all’interno del gruppo. Usa prefissi espliciti nelle chiavi: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> e wildcard "*". Le chiavi legacy senza prefisso sono ancora accettate e corrispondono solo come id:.

Ordine di risoluzione (il piu specifico vince):

match toolsBySender del gruppo/canale
tools del gruppo/canale
match toolsBySender predefinito ("*")
tools predefinito ("*")

Esempio (Telegram):

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

Note:

Le restrizioni strumenti per gruppo/canale sono applicate in aggiunta alla policy strumenti globale/agent (deny vince comunque).
Alcuni canali usano nesting diversi per stanze/canali (es. Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Allowlist di gruppo

Quando channels.whatsapp.groups, channels.telegram.groups o channels.imessage.groups e configurato, le chiavi fungono da allowlist di gruppo. Usa "*" per consentire tutti i gruppi impostando comunque il comportamento menzione predefinito.

Intenti comuni (copia/incolla):

Disabilita tutte le risposte nei gruppi

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

Consenti solo gruppi specifici (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false },
      },
    },
  },
}

Consenti tutti i gruppi ma richiedi menzione (esplicito)

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

Solo il proprietario puo attivare nei gruppi (WhatsApp)

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

Attivazione (solo proprietario)

I proprietari dei gruppi possono alternare l’attivazione per gruppo:

/activation mention
/activation always

Il proprietario e determinato da channels.whatsapp.allowFrom (o l’E.164 del bot quando non impostato). Invia il comando come messaggio autonomo. Le altre piattaforme attualmente ignorano /activation.

Campi di contesto

I payload in ingresso dei gruppi impostano:

ChatType=group
GroupSubject (se noto)
GroupMembers (se noti)
WasMentioned (risultato del gating menzione)
I topic dei forum Telegram includono anche MessageThreadId e IsForum.

Il system prompt dell’agent include un’introduzione di gruppo al primo turno di una nuova sessione di gruppo. Ricorda al modello di rispondere come un umano, evitare tabelle Markdown e evitare di digitare sequenze letterali \n.

Specifiche iMessage

Preferisci chat_id:<id> per il routing o l’allowlisting.
Elenca le chat: imsg chats --limit 20.
Le risposte nei gruppi tornano sempre allo stesso chat_id.

Specifiche WhatsApp

Vedi Messaggi di gruppo per il comportamento specifico di WhatsApp (iniezione storico, dettagli sulla gestione delle menzioni).