OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Configuration

Mensajes de grupo de WhatsApp

Para el modelo de grupos entre canales (Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp, Zalo), consulte Grupos. Esta página aborda el comportamiento específico de WhatsApp que se añade a ese modelo: activación, listas de permitidos de grupos, claves de sesión por grupo e inyección de contexto de mensajes pendientes.

Objetivo: permitir que OpenClaw permanezca en grupos de WhatsApp, se active solo cuando se le mencione y mantenga ese hilo separado de la sesión personal de mensajes directos.

Comportamiento

  • Modos de activación: mention (predeterminado) o always. mention requiere una mención: una @mención real de WhatsApp (mentionedJids), un patrón de expresión regular configurado, los dígitos E.164 del bot en cualquier parte del texto o una respuesta citada a uno de los mensajes del bot (excepto en configuraciones de chat consigo mismo con un número compartido). always activa al agente con cada mensaje, pero el prompt de grupo inyectado le indica que responda solo cuando aporte valor y que, de lo contrario, devuelva el token silencioso exacto NO_REPLY (sin distinguir entre mayúsculas y minúsculas). Los valores predeterminados proceden de la configuración (channels.whatsapp.groups requireMention) y pueden sobrescribirse por grupo mediante /activation.
  • Lista de permitidos de grupos: cuando se establece channels.whatsapp.groups, solo se admiten los JID de grupo enumerados (incluya "*" para permitirlos todos); los mensajes de grupos no incluidos se descartan con una indicación en el registro.
  • Política de grupos: channels.whatsapp.groupPolicy controla si se aceptan los mensajes de grupo (open|disabled|allowlist). allowlist usa channels.whatsapp.groupAllowFrom (valor de respaldo: channels.whatsapp.allowFrom explícito). El valor predeterminado es allowlist (bloqueado hasta que se añadan remitentes).
  • Sesiones por grupo: las claves de sesión tienen el formato agent:<agentId>:whatsapp:group:<jid> (las cuentas no predeterminadas añaden :thread:whatsapp-account-<accountId>), por lo que las directivas como /verbose on, /trace on o /think high (enviadas como mensajes independientes) se limitan a ese grupo; el estado de los mensajes directos personales no se modifica.
  • Inyección de contexto: los mensajes de grupo solo pendientes (50 de forma predeterminada) que no activaron una ejecución se anteponen bajo [Chat messages since your last reply - for context], con la línea desencadenante bajo [Current message - respond to this]. La ventana de mensajes pendientes se borra después de la ejecución; los mensajes que ya están en la sesión no vuelven a inyectarse.
  • Atribución del remitente: cada línea del grupo incluye la etiqueta del remitente dentro del sobre del mensaje, por ejemplo, [WhatsApp <groupJid> <timestamp>] Alice (+447700900123): text, y la identidad del remitente junto con el asunto y los miembros del grupo se incluyen en el bloque de metadatos de conversación no fiables.
  • Mensajes efímeros/de visualización única: los envoltorios se eliminan antes de extraer el texto y las menciones, por lo que las menciones que contienen siguen activando al agente.
  • Prompt del sistema del grupo: el primer turno de una sesión de grupo (y cualquier turno posterior a que /activation cambie el modo) inyecta instrucciones de activación en el prompt del sistema (Activation: trigger-only ... o Activation: always-on ..., además de «dirigirse al remitente específico»). Siempre se incluyen las instrucciones persistentes de entrega para chats grupales («Está en un chat grupal de WhatsApp...»).

Ejemplo de configuración (WhatsApp)

Permita que las menciones por nombre visible funcionen incluso cuando WhatsApp elimine el @ visual del cuerpo del texto:

json5
{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },      historyLimit: 50, // ventana de contexto pendiente del grupo (valor predeterminado: 50)    },  },  agents: {    entries: {      main: {        groupChat: {          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    },  },}

Notas:

  • Las expresiones regulares no distinguen entre mayúsculas y minúsculas y usan las mismas protecciones de expresiones regulares seguras que otras superficies de configuración de expresiones regulares; los patrones no válidos y las repeticiones anidadas no seguras se ignoran.
  • WhatsApp sigue enviando menciones canónicas mediante mentionedJids cuando alguien toca el contacto, por lo que el valor de respaldo basado en el número rara vez es necesario, pero constituye una medida de seguridad útil.
  • La ventana de contexto pendiente se resuelve como channels.whatsapp.accounts.<id>.historyLimit → channels.whatsapp.historyLimit → messages.groupChat.historyLimit → 50.

Comando de activación (solo para el propietario)

Use el comando del chat grupal:

  • /activation mention
  • /activation always

Solo los números del propietario (procedentes de channels.whatsapp.allowFrom o el propio número E.164 del bot cuando no se establece) pueden cambiar esta opción; /activation de cualquier otra persona se ignora y se almacena únicamente como contexto. Envíe /status como mensaje independiente en el grupo para consultar el modo de activación actual.

Uso

  1. Añada al grupo su cuenta de WhatsApp (la que ejecuta OpenClaw).
  2. Diga @openclaw ... (o incluya el número). Solo los remitentes incluidos en la lista de permitidos pueden activarlo, a menos que se establezca groupPolicy: "open".
  3. El prompt del agente incluye el contexto pendiente del grupo y líneas etiquetadas por remitente para que pueda dirigirse a la persona correcta.
  4. Las directivas de sesión (/verbose on, /trace on, /think high, /new o /reset, /compact) se aplican únicamente a la sesión de ese grupo; envíelas como mensajes independientes para que se registren. La sesión personal de mensajes directos permanece independiente.

Pruebas y verificación

  • Prueba de humo manual:
    • Envíe una mención @openclaw en el grupo y confirme que la respuesta hace referencia al nombre del remitente.
    • Envíe una segunda mención y verifique que se incluya el bloque de historial y que se borre en el siguiente turno.
  • Compruebe los registros del Gateway (ejecútelo con --verbose) para localizar entradas inbound web message que muestren from: <groupJid> y el cuerpo etiquetado con el remitente.

Consideraciones conocidas

  • Los Heartbeat se ejecutan en la sesión principal del agente; las sesiones de grupo nunca reciben ejecuciones de Heartbeat.
  • La supresión de ecos recuerda el prompt combinado (historial y mensaje actual) por sesión para que los propios mensajes entregados por el bot no vuelvan a activarlo; un lote idéntico repetido puede omitirse por considerarse un eco.
  • Las entradas del almacén de sesiones aparecen como agent:<agentId>:whatsapp:group:<jid> en el almacén de sesiones SQLite por agente; la ausencia de una entrada solo significa que el grupo todavía no ha activado ninguna ejecución.
  • Los indicadores de escritura siguen agents.entries.*.typingMode / agents.defaults.typingMode. Cuando se habilitan las respuestas visibles en el modo exclusivo de herramientas de mensajes, la escritura comienza inmediatamente de forma predeterminada para que los miembros del grupo puedan ver que el agente está trabajando, aunque no se publique ninguna respuesta final automática. La configuración explícita del modo de escritura sigue teniendo prioridad.

Temas relacionados

Was this useful?
On this page

On this page