WhatsApp

Estado: listo para producción mediante WhatsApp Web (Baileys). El Gateway es responsable de las sesiones vinculadas; no hay ningún 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 utilizan la ruta local del plugin; las instalaciones estables/beta instalan primero @openclaw/whatsapp desde ClawHub y recurren a npm si falla. 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 en el plugin externo. Instalación manual:

openclaw plugins install clawhub:@openclaw/whatsapp

Utilice el paquete npm sin prefijo (@openclaw/whatsapp) únicamente como alternativa del registro; fije una versión exacta solo para obtener 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 es responsable del socket de WhatsApp y del bucle de reconexión.
• Un monitor supervisa dos señales de forma independiente: la actividad de transporte sin procesar de WhatsApp Web y la actividad de mensajes de la aplicación. Una sesión inactiva pero conectada no se reinicia solo porque no se haya recibido ningún mensaje recientemente; solo fuerza la reconexión cuando dejan de llegar tramas de transporte durante un intervalo interno fijo (no configurable por el usuario) o los mensajes de la aplicación permanecen inactivos durante más de 4 veces el tiempo de espera normal de mensajes. Inmediatamente después de una reconexión de una sesión activa recientemente, ese primer intervalo utiliza el tiempo de espera normal de mensajes, 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 desduplicación de identificadores de mensajes entrantes; el inicio inicial mantiene la protección breve contra el historial obsoleto.
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino; de lo contrario, fallan de inmediato.
• 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 un participante, incluidos los grupos respaldados por LID.
• Se ignoran los chats de estado y difusión (@status, @broadcast).
• Los chats directos utilizan 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/Boletines de WhatsApp pueden ser destinos salientes explícitos mediante su JID @newsletter nativo, utilizando metadatos de sesión de 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 en el 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.

Llamar al solicitante actual con MeowCaller (experimental)

El plugin puede exponer whatsapp_call en los turnos del agente originados en WhatsApp. Utiliza MeowCaller para realizar una llamada de voz de WhatsApp al solicitante autorizado actual y reproducir un mensaje TTS de OpenClaw cuando 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á desactivada 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: solo llamadas de audio salientes individuales, sin números de destino arbitrarios, sin autenticación compartida con la conexión de 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 que MeowCaller complete las fases de respuesta, reproducción y finalización, 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 representar las solicitudes de aprobación de ejecución y plugins como reacciones 👍/👎, controladas mediante la configuración de reenvío de aprobaciones de nivel superior:

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

approvals.exec y approvals.plugin son independientes; activar WhatsApp como canal solo vincula el transporte y no envía nada a menos que la familia de aprobaciones correspondiente esté activada y enrutada allí. El modo de sesión entrega aprobaciones de emojis nativas únicamente para las aprobaciones que se originan en WhatsApp. El modo de destino utiliza el pipeline de reenvío compartido 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 predeterminados para mensajes normales, no una lista de aprobadores. Los comandos manuales /approve siguen pasando por la ruta normal de autorización de remitentes de WhatsApp antes de resolver la aprobación.

Reacciones a preguntas

Para una solicitud ask_user con una pregunta no secreta de selección única y entre una y cuatro opciones, WhatsApp muestra desde 1️⃣ hasta 4️⃣ junto a las etiquetas de las opciones. Reaccione a la solicitud entregada con el número correspondiente para responder. OpenClaw asigna el número a la opción canónica mediante el Gateway; se ignoran las pulsaciones obsoletas o duplicadas. Las solicitudes con varias preguntas, selección múltiple o texto libre siguen admitiendo únicamente respuestas de texto. Las reglas normales de admisión de mensajes directos y grupos de WhatsApp autorizan al remitente que reacciona.

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 difunde a los plugins las cargas útiles entrantes del hook message_received salvo que se habilite explícitamente:

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

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

Control de acceso y activación

Enlaces ACP configurados

WhatsApp admite enlaces 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 el requisito de mención/activación se ejecutan antes de que OpenClaw garantice la existencia de la sesión ACP vinculada. Un enlace coincidente controla la ruta: los grupos de difusión no distribuyen ese turno a las sesiones ordinarias de WhatsApp.

Comportamiento del número personal y del chat propio

Cuando el número propio vinculado también está presente en allowFrom, se activan las protecciones para el chat propio: se omiten las confirmaciones de lectura para los turnos del chat propio, se ignora el comportamiento de activación automática mediante el JID de mención que provocaría una mención al propio usuario y las respuestas utilizan de forma predeterminada [{identity.name}] (o [openclaw]) cuando no se establece responsePrefix para el canal o la cuenta.

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 respuestas (las respuestas salientes citan visiblemente el mensaje entrante):

Anulación por cuenta: channels.whatsapp.accounts.<id>.replyToMode.

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

Nivel de reacciones

channels.whatsapp.reactionLevel controla con qué amplitud utiliza el agente las reacciones con emojis:

Anulación 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, condicionada por reactionLevel (se suprime cuando "off"):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // siempre | menciones | nunca      },    },  },}

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 dirige el mensaje y recurre a "👀" como alternativa (omita ackReaction o establezca emoji: "" para no enviar confirmación); los errores se registran, pero no bloquean la entrega de la respuesta; el modo de grupo mentions solo reacciona en los turnos activados mediante una mención, mientras que la activación de grupo always omite esa comprobación; WhatsApp solo utiliza channels.whatsapp.ackReaction (el messages.ackReaction heredado no se aplica aquí).

Reacciones de estado del ciclo de vida

Establezca 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, pasando por estados como en cola, pensando, actividad de herramientas, Compaction, finalizado y error:

{  messages: {    statusReactions: {      enabled: true,    },  },}

Notas: channels.whatsapp.ackReaction sigue controlando la aptitud 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 y restauran la confirmación después del estado final de finalización o error.

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 (el valor predeterminado de las acciones existentes es 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

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>

Prompts del sistema

WhatsApp admite prompts 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). La búsqueda del prompt se realiza después en ese único mapa resultante:

1. Prompt específico del grupo (groups["<groupId>"].systemPrompt): se utiliza cuando existe la entrada del grupo y está definida su clave systemPrompt. Una cadena vacía ("") suprime el comodín y no aplica ningún prompt.
2. Prompt comodín de grupo (groups["*"].systemPrompt): se utiliza 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 con Telegram: Telegram suprime el valor raíz groups para todas las cuentas de una configuración con varias cuentas (incluso para las cuentas que no tienen su propio groups) para evitar que un bot reciba mensajes de grupos a los que no pertenece. WhatsApp no aplica esa protección: cualquier cuenta sin un reemplazo propio hereda los valores raíz groups/direct, 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 prompts por cuenta.

Comportamiento importante:

• channels.whatsapp.groups es tanto un mapa de configuración por grupo como la lista de permitidos de grupos a 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 solo cuando ya desee que ese ámbito admita todos los grupos. Para mantener como elegibles únicamente un conjunto fijo de identificadores de grupo, repita el prompt en cada entrada incluida explícitamente en la lista de permitidos en lugar de utilizar groups["*"].
• La admisión de grupos y la autorización de remitentes son comprobaciones independientes. groups["*"] amplía los grupos que llegan al procesamiento de grupos; no autoriza a todos los remitentes de esos grupos. Esto 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 se haya admitido mediante dmPolicy junto con allowFrom o las reglas del almacén de emparejamientos.

Ejemplo:

{  channels: {    whatsapp: {      groups: {        // Utilizar solo si deben admitirse todos los grupos en el ámbito raíz.        // Se aplica a todas las cuentas que no definen su propio mapa groups.        "*": { systemPrompt: "Prompt predeterminado para todos los grupos." },      },      direct: {        // Se aplica a todas las cuentas que no definen su propio mapa direct.        "*": { systemPrompt: "Prompt predeterminado 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 también aquí.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Centrarse en la gestión de proyectos.",            },            // Utilizar solo si deben admitirse todos los grupos en esta cuenta.            "*": { systemPrompt: "Prompt predeterminado para los grupos de trabajo." },          },          direct: {            // Esta cuenta define su propio mapa direct, por lo que las entradas direct raíz se            // sustituyen por completo. Para conservar un comodín, defina "*" explícitamente también aquí.            "+15551234567": { systemPrompt: "Prompt para un chat directo de trabajo específico." },            "*": { systemPrompt: "Prompt predeterminado para los chats directos de trabajo." },          },        },      },    },  },}

Referencias de configuración

Referencia principal: Referencia de configuración: WhatsApp

Temas relacionados

• Emparejamiento
• Grupos
• Seguridad
• Enrutamiento de canales
• Enrutamiento multiagente
• Solución de problemas