Guia Completa de Integracion de OpenClaw con WhatsApp

Descripcion General

La integracion con WhatsApp te permite chatear con tu asistente de IA de OpenClaw directamente a traves de WhatsApp. OpenClaw usa WhatsApp Web via Baileys -- el gateway es dueno de la(s) sesion(es) y gestiona toda la comunicacion. Vincularas tu cuenta de WhatsApp de forma similar a como vinculas WhatsApp Web en un navegador.

Requisitos Previos

Antes de comenzar, asegurate de tener:

• OpenClaw instalado y el gateway en ejecucion
• Una cuenta de WhatsApp con un numero movil real (los numeros VoIP y virtuales suelen ser bloqueados por WhatsApp)
• Runtime Node.js (Bun no es recomendado -- WhatsApp/Baileys no es confiable en Bun)

Obtener un Numero de Telefono

WhatsApp requiere un numero movil real para la verificacion. Hay dos modos soportados:

Numero Dedicado (Recomendado)

Usa un numero de telefono separado para OpenClaw. Esto ofrece la mejor experiencia de usuario con enrutamiento limpio y sin particularidades del modo self-chat. La configuracion ideal es un telefono Android de repuesto/antiguo + eSIM -- dejalo conectado a Wi-Fi y enchufado, luego vincula via QR.

Consejos para obtener un numero:

• eSIM local de tu operador movil del pais (lo mas confiable)
• SIM prepago -- barata, solo necesita recibir un SMS de verificacion
• Evita: TextNow, Google Voice, la mayoria de servicios de "SMS gratis" -- WhatsApp los bloquea agresivamente

El numero solo necesita recibir un SMS de verificacion. Despues de eso, las sesiones de WhatsApp Web persisten a traves de creds.json.

Consejo: Puedes usar WhatsApp Business en el mismo dispositivo con un numero diferente. Ideal para mantener tu WhatsApp personal separado -- instala WhatsApp Business y registra el numero de OpenClaw ahi.

Numero Personal (Alternativa)

Alternativa rapida: ejecuta OpenClaw en tu propio numero. Enviate mensajes a ti mismo (funcion "Enviarte un mensaje" de WhatsApp) para probar y no molestar a tus contactos. En este caso debes habilitar el modo self-chat.

Paso 1: Configurar WhatsApp

Edita tu ~/.openclaw/openclaw.json.

Configuracion con Numero Dedicado

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

Reemplaza +15551234567 con el/los numero(s) de telefono que deseas permitir para chatear con el asistente (formato E.164).

Configuracion con Numero Personal (Modo Self-Chat)

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Al usar el modo self-chat, ingresa el numero de telefono desde el cual envias mensajes (el propietario/remitente), no el numero del asistente. Las respuestas en self-chat usan [{identity.name}] como prefijo por defecto (o [openclaw] si no esta definido). Puedes personalizar esto via messages.responsePrefix o establecerlo como "" para eliminarlo.

Paso 2: Vincular Tu Cuenta de WhatsApp

Ejecuta el comando de inicio de sesion:

openclaw channels login

Esto mostrara un codigo QR en tu terminal. En tu telefono:

1. Abre WhatsApp
2. Ve a Ajustes > Dispositivos vinculados
3. Toca Vincular un dispositivo
4. Escanea el codigo QR mostrado en tu terminal

Para configuraciones con multiples cuentas, especifica la cuenta:

openclaw channels login --account <accountId>

La cuenta predeterminada (cuando se omite --account) es default si esta presente, de lo contrario es el primer ID de cuenta configurado (ordenado alfabeticamente).

Paso 3: Iniciar el Gateway

Inicia el gateway de OpenClaw para comenzar a recibir mensajes. El gateway es dueno del socket de Baileys y del bucle de bandeja de entrada -- la CLI y la aplicacion de macOS se comunican con el gateway, sin uso directo de Baileys.

Importante: Se requiere un listener activo para envios salientes; de lo contrario, los envios fallaran inmediatamente.

Control de Acceso de Mensajes Directos

OpenClaw ofrece tres modos de politica de DM via channels.whatsapp.dmPolicy:

Modo Pairing (Predeterminado)

Los remitentes desconocidos reciben un codigo de emparejamiento con tiempo limitado. Su mensaje no se procesa hasta que sea aprobado.

# Aprobar una solicitud de emparejamiento
openclaw pairing approve whatsapp <code>

# Listar solicitudes de emparejamiento pendientes
openclaw pairing list whatsapp

Los codigos de emparejamiento expiran despues de 1 hora, y las solicitudes pendientes estan limitadas a 3 por canal.

Modo Allowlist

Solo los numeros de telefono listados en channels.whatsapp.allowFrom pueden iniciar chats.

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567", "+15559876543"],
    },
  },
}

Modo Open

Requiere que channels.whatsapp.allowFrom incluya "*".

Nota: Tu numero de WhatsApp vinculado es implicitamente confiable -- los mensajes propios omiten las verificaciones de dmPolicy y allowFrom.

Confirmaciones de Lectura

Por defecto, el gateway marca los mensajes entrantes de WhatsApp como leidos (marcas azules) una vez aceptados.

Deshabilitar globalmente:

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

Deshabilitar por cuenta:

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

El modo self-chat siempre omite las confirmaciones de lectura.

Soporte para Chats Grupales

Los grupos se mapean a sesiones dedicadas. Configura el comportamiento de grupos con:

• Politica de grupo: channels.whatsapp.groupPolicy -- open, disabled o allowlist (predeterminado: allowlist)
• Modos de activacion:
  • mention (predeterminado): requiere @mencion o coincidencia por regex
  • always: siempre genera una respuesta

Alterna la activacion con un comando exclusivo del propietario (debe ser un mensaje independiente):

/activation mention
/activation always

El propietario se determina por channels.whatsapp.allowFrom (o tu E.164 personal si no esta definido).

Contexto del Historial de Grupo

Los mensajes recientes no procesados (50 por defecto) se inyectan automaticamente como contexto:

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

Cada mensaje incluye un sufijo de remitente: [from: Name (+E164)].

Los metadatos del grupo (asunto + participantes) se cachean durante 5 minutos.

Reacciones de Confirmacion

WhatsApp puede enviar automaticamente reacciones con emoji a los mensajes entrantes al recibirlos, proporcionando retroalimentacion instantanea antes de que el bot genere una respuesta.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Opciones:

• emoji: Emoji con el que reaccionar (por ejemplo, "👀", "✅"). Vacio u omitido deshabilita la funcion.
• direct (predeterminado: true): Enviar reacciones en chats de DM.
• group (predeterminado: "mentions"):
  • "always": Reaccionar a todos los mensajes del grupo
  • "mentions": Reaccionar solo cuando se @menciona al bot
  • "never": Nunca reaccionar en grupos

Sobreescritura por cuenta:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

Las reacciones se envian inmediatamente al recibir el mensaje, antes de los indicadores de escritura o las respuestas del bot. Los fallos se registran pero no impiden que el bot responda.

Manejo de Mensajes

Mensajes Entrantes

• Los mensajes llegan via eventos messages.upsert de Baileys
• Los chats de estado/difusion se ignoran
• Los chats directos usan formato E.164; los grupos usan group JID
• El contexto de respuesta citada siempre se adjunta para proporcionar contexto de conversacion
• Los mensajes solo con medios usan marcadores de posicion: <media:image|video|audio|document|sticker>

Mensajes Salientes

• El texto se divide en fragmentos de 4,000 caracteres por defecto (configurable via channels.whatsapp.textChunkLimit)
• Division opcional por saltos de linea: establece channels.whatsapp.chunkMode="newline" para dividir en limites de parrafo antes de la division por longitud
• Tipos de medios soportados: imagen, video, audio, documento
• El audio se envia como notas de voz (PTT). Mejores resultados con formato OGG/Opus
• El pie de foto solo se incluye en el primer elemento multimedia
• GIFs animados: WhatsApp espera MP4 con gifPlayback: true para reproduccion en bucle

Limites de Medios

• Limite de guardado de medios entrantes: 50 MB (configurable via channels.whatsapp.mediaMaxMb)
• Limite de medios salientes: 5 MB por elemento (configurable via agents.defaults.mediaMaxMb)
• Las imagenes se optimizan automaticamente a JPEG cuando estan por debajo del limite (redimensionado + barrido de calidad)
• Los medios que exceden el limite generan un error; la respuesta multimedia recurre a una advertencia de texto

Credenciales y Almacenamiento

• Las credenciales se almacenan en: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Copia de seguridad automatica en creds.json.bak (se restaura en caso de corrupcion)
• Cerrar sesion: openclaw channels logout (o --account <id>) elimina el estado de autenticacion de WhatsApp pero conserva el oauth.json compartido

Soporte Multi-Cuenta

Multiples cuentas de WhatsApp pueden ejecutarse en un solo proceso del Gateway. Usa identificadores de cuenta en la configuracion:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* configuracion por cuenta */ },
        work: { /* configuracion por cuenta */ },
      },
    },
  },
}

La configuracion por cuenta soporta sobreescrituras para sendReadReceipts, ackReaction, mediaMaxMb, historyLimit y mas.

Por Que No Twilio / WhatsApp Business API?

Las primeras versiones de OpenClaw soportaban la integracion de WhatsApp Business de Twilio, pero fue eliminada porque:

• Los numeros de WhatsApp Business no son adecuados para un asistente personal
• Meta impone una ventana de respuesta de 24 horas -- si no has respondido en las ultimas 24 horas, el numero de negocio no puede iniciar nuevos mensajes
• El uso intensivo o "conversacional" activa bloqueos agresivos, porque las cuentas de negocio no estan disenadas para mensajeria estilo asistente personal
• Resultado: entrega poco confiable y bloqueos frecuentes

Referencia Rapida de Configuracion

| Clave de Configuracion | Descripcion | |---|---| | channels.whatsapp.dmPolicy | Politica de DM: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Habilitar para configuracion con numero personal | | channels.whatsapp.allowFrom | Lista de permitidos para DM (numeros de telefono E.164) | | channels.whatsapp.sendReadReceipts | Confirmaciones de lectura automaticas (predeterminado: true) | | channels.whatsapp.ackReaction | Reaccion automatica al recibir mensaje | | channels.whatsapp.groupPolicy | Politica de grupo: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Tamano de fragmento de texto saliente (predeterminado: 4000) | | channels.whatsapp.mediaMaxMb | Limite de medios entrantes (predeterminado: 50 MB) | | channels.whatsapp.configWrites | Permitir escrituras de configuracion via comando /config | | agents.defaults.mediaMaxMb | Limite de medios salientes (predeterminado: 5 MB) |

Solucion de Problemas

No Vinculado / Se Requiere Inicio de Sesion QR

Sintoma: channels status muestra linked: false o advierte "Not linked".

Solucion: Ejecuta openclaw channels login en el host del gateway y escanea el codigo QR (WhatsApp > Ajustes > Dispositivos vinculados).

Vinculado pero Desconectado / Bucle de Reconexion

Sintoma: channels status muestra running, disconnected o advierte "Linked but disconnected".

Solucion: Ejecuta openclaw doctor o reinicia el gateway. Si persiste, vuelve a vincular via openclaw channels login e inspecciona openclaw logs --follow.

Problemas con el Runtime de Bun

Bun no es recomendado. WhatsApp (Baileys) y Telegram no son confiables en Bun. Ejecuta el gateway con Node.js.

Comportamiento de Reconexion

El gateway usa una politica de backoff (web.reconnect) con initialMs, maxMs, factor, jitter y maxAttempts configurables. Si se alcanzan los intentos maximos, el monitoreo web se detiene (modo degradado). Un socket con sesion cerrada se detiene y requiere re-vinculacion.

Siguientes Pasos

• Guia de integracion con Telegram
• Guia de integracion con Discord
• Documentacion oficial de WhatsApp