Configura WhatsApp en OpenClaw

¿Te ha pasado que quieres automatizar mensajes pero la configuración de las APIs oficiales es demasiado restrictiva o costosa? Configurar un canal de comunicación suele ser un proceso lento que te quita tiempo para programar la lógica real de tu aplicación.

OpenClaw permite conectar WhatsApp de forma directa mediante WhatsApp Web (Baileys). En este modelo, el Gateway gestiona las sesiones vinculadas para que tú te enfoques en el código.

Requisitos previos

• Una cuenta de WhatsApp activa.
• CLI de openclaw instalado y configurado.

Inicio rápido

Sigue estos cuatro pasos para tener tu conexión lista en menos de 5 minutos.

1. Configura la política de acceso

Edita tu configuración para definir quién puede enviar mensajes. Mi recomendación es usar pairing para remitentes desconocidos.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

2. Vincula WhatsApp mediante QR

Ejecuta el comando de login. Si necesitas usar una cuenta específica (por ejemplo, para trabajo), usa el flag --account.

openclaw channels login --channel whatsapp

Para una cuenta específica:

openclaw channels login --channel whatsapp --account work

3. Inicia el Gateway

Esto activa el socket y mantiene la conexión viva.

openclaw gateway

4. Aprueba la solicitud de pairing

Si activaste el modo pairing, debes aprobar manualmente las solicitudes nuevas.

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Recomendación de despliegue

Te sugiero usar un número dedicado siempre que sea posible. Es la forma más limpia de operar por estas razones:

• Tienes una identidad de WhatsApp separada para OpenClaw.
• Evitas confusiones en los chats personales.
• Los límites de enrutamiento y las listas de permitidos son más claros.
• La configuración de políticas es mínima.

Si decides usar tu número personal, OpenClaw activará automáticamente el selfChatMode: true para proteger tus chats y permitirte interactuar contigo mismo.

Runtime model

• El Gateway es el dueño del socket de WhatsApp y del ciclo de reconexión.
• Para enviar mensajes salientes, necesitas un listener de WhatsApp activo para esa cuenta.
• El sistema ignora automáticamente los estados y chats de difusión (@status, @broadcast).
• Las sesiones de grupo se mantienen aisladas bajo el formato agent:<agentId>:whatsapp:group:<jid>.

Solución de problemas

• Las solicitudes de pairing expiran: Tienes un límite de 1 hora para aprobar una solicitud antes de que se elimine.
• Límite de solicitudes pendientes: El sistema solo permite un máximo de 3 solicitudes pendientes por canal.

¿Necesitas ayuda personalizada? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Pairing details
• Channel troubleshooting
• Gateway configuration

Gestionar quién tiene permiso para hablar con tu bot es fundamental para evitar ruidos innecesarios o consumo excesivo de recursos. Si dejas la configuración abierta, cualquier usuario podría activar procesos internos; si la cierras demasiado, tus usuarios legítimos se quedarán fuera.

Aquí tienes cómo configurar el acceso y la activación en tu Gateway para mantener el control total sobre las interacciones.

What You’ll Need

• Una cuenta de WhatsApp vinculada al sistema.
• Acceso al archivo de configuración de channels.whatsapp.
• Los números de teléfono en formato E.164 para las listas de permitidos.
• Permisos de owner para ejecutar comandos en el chat.

Quick Start

Para configurar el acceso básico en 5 minutos, debes definir la política de mensajes directos (DM). Por defecto, el sistema utiliza pairing, lo que significa que el bot recordará con quién se ha vinculado.

channels:
  whatsapp:
    dmPolicy: pairing # Opciones: pairing, allowlist, open, disabled
    allowFrom:
      - "+1234567890" # Formato E.164

Si necesitas que el bot sea totalmente público, cambia dmPolicy a open y asegúrate de incluir "*" en allowFrom.

Control de DM y listas de permitidos

La propiedad channels.whatsapp.dmPolicy es el corazón del control de acceso. Tienes cuatro comportamientos posibles:

1. pairing: Es el valor por defecto. Los emparejamientos se guardan en el allow-store del canal y se mezclan con lo que pongas en allowFrom.
2. allowlist: Solo los números listados explícitamente pueden interactuar.
3. open: Cualquiera puede escribir, siempre que allowFrom incluya el comodín "*".
4. disabled: Bloquea todos los mensajes directos entrantes.

Ten en cuenta que los DMs salientes (fromMe) nunca activan el auto-pairing. Además, si no configuras ninguna lista, el sistema permite por defecto el número propio vinculado.

Gestión de Grupos

El acceso a grupos funciona mediante dos capas de seguridad independientes.

Capa 1: Lista de grupos permitidos Usa channels.whatsapp.groups para filtrar en qué grupos puede operar el bot. Si omites esta opción, todos los grupos son elegibles. Si la incluyes, funciona como una allowlist (puedes usar "*" para permitir todos explícitamente).

Capa 2: Política de remitentes en grupos Se configura mediante channels.whatsapp.groupPolicy y groupAllowFrom:

• open: Se ignora la lista de remitentes.
• allowlist: El remitente debe estar en groupAllowFrom o ser un "*".
• disabled: Se bloquean todos los mensajes entrantes de grupos.

Si no defines groupAllowFrom, el sistema usará los valores de allowFrom como respaldo. Si no existe ningún bloque de configuración para channels.whatsapp, la política de grupos por defecto será open.

Menciones y Activación de Sesión

En los grupos, el bot requiere una mención para responder. El sistema detecta estas interacciones de varias formas:

• Menciones explícitas de WhatsApp a la identidad del bot.
• Patrones de Regex configurados en agents.list[].groupChat.mentionPatterns (o el fallback en messages.groupChat.mentionPatterns).
• Detección implícita cuando alguien responde directamente a un mensaje enviado por el bot.

Puedes cambiar el comportamiento de activación en tiempo real mediante comandos de chat. Estos cambios afectan al estado de la sesión, no a la configuración global, y solo el owner puede ejecutarlos:

• /activation mention: El bot solo responde si es mencionado.
• /activation always: El bot escucha y responde a todos los mensajes del chat.

Comportamiento del número personal

Cuando utilizas tu propio número vinculado y este aparece en allowFrom, el Gateway activa salvaguardas especiales para el “self-chat”:

• No se envían confirmaciones de lectura para tus propios mensajes.
• Se ignora el auto-disparo por mención de JID para evitar que el bot se responda a sí mismo infinitamente.
• Si messages.responsePrefix no está definido, las respuestas en el chat contigo mismo usarán por defecto [{identity.name}] o [openclaw].

Troubleshooting

• El bot no responde en un grupo nuevo: Verifica si has definido channels.whatsapp.groups. Si la lista existe y el ID del grupo no está, el bot ignorará los mensajes.
• Las menciones por Regex no funcionan: Asegúrate de que los patrones están en agents.list[].groupChat.mentionPatterns. Si ese campo está vacío, revisa el fallback en messages.groupChat.mentionPatterns.

Si tienes dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

What’s Next

• Configuración de Mensajería
• Gestión de Identidades

Manejar mensajes entrantes de diferentes fuentes suele ser un dolor de cabeza. Te encuentras con formatos inconsistentes, respuestas citadas que pierden el hilo o archivos multimedia que no sabes cómo procesar sin descargar primero. Es fácil perder el contexto de una conversación cuando los datos llegan desordenados.

Aquí te muestro cómo el sistema normaliza toda esa información para que tú solo te preocupes por la lógica de tu aplicación.

Requisitos previos

• Una cuenta de WhatsApp activa en el Gateway.
• Acceso al archivo de configuración de channels.whatsapp.

Inicio rápido

1. Gestiona el contexto de las respuestas

Cuando recibes un mensaje en WhatsApp, este llega dentro de un “inbound envelope” compartido. Si el usuario está respondiendo a un mensaje específico (una cita), el contexto se añade automáticamente con este formato:

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

Además, el sistema rellena campos de metadata útiles como ReplyToId, ReplyToBody, ReplyToSender y el JID/E.164 del remitente.

2. Identifica archivos multimedia y datos

Si recibes mensajes que solo contienen archivos, verás placeholders de texto. Esto evita que tengas que procesar binarios de entrada para saber qué envió el usuario:

• <media:image>
• <media:video>
• <media:audio>
• <media:document>
• <media:sticker>

Los datos de ubicación (location) y contactos también se convierten en texto plano antes de ser enviados a tu lógica.

3. Configura el historial en grupos

Para los grupos, puedes inyectar mensajes previos para que el bot entienda de qué se está hablando. El límite por defecto es de 50 mensajes.

Puedes ajustar esto en channels.whatsapp.historyLimit o usar el fallback messages.groupChat.historyLimit. Si usas 0, desactivas esta función. El sistema inserta estos marcadores para separar el historial del mensaje actual:

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

4. Controla los Read receipts

Por defecto, el sistema envía confirmaciones de lectura para los mensajes entrantes aceptados. Si prefieres manejarlo tú o desactivarlo, tienes dos opciones.

Desactivación global:

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

Anulación por cuenta específica:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

Solución de problemas

• El bot no recibe contexto de mensajes antiguos en grupos: Revisa el valor de channels.whatsapp.historyLimit. Si está en 0, no se inyectará ningún mensaje previo.
• No se envían Read receipts en chats propios: Los turnos de “self-chat” omiten automáticamente las confirmaciones de lectura, incluso si las tienes activadas globalmente.

Si necesitas ayuda personalizada para configurar tu flujo de mensajes, consulta nuestro AI Setup Assistant.

Próximos pasos

• Configuración de canales
• Gestión de Webhooks

¿Alguna vez has intentado enviar un mensaje larguísimo y terminó cortado en el lugar menos oportuno? Peor aún, enviar un video que nunca carga porque el archivo es demasiado pesado. Gestionar la entrega y los archivos multimedia en WhatsApp requiere ajustes precisos para que la comunicación sea clara y no se pierda información en el camino.

Aquí tienes los detalles para configurar estos aspectos y evitar que tus respuestas se corten o fallen silenciosamente.

Requisitos previos

• Acceso a la configuración de channels.whatsapp
• CLI de openclaw instalado

Inicio rápido

Para configurar una base sólida en 5 minutos, ajusta cómo se dividen los mensajes y activa las reacciones de lectura:

1. Define la fragmentación de texto: Usa channels.whatsapp.textChunkLimit = 4000 para establecer el límite. Te recomiendo usar channels.whatsapp.chunkMode = "newline", ya que prioriza los espacios entre párrafos antes de cortar por longitud.

2. Configura reacciones automáticas: Añade esto a tu configuración para confirmar que el bot recibió el mensaje:

   {
     channels: {
       whatsapp: {
         ackReaction: {
           emoji: "👀",
           direct: true,
           group: "mentions", // siempre | menciones | nunca
         },
       },
     },
   }

Delivery y Multimedia

WhatsApp maneja distintos tipos de payloads: imágenes, videos, audios (notas de voz PTT) y documentos. El sistema se encarga de varios detalles técnicos por ti:

• Notas de voz: Si envías audio/ogg, se reescribe automáticamente a audio/ogg; codecs=opus para asegurar la compatibilidad.
• GIFs: Puedes activar la reproducción automática usando gifPlayback: true en los envíos de video.
• Captions: En respuestas con múltiples archivos multimedia, el texto se aplica al primer elemento del set.
• Sources: Puedes usar rutas locales, file:// o enlaces HTTP(S).

Límites de tamaño y optimización

El sistema incluye protecciones para evitar errores de red:

• Inbound: El límite de guardado para archivos recibidos es channels.whatsapp.mediaMaxMb (50MB por defecto).
• Outbound: Para respuestas automáticas, el límite es agents.defaults.mediaMaxMb (5MB por defecto).
• Optimización: Las imágenes pasan por un proceso automático de ajuste de tamaño y calidad para cumplir con estos límites.

Cuentas y Credenciales

Si manejas múltiples cuentas, los IDs se obtienen de channels.whatsapp.accounts. El sistema elige la cuenta default si existe; si no, toma el primer ID configurado tras ordenarlos.

Las credenciales se guardan en: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json

Si necesitas cerrar sesión en una cuenta específica para limpiar el estado de autenticación, usa este comando: openclaw channels logout --channel whatsapp [--account <id>]

Tools y Configuración

El Agent soporta la herramienta de reacción (react) de forma nativa. Puedes controlar qué acciones están permitidas mediante estos gates:

• channels.whatsapp.actions.reactions
• channels.whatsapp.actions.polls

Por defecto, el canal permite escrituras de configuración iniciadas por el bot. Si prefieres bloquear esto, usa channels.whatsapp.configWrites=false.

Solución de problemas

• El mensaje multimedia no llega: Si el envío falla, el sistema tiene un comportamiento de fallback: envía una advertencia en texto en lugar de ignorar la respuesta por completo.
• Las reacciones no funcionan en grupos: Verifica el modo de group. Si está en mentions, solo reaccionará cuando el bot sea mencionado. Cambia a always si necesitas omitir esta validación.

Para resolver dudas específicas sobre tu configuración, consulta al AI Setup Assistant.

Próximos pasos

• WhatsApp Configuration Reference
• Managing Credentials

---
title: Solución de problemas en tu Gateway de WhatsApp
description: Guía técnica para resolver errores de conexión, mensajes de grupo y configuración en openclaw.
---

Conectar una API con WhatsApp suele presentar retos técnicos, desde sesiones que se cierran hasta mensajes que no llegan a su destino. Es frustrante pasar horas revisando logs cuando solo necesitas que tu integración funcione de forma estable.

Aquí tienes los pasos directos para diagnosticar y arreglar los fallos más comunes en tu Gateway.

## Requisitos previos

Para seguir esta guía, asegúrate de cumplir con estos requisitos:

- Node.js instalado (evita usar Bun para el Gateway).
- CLI de openclaw configurada en tu terminal.
- Una cuenta de WhatsApp lista para vincular.
- Acceso a los archivos de configuración de tu proyecto.

## Inicio rápido

Si tienes problemas con un canal, sigue esta ruta de 5 minutos para restablecer la conexión:

1. **Vincula el canal:** Ejecuta el comando para generar el QR y loguearte.
   ```bash
   openclaw channels login --channel whatsapp

2. Verifica el estado: Confirma que la sesión está activa.

   openclaw channels status

Solución de problemas

El canal no aparece como vinculado (Requiere QR)

Si el reporte de estado indica que el canal no está vinculado, necesitas refrescar la sesión manualmente.

Solución:

openclaw channels login --channel whatsapp
openclaw channels status

Vinculado pero desconectado o en bucle de reconexión

Si la cuenta aparece como vinculada pero sufres desconexiones constantes o intentos fallidos de reconexión, usa las herramientas de diagnóstico internas.

Solución:

openclaw doctor
openclaw logs --follow

Si el problema persiste tras revisar los logs, vuelve a vincular la cuenta con channels login.

Error: “No active listener” al enviar mensajes

Los envíos salientes fallan inmediatamente si no existe un listener del Gateway activo para la cuenta de destino.

Asegúrate de que el Gateway esté ejecutándose y que la cuenta específica esté correctamente vinculada en el sistema.

Mensajes de grupo ignorados inesperadamente

Si los mensajes en grupos no se procesan, revisa tu configuración en este orden exacto:

1. El valor de groupPolicy.
2. Las reglas en groupAllowFrom / allowFrom.
3. Las entradas en la lista blanca de groups.
4. El filtrado por menciones (requireMention y los patrones de mención configurados).

Advertencia de runtime con Bun

El Gateway de WhatsApp debe ejecutarse sobre Node.js. Se ha detectado que Bun es incompatible para mantener una operación estable en los gateways de WhatsApp y Telegram. Cambia el runtime para evitar cierres inesperados.

Configuration reference pointers

Si necesitas ajustar parámetros específicos, consulta la referencia principal:

• Configuration reference - WhatsApp

Campos clave para WhatsApp:

• Control de acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups.
• Entrega de mensajes: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction.
• Gestión multi-cuenta: accounts.<id>.enabled, accounts.<id>.authDir y overrides a nivel de cuenta.
• Operaciones: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*.
• Comportamiento de sesión: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit.

¿Necesitas ayuda personalizada con tu configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Pairing
• Channel routing
• Troubleshooting