English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Configuration

Messaggi di gruppo di WhatsApp

Per il modello dei gruppi multicanale (Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo), vedi Gruppi. Questa pagina descrive il comportamento specifico di WhatsApp in aggiunta a quel modello: attivazione, allowlist dei gruppi, chiavi di sessione per gruppo e iniezione del contesto dei messaggi in sospeso.

Obiettivo: consentire a OpenClaw di restare nei gruppi WhatsApp, attivarsi solo quando viene chiamato in causa e mantenere quel thread separato dalla sessione DM personale.

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)

Aggiungi un blocco groupChat a ~/.openclaw/openclaw.json in modo che i richiami tramite nome visualizzato funzionino anche quando WhatsApp rimuove la @ visiva dal corpo del testo:

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

Note:

  • 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)

Usa il comando della chat di gruppo:

  • /activation mention
  • /activation always

Solo il numero del proprietario (da channels.whatsapp.allowFrom, oppure il numero E.164 del bot quando non è impostato) può modificarlo. Invia /status come messaggio autonomo nel gruppo per vedere la modalità di attivazione corrente.

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