Gruppi

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

# 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 controllo tramite menzione.
• Le normali risposte finali nei gruppi/canali sono private per impostazione predefinita. L'output visibile nella stanza usa lo strumento message.

Traduzione: i mittenti nella allowlist possono attivare OpenClaw menzionandolo.

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

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

# Risposte visibili

Per stanze di gruppo/canale, OpenClaw usa per impostazione predefinita messages.groupChat.visibleReplies: "message_tool". openclaw doctor --fix scrive questo valore predefinito nelle configurazioni dei canali configurati che lo omettono. Ciò significa che l'agente elabora comunque il turno e può aggiornare lo stato di memoria/sessione, ma la sua normale risposta finale non viene pubblicata automaticamente nella stanza. Per parlare in modo visibile, l'agente usa message(action=send).

Questo valore predefinito dipende da un modello/runtime che chiama gli strumenti in modo affidabile. Se i log mostrano testo dell'assistente ma didSendViaMessagingTool: false, il modello ha risposto privatamente invece di chiamare lo strumento di messaggistica. Non si tratta di un errore di invio di Discord/Slack/Telegram. Usa un modello affidabile nelle chiamate agli strumenti per le sessioni di gruppo/canale, oppure imposta messages.groupChat.visibleReplies: "automatic" per ripristinare le risposte finali visibili legacy.

Se lo strumento di messaggistica 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 turno sorgente, usa messages.visibleReplies: "message_tool" per applicare globalmente lo stesso comportamento di risposta visibile solo tramite strumento. Anche gli harness possono scegliere questo valore come predefinito quando non impostato; l'harness Codex lo fa per le chat dirette in modalità Codex. messages.groupChat.visibleReplies rimane l'override più specifico per le stanze di gruppo/canale.

Questo sostituisce il vecchio schema che forzava il modello a rispondere NO_REPLY per la maggior parte dei turni in modalità ascolto. In modalità solo strumento, non produrre nulla di visibile significa semplicemente non chiamare lo strumento di messaggistica.

Gli indicatori di digitazione vengono comunque inviati mentre l'agente lavora in modalità solo strumento. La modalità di digitazione predefinita per i gruppi viene aggiornata da "message" a "instant" per questi turni, perché potrebbe non esserci mai testo normale del messaggio dell'assistente prima che l'agente decida se chiamare lo strumento di messaggistica. La configurazione esplicita della modalità di digitazione ha comunque la precedenza.

Per ripristinare le risposte finali automatiche legacy per le stanze di gruppo/canale:

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

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 di messaggistica per ogni chat sorgente:

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

I comandi slash nativi (Discord, Telegram e altre superfici con supporto nativo ai comandi) bypassano visibleReplies: "message_tool" e rispondono sempre in modo visibile, così l'interfaccia dei comandi nativa del canale riceve la risposta prevista. Questo vale solo per i turni di comando nativi validati; i comandi /... digitati come testo e i turni di chat ordinari seguono comunque il valore predefinito configurato per il gruppo.

# Visibilità del contesto e allowlist

Nella sicurezza dei gruppi sono coinvolti due controlli diversi:

• Autorizzazione all'attivazione: chi può attivare l'agente (groupPolicy, groups, groupAllowFrom, allowlist specifiche 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. Ciò significa che le allowlist decidono principalmente chi può attivare azioni, non sono un confine universale di oscuramento per ogni frammento citato o storico.

Se vuoi...

Per allowlist di mittenti riutilizzabili, vedi 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 per mittente, se configurato).
• Gli Heartbeat vengono saltati per le sessioni di gruppo.

# Schema: DM personali + gruppi pubblici (agente singolo)

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

Perché: in modalità agente singolo, i DM in genere arrivano 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 tua sessione DM principale resta sull'host. Docker è il backend predefinito se non ne scegli uno.

Questo ti dà un unico "cervello" 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 Gateway
• Debug del motivo per cui uno strumento è bloccato: Sandbox vs policy degli strumenti vs privilegi elevati
• Dettagli sui bind mount: Sandboxing

# Etichette di visualizzazione

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

# Policy 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: ["[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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

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

# Controllo tramite menzione (predefinito)

I messaggi di gruppo richiedono una menzione, salvo override per gruppo. I valori predefiniti vivono per sottosistema in *.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 i metadati di citazione. I casi integrati attuali includono Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser.

{
  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,
        },
      },
    ],
  },
}

# Restrizioni degli strumenti per gruppo/canale (facoltative)

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

• tools: consenti/nega strumenti per l'intero gruppo.
• toolsBySender: override per mittente all'interno del gruppo. Usa prefissi di chiave espliciti: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> e wildcard "*". Le chiavi legacy senza prefisso sono ancora accettate e abbinate 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 dei gruppi

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

Intenti comuni (copia/incolla):

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

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

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

Note specifiche del canale:

• BlueBubbles può opzionalmente arricchire i partecipanti anonimi dei gruppi macOS dal database locale dei Contatti prima di popolare GroupMembers. Questo è disattivato per impostazione predefinita e viene eseguito solo dopo il normale superamento del gating di gruppo.

Il prompt di sistema dell'agente include un'introduzione al gruppo nel primo turno di una nuova sessione di gruppo. Ricorda al modello di rispondere come un essere umano, evitare tabelle Markdown, ridurre al minimo le righe vuote e seguire la normale spaziatura della chat, ed evitare di digitare sequenze letterali \n. I nomi dei gruppi e le etichette dei partecipanti provenienti dal canale sono resi come metadati non attendibili in blocchi fenced, non come istruzioni di sistema inline.

# Specificità di iMessage

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

# Prompt di sistema di WhatsApp

Vedi WhatsApp per le regole canoniche dei prompt di sistema di WhatsApp, incluse la risoluzione dei prompt di gruppo e diretti, il comportamento wildcard e la semantica degli override degli account.

# Specificità di WhatsApp

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

# Correlati

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