Guía completa de integración de OpenClaw con WhatsApp: de la configuración a la práctica

Chatear con IA en WhatsApp significa usar tu app de mensajería más habitual para llamar al asistente, sin cambiar de aplicación. La integración con WhatsApp es un poco más compleja que con Telegram, pero entendiendo el principio la configuras en 5-10 minutos.

Guía de «cangrejo barato»: ArkClaw democratiza el agente de IA

OpenClaw (el «langostino») está muy de moda pero la configuración asusta. ArkClaw de Volcano Engine de ByteDance baja el listón al suelo: sin pelearte con servidores ni tokens, en un clic tienes un «asistente 24/7» que controla el navegador, ejecuta scripts y gestiona el calendario.

Lo importante: cuesta poco. Solo 9,9 yuanes al mes; con mi código de invitación ZLKUK54M (regístrate aquí) son 8,9 yuanes. Si eres desarrollador, el Coding Plan Pro puede salir gratis.

¿Por qué conectar IA en WhatsApp?

Antes de empezar, puede que te preguntes: ¿por qué no Telegram o la interfaz web?

Cada plataforma tiene sus ventajas. Para mí, WhatsApp encaja por esto:

• Hábito diario: es donde más chateo; familia y amigos están ahí
• Integración fluida: no hace falta abrir otra app de IA; preguntas desde el chat
• Linked Devices: la función multi-dispositivo de WhatsApp es madura y estable
• Privacidad bajo control: los datos están en tu servidor, sin pasar por terceros

Telegram también tiene ventajas: API más abierta y ecosistema de bots más rico. Elige según tu escenario.

Preparación: confirma tu entorno

Antes de conectar, verifica estos requisitos:

Requisitos imprescindibles

1. OpenClaw instalado y en ejecución — si aún no lo tienes, mira la guía de instalación previa
2. Cuenta de WhatsApp en el móvil — debe ser la cuenta principal para escanear el código
3. Gateway en ejecución — asegúrate de que openclaw gateway está activo
4. Red estable — hace falta buena conexión al escanear el QR

Nota técnica

Un detalle: si usas el runtime Bun, al conectar WhatsApp o Telegram puedes toparte con incompatibilidades. Lo oficial recomienda Node.js para el Gateway; suele ir más estable.

Comprueba tu entorno:

# Comprobar versión de Node.js
node --version

# Confirmar que el Gateway está en ejecución
ps aux | grep openclaw

Tres métodos de conexión

OpenClaw ofrece tres formas de enlazar WhatsApp; las ordeno por recomendación.

Método 1: asistente onboard (el más simple)

Es el más guiado, ideal la primera vez.

Si aún no completaste la configuración inicial:

openclaw onboard --install-daemon

En el asistente te preguntará qué canales conectar. Elige WhatsApp y:

1. El terminal muestra un código QR
2. Abre WhatsApp en el móvil: Ajustes → Dispositivos vinculados
3. Pulsa Vincular dispositivo y escanea el QR
4. Tras el escaneo, el terminal confirma la conexión

Tarda poco: 1-2 minutos. La primera vez estaba nervioso por si no escaneaba; al primer intento funcionó.

Método 2: comando channels login

Si ya hiciste onboard y solo quieres añadir WhatsApp:

openclaw channels login

Qué ocurre al ejecutarlo:

1. El terminal (o la web) muestra el QR
2. Escaneas con WhatsApp
3. Se establece la conexión y empiezas a recibir mensajes

Rápido y directo, sin todo el flujo de configuración.

Método 3: interfaz web (más flexible)

Para un control fino, usa el panel web.

Abre el panel de OpenClaw (por defecto http://localhost:18789) y:

Paso 1: entrar en configuración

Ve a Settings → Config y pulsa RAW arriba a la derecha para el editor de configuración en bruto.

Paso 2: añadir configuración de WhatsApp

En la sección channels, añade:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "debounceMs": 0
    }
  }
}

Significado de cada opción:

• dmPolicy: política de mensajes privados; allowlist solo permite usuarios en la lista blanca
• allowFrom: lista blanca con tu número (formato internacional con código de país)
• groupPolicy: política de grupos; allowlist es más seguro
• mediaMaxMb: tamaño máximo de archivos multimedia (MB)
• debounceMs: retardo anti-rebote en ms; suele ser 0

Paso 3: guardar y escanear

Pulsa Update arriba a la derecha, vuelve a Channels y verás un QR. Escanea con WhatsApp.

Configuración en detalle

Profundicemos en esas opciones.

Permisos: ¿quién puede escribir a tu IA?

dmPolicy y groupPolicy son claves de seguridad.

dmPolicy (mensajes privados) tiene tres valores:

• allowlist: solo números en la lista (recomendado)
• denylist: todos excepto la lista negra
• open: cualquiera puede escribir (no recomendado salvo que sepas lo que haces)

Yo uso allowlist con mi número y el de familia. La IA puede ejecutar cosas en el sistema; no quiero desconocidos enviando mensajes.

Formato de números en allowFrom

Deben ir en formato internacional con código de país:

"allowFrom": [
  "+8613800138000",    // China
  "+14155552671",      // EE. UU.
  "+447700900000"      // Reino Unido
]

No olvides el + y el código de país; si no, no se reconocen.

groupPolicy (grupos)

Para usar la IA en grupos de WhatsApp configura la política de grupo. Sinceramente, no abriría la IA en grupos salvo círculos muy cerrados de confianza.

Ejemplo:

"groupPolicy": "allowlist",
"allowFrom": ["ID del grupo"]

El ID del grupo aparece en los logs, o pon open, envía un mensaje y míralo en el log.

Enrutamiento: cómo procesa la IA tus mensajes

OpenClaw enruta automáticamente los mensajes de WhatsApp al modelo de IA:

1. Envías un mensaje en WhatsApp
2. OpenClaw Gateway lo recibe
3. Comprueba si el remitente está en la lista blanca
4. Si pasa, lo reenvía al modelo
5. La IA genera la respuesta
6. La respuesta vuelve a WhatsApp

Suele tardar 1-2 segundos según el modelo.

Archivos multimedia

mediaMaxMb limita el tamaño de archivo; 50 MB por defecto suele bastar.

Tipos admitidos por OpenClaw:

• Imágenes (JPG, PNG, etc.)
• Audio
• Documentos (PDF, TXT, etc.)

Si la IA tiene visión (p. ej. GPT-4V), puede interpretar imágenes que envíes.

Escaneo del código QR paso a paso

Cualquiera que sea el método, al final hay que escanear. Detalles a tener en cuenta:

En el móvil

1. Abre WhatsApp
2. Menú superior (tres puntos)
3. Dispositivos vinculados (Linked Devices)
4. Vincular dispositivo (Link a Device)
5. Puede pedir huella o contraseña
6. Apunta la cámara al QR del ordenador

En el ordenador

• Caducidad del QR: suele expirar en 1-2 minutos; regenera si falla
• Legibilidad: QR nítido; no uses fuente demasiado pequeña en terminal
• Red: móvil y PC online al escanear

La primera vez el QR en terminal era minúsculo y fallé varias veces; ampliar la ventana del terminal lo arregló.

Señales de conexión correcta

Tras escanear verás:

• Móvil: OpenClaw en la lista de dispositivos vinculados
• PC: mensaje tipo «WhatsApp connected»
• Web: WhatsApp en verde en Channels

Pruebas y verificación

Tras conectar, prueba de inmediato:

Primer mensaje

Escríbete a ti mismo, por ejemplo:

Hola, ¿me escuchas?

Si todo está bien, la IA responde en segundos. La primera respuesta me hizo sonreír un rato — parecía magia.

Distintos tipos de mensaje

Prueba:

• Texto: una pregunta a la IA
• Imagen: pide una descripción (modelo con visión)
• Documento: PDF o TXT
• Voz: si está soportado, prueba voz a texto

Revisar logs

Si algo falla, los logs ayudan:

# Ver logs de OpenClaw
openclaw gateway --port 18789

Verás mensajes recibidos, procesamiento y errores.

Resolución de problemas frecuentes

Al instalar software siempre hay tropiezos. Estos son los que me encontré y cómo los resolví.

Problema 1: el QR escaneado no hace nada

Causas posibles:

• QR caducado
• Problema de red
• WhatsApp desactualizado

Solución:

1. Regenera el QR y escanea de nuevo
2. Comprueba la red en móvil y PC
3. Actualiza WhatsApp

Problema 2: fallo de conexión, status=515

Error bastante común; la documentación oficial lo menciona.

Mensaje completo:

WhatsApp login failed: status=515 Unknown Stream Errored (restart required)

Solución:

1. Ve a Settings → Config
2. Pulsa Update (aunque no cambies nada)
3. Vuelve a Channels y revisa el estado
4. Si persiste, reinicia el Gateway

# Reiniciar Gateway
pkill -f openclaw
openclaw gateway --port 18789

Problema 3: envié mensaje y la IA no responde

Causas posibles:

• Remitente fuera de la lista blanca
• Modelo mal configurado
• API key inválida

Pasos:

1. Formato internacional del número
2. Logs: ¿llegó el mensaje?
3. ¿Responde la IA en la web?
4. ¿La API key sigue válida?

Problema 4: permiso denegado

Síntoma: «Permission denied» o silencio tras enviar

Solución:

• Tu número en allowFrom
• Formato con código de país
• En grupos, revisa groupPolicy

Problema 5: no se envían archivos multimedia

Causas posibles:

• Supera mediaMaxMb
• Formato no soportado
• Fallo de subida por red

Solución:

• Sube mediaMaxMb
• Comprime el archivo
• Revisa la conexión

Problema 6: desconexión tras reiniciar el Gateway

Síntoma: tras reiniciar PC o Gateway, WhatsApp se cae

Solución:

1. Normalmente reconecta solo
2. Si no: openclaw channels login y escanea otra vez
3. Comprueba que el daemon arranca bien

Trucos avanzados

Con lo básico listo, puedes afinar más.

Varios dispositivos

WhatsApp permite varios dispositivos vinculados. Si tienes OpenClaw en varios PCs, cada uno puede conectarse y los mensajes se sincronizan.

Ojo: una misma cuenta de WhatsApp solo puede enlazarse una vez con OpenClaw. Para varios PCs necesitas cuentas distintas.

Respuesta personalizada

debounceMs controla el anti-rebote:

"debounceMs": 1000

Si mandas varios mensajes seguidos, la IA espera 1 s y los procesa juntos, evitando llamadas API constantes.

Filtrado de mensajes

En Skills puedes ignorar ciertos mensajes; por ejemplo, responder solo si empiezan por «AI».

Rendimiento

Con mucho volumen:

• Reduce mediaMaxMb para ahorrar ancho de banda
• Ajusta debounceMs
• Usa un modelo más rápido

Recomendaciones de seguridad

Tras conectar WhatsApp, ten en cuenta lo siguiente:

1. Lista blanca estricta

Solo números de confianza en allowFrom. Esos números pueden ejecutar comandos vía IA (si activaste skills); el permiso es amplio.

2. Revisa dispositivos vinculados

En WhatsApp → Dispositivos vinculados, mira qué hay conectado. Si ves algo raro, desvincúlalo al momento.

3. Confirmación en acciones sensibles

Para borrar archivos o cambiar config, añade confirmación en skills para evitar errores.

4. No conectes en equipos públicos

En cibercafés o bibliotecas no escanees WhatsApp; el equipo puede estar comprometido.

5. Mantén OpenClaw actualizado

Parches de seguridad al día:

npm update -g openclaw
# o
pnpm update -g openclaw

Para cerrar

Hasta aquí deberías tener WhatsApp conectado a OpenClaw. Resumen del flujo:

WhatsApp vs Telegram: ¿cuál elegir?

Si dudas entre plataformas:

Elige WhatsApp si:

• WhatsApp es tu canal principal
• Quieres compartir la IA con familia y amigos
• Valoras la estabilidad de Linked Devices

Elige Telegram si:

• Quieres API más abierta
• Necesitas el ecosistema de bots
• Usas mucho canales y grupos avanzados

Puedes tener ambos: OpenClaw admite varios canales a la vez en WhatsApp y Telegram según el caso.

¿Qué hacer después?

Con la conexión lista:

• Explora Skills para ampliar capacidades
• Prueba imágenes y documentos (multimodal)
• Ajusta la lógica de respuesta
• Si te interesa, desarrolla plugins propios

Último aviso: WhatsApp es cómodo, pero cuida la seguridad. Gestiona la lista blanca con cuidado y no des permisos de IA a quien no confíes.

¡Disfruta! Ante dudas, documentación o comunidad.

---