​

WhatsApp (canal web)

​

Configuración rápida (principiante)

1. Use un número de teléfono separado si es posible (recomendado).
2. Configure WhatsApp en ~/.openclaw/openclaw.json.
3. Ejecute openclaw channels login para escanear el código QR (Dispositivos vinculados).
4. Inicie el gateway.

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

​

Objetivos

• Múltiples cuentas de WhatsApp (multicuenta) en un solo proceso del Gateway.
• Enrutamiento determinista: las respuestas regresan a WhatsApp, sin enrutamiento por modelo.
• El modelo ve suficiente contexto para comprender respuestas citadas.

​

Escrituras de configuración

{
  channels: { whatsapp: { configWrites: false } },
}

​

Arquitectura (quién es dueño de qué)

• Gateway es propietario del socket de Baileys y del bucle de bandeja de entrada.
• CLI / app de macOS se comunican con el gateway; no usan Baileys directamente.
• Oyente activo es obligatorio para envíos salientes; de lo contrario, el envío falla de inmediato.

​

Obtener un número de teléfono (dos modos)

​

Número dedicado (recomendado)

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

​

Número personal (alternativa)

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

​

Consejos para obtener números

• eSIM local de su operador móvil del país (lo más confiable)
  • Austria: hot.at
  • Reino Unido: giffgaff — SIM gratis, sin contrato
• SIM prepago — económica, solo necesita recibir un SMS para la verificación

​

¿Por qué no Twilio?

• Las primeras versiones de OpenClaw admitían la integración de WhatsApp Business de Twilio.
• Los números de WhatsApp Business no son adecuados para un asistente personal.
• Meta impone una ventana de respuesta de 24 horas; si no ha respondido en las últimas 24 horas, el número empresarial no puede iniciar mensajes nuevos.
• El uso de alto volumen o “conversacional” activa bloqueos agresivos, porque las cuentas empresariales no están pensadas para enviar decenas de mensajes de asistente personal.
• Resultado: entrega poco confiable y bloqueos frecuentes, por lo que se eliminó el soporte.

​

Inicio de sesión + credenciales

• Comando de inicio de sesión: openclaw channels login (QR vía Dispositivos vinculados).
• Inicio de sesión multicuenta: openclaw channels login --account <id> (<id> = accountId).
• Cuenta predeterminada (cuando se omite --account): default si existe; de lo contrario, el primer id de cuenta configurado (ordenado).
• Credenciales almacenadas en ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.
• Copia de respaldo en creds.json.bak (se restaura en caso de corrupción).
• Compatibilidad heredada: instalaciones antiguas almacenaban archivos de Baileys directamente en ~/.openclaw/credentials/.
• Cerrar sesión: openclaw channels logout (o --account <id>) elimina el estado de autenticación de WhatsApp (pero conserva el oauth.json compartido).
• Socket con sesión cerrada ⇒ error que indica volver a vincular.

​

Flujo entrante (DM + grupos)

• Los eventos de WhatsApp provienen de messages.upsert (Baileys).
• Los oyentes de la bandeja de entrada se desacoplan al apagar para evitar acumular manejadores de eventos en pruebas/reinicios.
• Se ignoran chats de estado/difusión.
• Los chats directos usan E.164; los grupos usan JID de grupo.
• Política de DM: channels.whatsapp.dmPolicy controla el acceso a chats directos (predeterminado: pairing).
  • Emparejamiento: los remitentes desconocidos reciben un código de emparejamiento (apruebe vía openclaw pairing approve whatsapp <code>; los códigos expiran después de 1 hora).
  • Abierto: requiere que channels.whatsapp.allowFrom incluya "*".
  • Su número de WhatsApp vinculado es implícitamente confiable, por lo que los mensajes propios omiten las comprobaciones de channels.whatsapp.dmPolicy y channels.whatsapp.allowFrom.

​

Modo número personal (alternativa)

• Los DM salientes nunca activan respuestas de emparejamiento (evita enviar spam a contactos).
• Los remitentes desconocidos entrantes siguen channels.whatsapp.dmPolicy.
• El modo autochat (allowFrom incluye su número) evita confirmaciones automáticas de lectura e ignora JID de menciones.
• Se envían confirmaciones de lectura para DM que no son autochat.

​

Confirmaciones de lectura

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

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

• El modo autochat siempre omite las confirmaciones de lectura.

​

FAQ de WhatsApp: envío de mensajes + emparejamiento

• El primer DM de un remitente nuevo devuelve un código corto (el mensaje no se procesa).
• Apruebe con: openclaw pairing approve whatsapp <code> (liste con openclaw pairing list whatsapp).
• Los códigos expiran después de 1 hora; las solicitudes pendientes se limitan a 3 por canal.

​

Normalización de mensajes (lo que ve el modelo)

• Body es el cuerpo del mensaje actual con envolvente.
• El contexto de respuesta citada siempre se agrega:
  [Replying to +1555 id:ABC123]
  <quoted text or <media:...>>
  [/Replying]
  
• También se establecen metadatos de respuesta:
  • ReplyToId = stanzaId
  • ReplyToBody = cuerpo citado o marcador de posición de medios
  • ReplyToSender = E.164 cuando se conoce
• Los mensajes entrantes solo de medios usan marcadores de posición:
  • <media:image|video|audio|document|sticker>

​

Grupos

• Los grupos se asignan a sesiones agent:<agentId>:whatsapp:group:<jid>.
• Política de grupos: channels.whatsapp.groupPolicy = open|disabled|allowlist (predeterminado allowlist).
• Modos de activación:
  • mention (predeterminado): requiere @mención o coincidencia por regex.
  • always: siempre se activa.
• /activation mention|always es solo para propietario y debe enviarse como mensaje independiente.
• Propietario = channels.whatsapp.allowFrom (o E.164 propio si no se establece).
• Inyección de historial (solo pendientes):
  • Mensajes recientes no procesados (predeterminado 50) insertados bajo: [Chat messages since your last reply - for context] (los mensajes ya en la sesión no se reinyectan)
  • Mensaje actual bajo: [Current message - respond to this]
  • Sufijo del remitente agregado: [from: Name (+E164)]
• Metadatos del grupo en caché por 5 min (asunto + participantes).

​

Entrega de respuestas (hilos)

• WhatsApp Web envía mensajes estándar (sin hilos de respuesta citada en el gateway actual).
• Las etiquetas de respuesta se ignoran en este canal.

​

Reacciones de confirmación (auto-reaccionar al recibir)

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

• emoji (string): Emoji a usar para la confirmación (p. ej., ”👀”, ”✅”, ”📨”). Vacío u omitido = función desactivada.
• direct (boolean, predeterminado: true): Enviar reacciones en chats directos/DM.
• group (string, predeterminado: "mentions"): Comportamiento en grupos:
  • "always": Reaccionar a todos los mensajes del grupo (incluso sin @mención)
  • "mentions": Reaccionar solo cuando el bot es @mencionado
  • "never": Nunca reaccionar en grupos

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

• Las reacciones se envían inmediatamente al recibir el mensaje, antes de indicadores de escritura o respuestas del bot.
• En grupos con requireMention: false (activación: siempre), group: "mentions" reaccionará a todos los mensajes (no solo @menciones).
• Enviar y olvidar: los fallos de reacción se registran pero no impiden que el bot responda.
• El JID del participante se incluye automáticamente para reacciones en grupos.
• WhatsApp ignora messages.ackReaction; use channels.whatsapp.ackReaction en su lugar.

​

Herramienta del agente (reacciones)

• Herramienta: whatsapp con acción react (chatJid, messageId, emoji, remove opcional).
• Opcional: participant (remitente del grupo), fromMe (reaccionar a su propio mensaje), accountId (multicuenta).
• Semántica de eliminación de reacciones: consulte /tools/reactions.
• Control de herramienta: channels.whatsapp.actions.reactions (predeterminado: habilitado).

​

Límites

• El texto saliente se fragmenta a channels.whatsapp.textChunkLimit (predeterminado 4000).
• Fragmentación opcional por nueva línea: configure channels.whatsapp.chunkMode="newline" para dividir en líneas en blanco (límites de párrafo) antes de fragmentar por longitud.
• Los guardados de medios entrantes están limitados por channels.whatsapp.mediaMaxMb (predeterminado 50 MB).
• Los elementos de medios salientes están limitados por agents.defaults.mediaMaxMb (predeterminado 5 MB).

​

Envío saliente (texto + medios)

• Usa oyente web activo; error si el gateway no está en ejecución.
• Fragmentación de texto: máx. 4k por mensaje (configurable vía channels.whatsapp.textChunkLimit, channels.whatsapp.chunkMode opcional).
• Medios:
  • Se admiten imagen/video/audio/documento.
  • Audio enviado como PTT; audio/ogg => audio/ogg; codecs=opus.
  • El subtítulo solo en el primer elemento de medios.
  • La obtención de medios admite HTTP(S) y rutas locales.
  • GIF animados: WhatsApp espera MP4 con gifPlayback: true para bucle en línea.
    • CLI: openclaw message send --media <mp4> --gif-playback
    • Gateway: los parámetros de send incluyen gifPlayback: true

​

Notas de voz (audio PTT)

• Mejores resultados: OGG/Opus. OpenClaw reescribe audio/ogg a audio/ogg; codecs=opus.
• [[audio_as_voice]] se ignora para WhatsApp (el audio ya se envía como nota de voz).

​

Límites de medios + optimización

• Límite saliente predeterminado: 5 MB (por elemento de medios).
• Anulación: agents.defaults.mediaMaxMb.
• Las imágenes se optimizan automáticamente a JPEG bajo el límite (redimensionado + barrido de calidad).
• Medios sobredimensionados ⇒ error; la respuesta de medios vuelve a una advertencia de texto.

​

Latidos

• Latido del Gateway registra la salud de la conexión (web.heartbeatSeconds, predeterminado 60 s).
• Latido del agente puede configurarse por agente (agents.list[].heartbeat) o globalmente vía agents.defaults.heartbeat (alternativa cuando no hay entradas por agente).
  • Usa el prompt de latido configurado (predeterminado: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.) + el comportamiento de omisión HEARTBEAT_OK.
  • La entrega usa por defecto el último canal utilizado (o el destino configurado).

​

Comportamiento de reconexión

• Política de backoff: web.reconnect:
  • initialMs, maxMs, factor, jitter, maxAttempts.
• Si se alcanza maxAttempts, el monitoreo web se detiene (degradado).
• Sesión cerrada ⇒ detener y requerir volver a vincular.

​

Mapa rápido de configuración

• channels.whatsapp.dmPolicy (política de DM: emparejamiento/lista de permitidos/abierto/deshabilitado).
• channels.whatsapp.selfChatMode (configuración mismo teléfono; el bot usa su número personal de WhatsApp).
• channels.whatsapp.allowFrom (lista de permitidos de DM). WhatsApp usa números telefónicos E.164 (sin nombres de usuario).
• channels.whatsapp.mediaMaxMb (límite de guardado de medios entrantes).
• channels.whatsapp.ackReaction (auto-reacción al recibir mensajes: {emoji, direct, group}).
• channels.whatsapp.accounts.<accountId>.* (configuración por cuenta + authDir opcional).
• channels.whatsapp.accounts.<accountId>.mediaMaxMb (límite de medios entrantes por cuenta).
• channels.whatsapp.accounts.<accountId>.ackReaction (anulación de reacción de confirmación por cuenta).
• channels.whatsapp.groupAllowFrom (lista de permitidos de remitentes de grupo).
• channels.whatsapp.groupPolicy (política de grupos).
• channels.whatsapp.historyLimit / channels.whatsapp.accounts.<accountId>.historyLimit (contexto de historial de grupo; 0 deshabilita).
• channels.whatsapp.dmHistoryLimit (límite de historial de DM en turnos de usuario). Anulaciones por usuario: channels.whatsapp.dms["<phone>"].historyLimit.
• channels.whatsapp.groups (lista de permitidos de grupos + valores predeterminados de control por mención; use "*" para permitir todo)
• channels.whatsapp.actions.reactions (control de reacciones de herramientas de WhatsApp).
• agents.list[].groupChat.mentionPatterns (o messages.groupChat.mentionPatterns)
• messages.groupChat.historyLimit
• channels.whatsapp.messagePrefix (prefijo entrante; por cuenta: channels.whatsapp.accounts.<accountId>.messagePrefix; obsoleto: messages.messagePrefix)
• messages.responsePrefix (prefijo saliente)
• agents.defaults.mediaMaxMb
• agents.defaults.heartbeat.every
• agents.defaults.heartbeat.model (anulación opcional)
• agents.defaults.heartbeat.target
• agents.defaults.heartbeat.to
• agents.defaults.heartbeat.session
• agents.list[].heartbeat.* (anulaciones por agente)
• session.* (scope, idle, store, mainKey)
• web.enabled (deshabilitar inicio del canal cuando es false)
• web.heartbeatSeconds
• web.reconnect.*

​

Registros + solución de problemas

• Subsistemas: whatsapp/inbound, whatsapp/outbound, web-heartbeat, web-reconnect.
• Archivo de registro: /tmp/openclaw/openclaw-YYYY-MM-DD.log (configurable).
• Guía de solución de problemas: Solución de problemas del Gateway.

​

Solución de problemas (rápida)

• Síntoma: channels status muestra linked: false o advierte “No vinculado”.
• Solución: ejecute openclaw channels login en el host del Gateway y escanee el QR (WhatsApp → Configuración → Dispositivos vinculados).

• Síntoma: channels status muestra running, disconnected o advierte “Vinculado pero desconectado”.
• Solución: openclaw doctor (o reinicie el gateway). Si persiste, vuelva a vincular vía channels login e inspeccione openclaw logs --follow.

• Bun no es recomendado. WhatsApp (Baileys) y Telegram no son confiables en Bun. Ejecute el gateway con Node. (Consulte la nota de runtime en Primeros pasos.)