Saltar al contenido principal

​
WhatsApp (canal web)

Estado: listo para producción mediante WhatsApp Web (Baileys). La gateway es propietaria de las sesiones vinculadas.

​
Instalación (bajo demanda)

  • Onboarding (openclaw onboard) y openclaw channels add --channel whatsapp solicitan instalar el plugin de WhatsApp la primera vez que lo seleccionas.
  • openclaw channels login --channel whatsapp también ofrece el flujo de instalación cuando el plugin todavía no está presente.
  • Canal de desarrollo + checkout de git: usa de forma predeterminada la ruta local del plugin.
  • Stable/Beta: usa de forma predeterminada el paquete npm @openclaw/whatsapp.
La instalación manual sigue estando disponible: 
openclaw plugins install @openclaw/whatsapp

Emparejamiento

La política predeterminada de mensajes directos es emparejamiento para remitentes desconocidos.

Solución de problemas del canal

Diagnósticos y guías de reparación entre canales.

Configuración de gateway

Patrones y ejemplos completos de configuración del canal.

​
Configuración rápida

1

Configurar la política de acceso de WhatsApp

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

Vincular WhatsApp (QR)

openclaw channels login --channel whatsapp
Para una cuenta específica:
openclaw channels login --channel whatsapp --account work
3

Iniciar la gateway

openclaw gateway
4

Aprobar la primera solicitud de emparejamiento (si usas el modo de emparejamiento)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Las solicitudes de emparejamiento caducan después de 1 hora. Las solicitudes pendientes tienen un límite de 3 por canal.
OpenClaw recomienda ejecutar WhatsApp en un número independiente cuando sea posible. (Los metadatos del canal y el flujo de configuración están optimizados para esa configuración, pero también se admiten configuraciones con número personal).

​
Patrones de despliegue

Este es el modo operativo más limpio:
  • identidad de WhatsApp separada para OpenClaw
  • límites de listas de permitidos y enrutamiento de mensajes directos más claros
  • menor probabilidad de confusión por chatear contigo mismo
Patrón de política mínima:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
Onboarding admite el modo de número personal y escribe una línea base compatible con chat contigo mismo:
  • dmPolicy: "allowlist"
  • allowFrom incluye tu número personal
  • selfChatMode: true
En runtime, las protecciones de chat contigo mismo se basan en el número propio vinculado y allowFrom.
El canal de la plataforma de mensajería está basado en WhatsApp Web (Baileys) en la arquitectura actual de canales de OpenClaw.No existe un canal de mensajería de WhatsApp de Twilio separado en el registro integrado de canales de chat.

​
Modelo de runtime

  • La gateway es propietaria del socket de WhatsApp y del bucle de reconexión.
  • Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino.
  • Los chats de estado y difusión se ignoran (@status, @broadcast).
  • Los chats directos usan reglas de sesión de mensajes directos (session.dmScope; main de forma predeterminada colapsa los mensajes directos en la sesión principal del agente).
  • Las sesiones de grupo están aisladas (agent:<agentId>:whatsapp:group:<jid>).

​
Control de acceso y activación

channels.whatsapp.dmPolicy controla el acceso al chat directo:
  • pairing (predeterminado)
  • allowlist
  • open (requiere que allowFrom incluya "*")
  • disabled
allowFrom acepta números con formato E.164 (normalizados internamente).Sobrescritura para varias cuentas: channels.whatsapp.accounts.<id>.dmPolicy (y allowFrom) tienen prioridad sobre los valores predeterminados a nivel de canal para esa cuenta.Detalles del comportamiento en runtime:
  • los emparejamientos se conservan en el almacén de permitidos del canal y se fusionan con allowFrom configurado
  • si no se configura ninguna lista de permitidos, el número propio vinculado está permitido de forma predeterminada
  • los mensajes directos salientes fromMe nunca se emparejan automáticamente

​
Comportamiento de número personal y chat contigo mismo

Cuando el número propio vinculado también está presente en allowFrom, se activan las protecciones de chat contigo mismo de WhatsApp:
  • omitir confirmaciones de lectura en turnos de chat contigo mismo
  • ignorar el comportamiento de activación automática por mention-JID que de otro modo te haría ping a ti mismo
  • si messages.responsePrefix no está establecido, las respuestas en chat contigo mismo usan de forma predeterminada [{identity.name}] o [openclaw]

​
Normalización de mensajes y contexto

Los mensajes entrantes de WhatsApp se encapsulan en el sobre compartido de entrada.Si existe una respuesta citada, el contexto se añade de esta forma:
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
Los campos de metadatos de respuesta también se rellenan cuando están disponibles (ReplyToId, ReplyToBody, ReplyToSender, remitente JID/E.164).
Los mensajes entrantes solo de medios se normalizan con placeholders como:
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
Las cargas de ubicación y contacto se normalizan a contexto textual antes del enrutamiento.
Para grupos, los mensajes no procesados pueden almacenarse en búfer e inyectarse como contexto cuando finalmente se activa el bot.
  • límite predeterminado: 50
  • configuración: channels.whatsapp.historyLimit
  • fallback: messages.groupChat.historyLimit
  • 0 desactiva
Marcadores de inyección:
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
Las confirmaciones de lectura están habilitadas de forma predeterminada para los mensajes entrantes de WhatsApp aceptados.Desactivar globalmente:
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
Sobrescritura por cuenta:
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
Los turnos de chat contigo mismo omiten las confirmaciones de lectura incluso cuando están habilitadas globalmente.

​
Entrega, fragmentación y medios

  • límite de fragmentación predeterminado: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • el modo newline prefiere límites de párrafo (líneas en blanco) y luego usa como fallback una fragmentación segura por longitud
  • admite cargas de imagen, video, audio (nota de voz PTT) y documento
  • audio/ogg se reescribe a audio/ogg; codecs=opus para compatibilidad con notas de voz
  • la reproducción de GIF animados se admite mediante gifPlayback: true en envíos de video
  • los subtítulos se aplican al primer elemento multimedia al enviar cargas de respuesta multimeda
  • la fuente multimedia puede ser HTTP(S), file:// o rutas locales
  • límite de guardado de medios entrantes: channels.whatsapp.mediaMaxMb (predeterminado 50)
  • límite de envío de medios salientes: channels.whatsapp.mediaMaxMb (predeterminado 50)
  • las sobrescrituras por cuenta usan channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • las imágenes se optimizan automáticamente (redimensionado/barrido de calidad) para ajustarse a los límites
  • ante fallo al enviar medios, el fallback del primer elemento envía una advertencia de texto en lugar de descartar la respuesta silenciosamente

​
Nivel de reacciones

channels.whatsapp.reactionLevel controla qué tan ampliamente usa el agente reacciones con emoji en WhatsApp:
NivelReacciones de confirmaciónReacciones iniciadas por el agenteDescripción
"off"NoNoSin reacciones en absoluto
"ack"SíNoSolo reacciones de confirmación (acuse previo a respuesta)
"minimal"SíSí (conservadoras)Confirmación + reacciones del agente con guía conservadora
"extensive"SíSí (fomentadas)Confirmación + reacciones del agente con guía fomentada
Predeterminado: "minimal". Las sobrescrituras por cuenta usan channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Reacciones de confirmación

WhatsApp admite reacciones de confirmación inmediatas al recibir entradas mediante channels.whatsapp.ackReaction. Las reacciones de confirmación están controladas por reactionLevel: se suprimen cuando reactionLevel es "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Notas de comportamiento:
  • se envían inmediatamente después de aceptar la entrada (antes de responder)
  • los fallos se registran, pero no bloquean la entrega normal de la respuesta
  • el modo de grupo mentions reacciona en turnos activados por mención; la activación de grupo always actúa como bypass para esta comprobación
  • WhatsApp usa channels.whatsapp.ackReaction (el heredado messages.ackReaction no se usa aquí)

​
Varias cuentas y credenciales

  • los IDs de cuenta provienen de channels.whatsapp.accounts
  • selección de cuenta predeterminada: default si está presente; en caso contrario, el primer ID de cuenta configurado (ordenado)
  • los IDs de cuenta se normalizan internamente para la búsqueda
  • ruta actual de autenticación: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • archivo de respaldo: creds.json.bak
  • la autenticación heredada predeterminada en ~/.openclaw/credentials/ sigue reconociéndose/migrándose para flujos de cuenta predeterminada
openclaw channels logout --channel whatsapp [--account <id>] borra el estado de autenticación de WhatsApp para esa cuenta.En directorios heredados de autenticación, oauth.json se conserva mientras se eliminan los archivos de autenticación de Baileys.

​
Herramientas, acciones y escrituras de configuración

  • La compatibilidad con herramientas del agente incluye la acción de reacción de WhatsApp (react).
  • Puertas de acciones:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Las escrituras de configuración iniciadas por canal están habilitadas de forma predeterminada (desactívalas con channels.whatsapp.configWrites=false).

​
Solución de problemas

Síntoma: el estado del canal informa que no está vinculado.Solución:
openclaw channels login --channel whatsapp
openclaw channels status
Síntoma: cuenta vinculada con desconexiones repetidas o intentos de reconexión.Solución:
openclaw doctor
openclaw logs --follow
Si es necesario, vuelve a vincular con channels login.
Los envíos salientes fallan rápidamente cuando no existe un listener activo de gateway para la cuenta de destino.Asegúrate de que la gateway esté en ejecución y de que la cuenta esté vinculada.
Comprueba en este orden:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • entradas de la lista de permitidos groups
  • filtro de mención (requireMention + patrones de mención)
  • claves duplicadas en openclaw.json (JSON5): las entradas posteriores sobrescriben las anteriores, así que mantén un solo groupPolicy por ámbito
El runtime de gateway de WhatsApp debe usar Node. Bun está marcado como incompatible para el funcionamiento estable de la gateway de WhatsApp/Telegram.

​
Indicadores de referencia de configuración

Referencia principal: Campos de WhatsApp de alta señal:
  • acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • varias cuentas: accounts.<id>.enabled, accounts.<id>.authDir, sobrescrituras a nivel de cuenta
  • operaciones: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • comportamiento de sesión: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​
Relacionado