WhatsApp

Estado: listo para producción mediante WhatsApp Web (Baileys). El Gateway administra las sesiones vinculadas; no existe un canal de WhatsApp de Twilio independiente.

Instalación

openclaw onboard y openclaw channels add --channel whatsapp solicitan instalar el plugin la primera vez que se selecciona; openclaw channels login --channel whatsapp ofrece el mismo flujo de instalación si falta el plugin. Los checkouts de desarrollo usan la ruta local del plugin; las instalaciones estables/beta instalan primero @openclaw/whatsapp desde ClawHub y, si falla, recurren a npm. El entorno de ejecución de WhatsApp se distribuye fuera del paquete npm principal de OpenClaw, por lo que sus dependencias de ejecución permanecen con el plugin externo. Instalación manual:

openclaw plugins install clawhub:@openclaw/whatsapp

Use el paquete npm sin prefijo (@openclaw/whatsapp) solo como alternativa del registro; fije una versión exacta únicamente para una instalación reproducible.

Configuración rápida

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

Patrones de despliegue

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

Modelo de ejecución

• El Gateway administra el socket de WhatsApp y el bucle de reconexión.
• Un supervisor controla de forma independiente dos señales: la actividad del transporte sin procesar de WhatsApp Web y la actividad de los mensajes de la aplicación. Una sesión inactiva pero conectada no se reinicia solo porque no haya llegado ningún mensaje recientemente; únicamente fuerza una reconexión cuando dejan de llegar tramas de transporte durante un intervalo interno fijo (no configurable por el usuario) o cuando los mensajes de la aplicación permanecen inactivos durante más de 4 veces el tiempo de espera normal de los mensajes. Justo después de una reconexión de una sesión recientemente activa, ese primer intervalo usa el tiempo de espera normal más corto en lugar del intervalo de 4 veces. OpenClaw puede responder automáticamente a los mensajes sin conexión que Baileys entrega al principio de esa reconexión, dentro del límite de la duración de la deduplicación de los identificadores de mensajes entrantes; el arranque inicial conserva la protección breve contra el historial obsoleto.
• Los tiempos del socket de Baileys se definen explícitamente en web.whatsapp.*: keepAliveIntervalMs (intervalo de ping de la aplicación), connectTimeoutMs (tiempo de espera del protocolo de enlace inicial), defaultQueryTimeoutMs (esperas de consultas de Baileys, además de los tiempos de espera de OpenClaw para el envío y la presencia salientes, y para las confirmaciones de lectura entrantes).
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino; de lo contrario, fallan inmediatamente.
• Los envíos a grupos adjuntan metadatos nativos de menciones para los tokens @+<digits> y @<digits> (en el texto y en los pies de contenido multimedia) cuando el token coincide con los metadatos actuales de los participantes, incluidos los grupos basados en LID.
• Los chats de estado y difusión (@status, @broadcast) se ignoran.
• Los chats directos usan las reglas de sesión de mensajes directos (session.dmScope; el valor predeterminado main agrupa los mensajes directos en la sesión principal del agente). Las sesiones de grupo se aíslan por JID (agent:<agentId>:whatsapp:group:<jid>).
• Los canales y boletines de WhatsApp pueden ser destinos salientes explícitos mediante su JID @newsletter nativo, usando metadatos de sesión del canal (agent:<agentId>:whatsapp:channel:<jid>) en lugar de la semántica de mensajes directos.
• El transporte de WhatsApp Web respeta las variables de entorno de proxy estándar del host del Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY y sus variantes en minúsculas). Se recomienda la configuración del proxy en el host en lugar de ajustes por canal.
• Cuando messages.removeAckAfterReply está habilitado, OpenClaw elimina la reacción de confirmación después de entregar una respuesta visible.

Llamar al solicitante actual con MeowCaller (experimental)

El plugin puede exponer whatsapp_call en los turnos del agente originados en WhatsApp. Usa MeowCaller para realizar una llamada de voz de WhatsApp al solicitante autorizado actual y reproducir un mensaje TTS de OpenClaw después de que responda. La herramienta no tiene ningún parámetro de número de destino, por lo que una instrucción no puede redirigir la llamada. Está deshabilitada de forma predeterminada.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

Límites: únicamente llamadas de audio salientes individuales, sin números de destino arbitrarios, sin autenticación compartida con la conexión del chat, sin llamadas a uno mismo desde el modo de número personal o chat con uno mismo, audio sintetizado limitado a 60 segundos, sin confirmación de audibilidad en el teléfono más allá de la finalización de las fases de respuesta, reproducción y cierre de MeowCaller, y OpenClaw detiene el proceso complementario después de un intervalo limitado de 115-175 segundos (que abarca las fases de conexión, respuesta, reproducción y cierre de MeowCaller).

Solicitudes de aprobación

WhatsApp puede mostrar las solicitudes de aprobación de ejecución y plugins como reacciones 👍/👎, controladas mediante la configuración general de reenvío de aprobaciones:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec y approvals.plugin son independientes; habilitar WhatsApp como canal solo conecta el transporte y no envía nada a menos que la familia de aprobaciones correspondiente esté habilitada y enrutada allí. El modo de sesión entrega aprobaciones mediante emojis nativos únicamente para las aprobaciones que se originan en WhatsApp. El modo de destinos usa el proceso compartido de reenvío para destinos explícitos y no crea una distribución independiente a mensajes directos de aprobadores.

Las reacciones de aprobación de WhatsApp requieren aprobadores explícitos en allowFrom (o "*"). defaultTo establece destinos de mensajes predeterminados normales, no una lista de aprobadores. Los comandos manuales /approve siguen pasando por la ruta normal de autorización del remitente de WhatsApp antes de resolver la aprobación.

Hooks de plugins y privacidad

Los mensajes entrantes de WhatsApp pueden contener información personal, números de teléfono, identificadores de grupos, nombres de remitentes y campos de correlación de sesiones. WhatsApp no transmite a los plugins las cargas útiles entrantes del hook message_received a menos que se habilite expresamente:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

Limite la habilitación a una cuenta mediante channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. Habilítela únicamente para plugins a los que confíe el contenido y los identificadores entrantes de WhatsApp.

Control de acceso y activación

Vinculaciones ACP configuradas

WhatsApp admite vinculaciones ACP persistentes mediante bindings[] en el nivel superior:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

Los chats directos coinciden con números E.164; los grupos coinciden con JID de grupos de WhatsApp. Las listas de grupos permitidos, la política de remitentes y los requisitos de mención o activación se aplican antes de que OpenClaw garantice la existencia de la sesión ACP vinculada. Una vinculación coincidente controla la ruta: los grupos de difusión no distribuyen ese turno a sesiones normales de WhatsApp.

Comportamiento del número personal y del chat consigo mismo

Cuando el número propio vinculado también está presente en allowFrom, se activan las protecciones del chat consigo mismo: se omiten las confirmaciones de lectura en esos turnos, se ignora el comportamiento de activación automática mediante el JID de mención que haría que se mencionara a sí mismo y, cuando messages.responsePrefix no está definido, las respuestas usan de forma predeterminada [{identity.name}] (o [openclaw]).

Normalización de mensajes y contexto

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

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

Entrega, fragmentación y contenido multimedia

Citas en respuestas

channels.whatsapp.replyToMode controla las citas nativas en las respuestas (las respuestas salientes citan visiblemente el mensaje entrante):

Reemplazo por cuenta: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

Nivel de reacciones

channels.whatsapp.reactionLevel controla la amplitud con la que el agente utiliza reacciones con emojis:

Reemplazo por cuenta: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

Reacciones de confirmación

channels.whatsapp.ackReaction envía una reacción inmediata al recibir un mensaje entrante, sujeta a reactionLevel (se omite cuando "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

Notas: se envía inmediatamente después de aceptar el mensaje entrante (antes de responder); si ackReaction está presente sin emoji, WhatsApp utiliza el emoji de identidad del agente al que se ha dirigido el mensaje y recurre a "👀" como alternativa (omita ackReaction o defina emoji: "" para no enviar ninguna confirmación); los fallos se registran, pero no bloquean la entrega de la respuesta; el modo de grupo mentions solo reacciona en los turnos activados por una mención, mientras que la activación de grupo always omite esa comprobación; WhatsApp utiliza únicamente channels.whatsapp.ackReaction (el valor heredado messages.ackReaction no se aplica aquí).

Reacciones de estado del ciclo de vida

Defina messages.statusReactions.enabled: true para permitir que WhatsApp sustituya la reacción de confirmación durante un turno, en lugar de dejar un emoji de recepción estático, alternando entre estados como en cola, pensando, actividad de herramientas, Compaction, completado y error:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

Notas: channels.whatsapp.ackReaction sigue controlando la elegibilidad para mensajes directos y grupos; el estado en cola utiliza el mismo emoji efectivo que las reacciones de confirmación simples; WhatsApp dispone de un espacio de reacción del bot por mensaje, por lo que las actualizaciones del ciclo de vida sustituyen la reacción actual; messages.removeAckAfterReply: true elimina la reacción de estado final después del periodo configurado de permanencia de completado/error; las categorías de emojis de herramientas incluyen tool, coding, web, deploy, build y concierge.

Varias cuentas y credenciales

Herramientas, acciones y escrituras de configuración

• La compatibilidad con herramientas del agente incluye la acción de reacción de WhatsApp (react).
• Controles de acciones: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (las acciones existentes tienen como valor predeterminado true), channels.whatsapp.actions.calls (valor predeterminado false; consulte MeowCaller más arriba).
• Las escrituras de configuración iniciadas por el canal están habilitadas de forma predeterminada; deshabilítelas mediante channels.whatsapp.configWrites: false.

Solución de problemas

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

Indicaciones del sistema

WhatsApp admite indicaciones del sistema al estilo de Telegram para grupos y chats directos mediante los mapas groups y direct.

Resolución para mensajes de grupo: primero se determina el mapa groups efectivo; si la cuenta define su propia clave groups, esta sustituye por completo el mapa raíz groups (sin combinación profunda). A continuación, la búsqueda de la indicación se ejecuta sobre ese único mapa resultante:

1. Indicación específica del grupo (groups["<groupId>"].systemPrompt): se usa cuando existe la entrada del grupo y su clave systemPrompt está definida. Una cadena vacía ("") suprime el comodín y no aplica ninguna indicación.
2. Indicación comodín del grupo (groups["*"].systemPrompt): se usa cuando la entrada específica del grupo no existe o existe sin una clave systemPrompt.

La resolución para mensajes directos sigue el mismo patrón con el mapa direct y direct["*"].

Diferencia respecto a Telegram: Telegram suprime el valor raíz groups para todas las cuentas de una configuración con varias cuentas (incluso para las cuentas sin un groups propio) para impedir que un bot reciba mensajes de grupos a los que no pertenece. WhatsApp no aplica esa protección: los valores raíz groups/direct se heredan en cualquier cuenta sin una sobrescritura propia, independientemente del número de cuentas. En una configuración de WhatsApp con varias cuentas, defina explícitamente el mapa completo en cada cuenta si desea indicaciones específicas por cuenta.

Comportamiento importante:

• channels.whatsapp.groups es tanto un mapa de configuración por grupo como la lista de permitidos de grupos en el nivel de chat. Tanto en el ámbito raíz como en el de la cuenta, groups["*"] significa «se admiten todos los grupos» para ese ámbito.
• Añada un comodín systemPrompt únicamente cuando ya desee que ese ámbito admita todos los grupos. Para mantener como elegibles únicamente un conjunto fijo de identificadores de grupo, repita la indicación en cada entrada incluida explícitamente en la lista de permitidos en lugar de usar groups["*"].
• La admisión de grupos y la autorización de remitentes son comprobaciones independientes. groups["*"] amplía qué grupos llegan al procesamiento de grupos; no autoriza a todos los remitentes de esos grupos. Eso sigue controlado por groupPolicy/groupAllowFrom.
• channels.whatsapp.direct no tiene ningún efecto secundario equivalente para los mensajes directos: direct["*"] solo proporciona una configuración predeterminada después de que un mensaje directo ya haya sido admitido mediante dmPolicy junto con allowFrom o las reglas del almacén de emparejamiento.

Ejemplo:

{  channels: {    whatsapp: {      groups: {        // Úselo únicamente si se deben admitir todos los grupos en el ámbito raíz.        // Se aplica a todas las cuentas que no definan su propio mapa de grupos.        "*": { systemPrompt: "Indicación predeterminada para todos los grupos." },      },      direct: {        // Se aplica a todas las cuentas que no definan su propio mapa de mensajes directos.        "*": { systemPrompt: "Indicación predeterminada para todos los chats directos." },      },      accounts: {        work: {          groups: {            // Esta cuenta define sus propios grupos, por lo que los grupos raíz se            // sustituyen por completo. Para conservar un comodín, defina "*" explícitamente aquí también.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Céntrese en la gestión de proyectos.",            },            // Úselo únicamente si se deben admitir todos los grupos en esta cuenta.            "*": { systemPrompt: "Indicación predeterminada para los grupos de trabajo." },          },          direct: {            // Esta cuenta define su propio mapa de mensajes directos, por lo que las entradas            // directas raíz se sustituyen por completo. Para conservar un comodín, defina "*" explícitamente aquí también.            "+15551234567": { systemPrompt: "Indicación para un chat directo de trabajo específico." },            "*": { systemPrompt: "Indicación predeterminada para los chats directos de trabajo." },          },        },      },    },  },}

Referencias de configuración

Referencia principal: Referencia de configuración: WhatsApp

Contenido relacionado

• Emparejamiento
• Grupos
• Seguridad
• Enrutamiento de canales
• Enrutamiento de varios agentes
• Solución de problemas