Messaggi di gruppo di WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Comportamento

• Modalità di attivazione: mention (predefinita) o always. mention richiede un richiamo esplicito (vere @-mention WhatsApp tramite mentionedJids, pattern regex sicuri o il numero E.164 del bot in qualsiasi punto del testo). always attiva l’agente a ogni messaggio, ma dovrebbe rispondere solo quando può aggiungere valore significativo; altrimenti restituisce il token silenzioso esatto NO_REPLY / no_reply. I valori predefiniti possono essere impostati nella configurazione (channels.whatsapp.groups) e sovrascritti per gruppo tramite /activation. Quando channels.whatsapp.groups è impostato, funge anche da allowlist dei gruppi (includi "*" per consentirli tutti).
• Criterio dei gruppi: channels.whatsapp.groupPolicy controlla se i messaggi di gruppo vengono accettati (open|disabled|allowlist). allowlist usa channels.whatsapp.groupAllowFrom (fallback: channels.whatsapp.allowFrom esplicito). Il valore predefinito è allowlist (bloccato finché non aggiungi mittenti).
• Sessioni per gruppo: le chiavi di sessione hanno la forma agent:<agentId>:whatsapp:group:<jid>, quindi comandi come /verbose on, /trace on o /think high (inviati come messaggi autonomi) sono limitati a quel gruppo; lo stato dei DM personali resta invariato. Gli Heartbeat vengono saltati per i thread di gruppo.
• Iniezione del contesto: i messaggi di gruppo solo in sospeso (predefinito 50) che non hanno attivato un’esecuzione vengono prefissati sotto [Chat messages since your last reply - for context], con la riga di attivazione sotto [Current message - respond to this]. I messaggi già presenti nella sessione non vengono reinseriti.
• Esposizione del mittente: ogni batch di gruppo ora termina con [from: Sender Name (+E164)], così Pi sa chi sta parlando.
• Effimeri/visualizzabili una volta: li estraiamo prima di ricavare testo/mention, quindi i richiami al loro interno attivano comunque.
• Prompt di sistema del gruppo: al primo turno di una sessione di gruppo (e ogni volta che /activation cambia la modalità) inseriamo nel prompt di sistema una breve descrizione come You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. Se i metadati non sono disponibili, diciamo comunque all’agente che si tratta di una chat di gruppo.

​

Esempio di configurazione (WhatsApp)

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

• Le regex non distinguono maiuscole/minuscole e usano le stesse protezioni safe-regex delle altre superfici regex di configurazione; i pattern non validi e le ripetizioni annidate non sicure vengono ignorati.
• WhatsApp invia comunque mention canoniche tramite mentionedJids quando qualcuno tocca il contatto, quindi il fallback sul numero è raramente necessario, ma è un’utile rete di sicurezza.

​

Comando di attivazione (solo proprietario)

• /activation mention
• /activation always

​

Come si usa

1. Aggiungi il tuo account WhatsApp (quello che esegue OpenClaw) al gruppo.
2. Scrivi @openclaw … (o includi il numero). Solo i mittenti nella allowlist possono attivarlo, a meno che tu non imposti groupPolicy: "open".
3. Il prompt dell’agente includerà il contesto recente del gruppo più il marker finale [from: …], così potrà rivolgersi alla persona corretta.
4. Le direttive a livello di sessione (/verbose on, /trace on, /think high, /new o /reset, /compact) si applicano solo alla sessione di quel gruppo; inviale come messaggi autonomi perché vengano registrate. La tua sessione DM personale resta indipendente.

​

Test / verifica

• Smoke test manuale:
  • Invia un richiamo @openclaw nel gruppo e conferma una risposta che faccia riferimento al nome del mittente.
  • Invia un secondo richiamo e verifica che il blocco della cronologia venga incluso e poi cancellato al turno successivo.
• Controlla i log del Gateway (esegui con --verbose) per vedere voci inbound web message che mostrano from: <groupJid> e il suffisso [from: …].

​

Considerazioni note

• Gli Heartbeat vengono saltati intenzionalmente per i gruppi, per evitare broadcast rumorosi.
• La soppressione degli echo usa la stringa combinata del batch; se invii lo stesso testo due volte senza mention, solo il primo riceverà una risposta.
• Le voci dello store delle sessioni appariranno come agent:<agentId>:whatsapp:group:<jid> nello store delle sessioni (~/.openclaw/agents/<agentId>/sessions/sessions.json per impostazione predefinita); una voce mancante significa semplicemente che il gruppo non ha ancora attivato un’esecuzione.
• Gli indicatori di digitazione nei gruppi seguono agents.defaults.typingMode. Quando le risposte visibili usano la modalità predefinita solo strumento messaggi, la digitazione inizia immediatamente per impostazione predefinita, così i membri del gruppo possono vedere che l’agente sta lavorando anche se non viene pubblicata alcuna risposta finale automatica. La configurazione esplicita della modalità di digitazione ha comunque la precedenza.

​

Correlati

• Gruppi
• Instradamento dei canali
• Gruppi broadcast