WhatsApp

Estado: listo para producción mediante WhatsApp Web (Baileys). Gateway administra las sesiones vinculadas.

Instalación (bajo demanda)

• La incorporación (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 aún no está presente.
• Canal de desarrollo + checkout de git: usa de forma predeterminada la ruta local del Plugin.
• Stable/Beta: instala primero el Plugin oficial @openclaw/whatsapp desde ClawHub, con npm como alternativa.
• El runtime de WhatsApp se distribuye fuera del paquete npm principal de OpenClaw para que las dependencias de runtime específicas de WhatsApp permanezcan con el Plugin externo.

La instalación manual sigue disponible:

openclaw plugins install clawhub:@openclaw/whatsapp

Usa el paquete npm básico (@openclaw/whatsapp) solo cuando necesites la alternativa del registro. Fija una versión exacta solo cuando necesites 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>

Llama al solicitante actual con MeowCaller (experimental)

El Plugin de WhatsApp puede exponer whatsapp_call en turnos de agente originados en WhatsApp. La herramienta usa MeowCaller para realizar una llamada de voz de WhatsApp al solicitante autorizado actual y reproduce un mensaje TTS de OpenClaw después de que responda. La herramienta no acepta un número de destino, por lo que un prompt no puede redirigir la llamada a un tercero. Esta capacidad experimental 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 actuales:

• solo llamadas de audio salientes uno a uno
• sin números de destino arbitrarios
• sin autenticación compartida con la conexión de chat
• sin llamadas a sí mismo desde el modo de número personal/chat propio
• el audio sintetizado está limitado a 60 segundos
• sin confirmación de audibilidad en el teléfono más allá de la finalización de respuesta/reproducción/colgado de MeowCaller
• OpenClaw detiene el proceso complementario después de una ventana limitada de 115–175 segundos, incluidas las fases de conexión, respuesta, reproducción y apagado de MeowCaller

Patrones de despliegue

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

Modelo de runtime

• Gateway administra el socket de WhatsApp y el bucle de reconexión.
• El watchdog de reconexión usa la actividad del transporte de WhatsApp Web, no solo el volumen de mensajes de aplicación entrantes, por lo que una sesión silenciosa de dispositivo vinculado no se reinicia solo porque nadie haya enviado un mensaje recientemente. Un límite más largo de silencio de la aplicación aún fuerza una reconexión si siguen llegando tramas de transporte pero no se gestiona ningún mensaje de aplicación durante la ventana del watchdog; después de una reconexión transitoria para una sesión activa recientemente, esa comprobación de silencio de la aplicación usa el timeout normal de mensajes para la primera ventana de recuperación.
• Los tiempos del socket de Baileys son explícitos bajo web.whatsapp.*: keepAliveIntervalMs controla los pings de aplicación de WhatsApp Web, connectTimeoutMs controla el timeout del handshake de apertura y defaultQueryTimeoutMs controla las esperas de consultas de Baileys más los límites de operación locales de envío/presencia saliente y confirmación de lectura entrante de OpenClaw.
• Los envíos salientes requieren un listener de WhatsApp activo para la cuenta de destino.
• Los envíos a grupos adjuntan metadatos nativos de mención para tokens @+<digits> y @<digits> en texto y pies de medios cuando el token coincide con los metadatos actuales de participantes de WhatsApp, incluidos grupos respaldados por LID.
• Los chats de estado y difusión se ignoran (@status, @broadcast).
• El watchdog de reconexión sigue la actividad del transporte de WhatsApp Web, no solo el volumen de mensajes de aplicación entrantes: las sesiones silenciosas de dispositivo vinculado permanecen activas mientras continúen las tramas de transporte, pero un bloqueo del transporte fuerza la reconexión mucho antes de la ruta posterior de desconexión remota.
• Los chats directos usan reglas de sesión de DM (session.dmScope; el valor predeterminado main colapsa los DM en la sesión principal del agente).
• Las sesiones de grupo están aisladas (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters pueden ser destinos salientes explícitos con su JID nativo @newsletter. Los envíos salientes de newsletters usan metadatos de sesión de canal (agent:<agentId>:whatsapp:channel:<jid>) en lugar de semántica de sesión de DM.
• El transporte de WhatsApp Web respeta las variables de entorno proxy estándar en el host del gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / variantes en minúsculas). Prefiere la configuración de proxy a nivel de host frente a ajustes de proxy de WhatsApp específicos del canal.
• Cuando messages.removeAckAfterReply está habilitado, OpenClaw borra la reacción de confirmación de WhatsApp después de que se entregue una respuesta visible.

Prompts de aprobación

WhatsApp puede renderizar prompts de aprobación de ejecución y Plugin con reacciones 👍 / 👎. La entrega está controlada por 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. Habilitar WhatsApp como canal solo vincula el transporte; no envía prompts de aprobación a menos que la familia de aprobación correspondiente esté habilitada y enrute a WhatsApp. El modo de sesión entrega aprobaciones nativas con emoji solo para aprobaciones que se originan en WhatsApp. El modo de destino usa la canalización compartida de reenvío para destinos explícitos de WhatsApp y no crea una distribución separada a DM de aprobadores.

Las reacciones de aprobación de WhatsApp requieren aprobadores explícitos de WhatsApp desde allowFrom o "*". defaultTo controla los destinos predeterminados ordinarios de mensajes; no es un aprobador de aprobación. Los comandos manuales /approve aún pasan por la ruta normal de autorización del remitente de WhatsApp antes de la resolución de aprobación.

Hooks de Plugin y privacidad

Los mensajes entrantes de WhatsApp pueden contener contenido de mensajes personales, números de teléfono, identificadores de grupo, nombres de remitente y campos de correlación de sesión. Por ese motivo, WhatsApp no transmite las cargas de hooks message_received entrantes a los plugins a menos que optes explícitamente por ello:

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

Puedes limitar la activación a una cuenta:

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

Activa esto solo para plugins en los que confíes para recibir contenido e identificadores de mensajes entrantes de WhatsApp.

Control de acceso y activación

Enlaces ACP configurados

WhatsApp admite enlaces ACP persistentes con entradas bindings[] de 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 como +15555550123.
• Los grupos coinciden con JID de grupos de WhatsApp como 120363424282127706@g.us.
• Las listas de permitidos de grupos, la política de remitentes y el control por mención o activación se ejecutan antes de que OpenClaw asegure que exista la sesión ACP configurada.
• Un enlace ACP configurado que coincide es dueño de la ruta. Los grupos de difusión de WhatsApp no distribuyen ese turno a sesiones ordinarias de WhatsApp.

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 para turnos de chat contigo mismo
• ignorar el comportamiento de activación automática por JID de mención que de otro modo te haría ping a ti mismo
• si messages.responsePrefix no está definido, las respuestas de chat contigo mismo 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,    },  },}

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

Entrega, fragmentación y contenido multimedia

Citas de respuesta

WhatsApp admite citas de respuesta nativas, donde las respuestas salientes citan visiblemente el mensaje entrante. Contrólalo con channels.whatsapp.replyToMode.

El valor predeterminado es "off". Las anulaciones por cuenta usan channels.whatsapp.accounts.<id>.replyToMode.

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

Nivel de reacciones

channels.whatsapp.reactionLevel controla con qué amplitud el agente usa reacciones emoji en WhatsApp:

Predeterminado: "minimal".

Las anulaciones por cuenta usan channels.whatsapp.accounts.<id>.reactionLevel.

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

Reacciones de reconocimiento

WhatsApp admite reacciones de acuse inmediatas al recibir mensajes entrantes mediante channels.whatsapp.ackReaction. Las reacciones de acuse están limitadas por reactionLevel: se suprimen cuando reactionLevel es "off".

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

Notas de comportamiento:

• se envía inmediatamente después de que se acepta el mensaje entrante (antes de la respuesta)
• si ackReaction está presente sin emoji, WhatsApp usa el emoji de identidad del agente enrutado, con "👀" como alternativa; omite ackReaction o define emoji: "" para no enviar ninguna reacción de confirmación
• 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 omisión para esta comprobación
• WhatsApp usa channels.whatsapp.ackReaction (el valor heredado messages.ackReaction no se usa aquí)

Reacciones de estado del ciclo de vida

Define messages.statusReactions.enabled: true para permitir que WhatsApp reemplace la reacción de confirmación durante un turno en lugar de dejar un emoji de acuse estático. Cuando está habilitado, OpenClaw usa el mismo espacio de reacción del mensaje entrante para estados del ciclo de vida como en cola, pensando, actividad de herramientas, Compaction, completado y error.

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

Notas de comportamiento:

• channels.whatsapp.ackReaction sigue controlando si las reacciones de estado son elegibles para mensajes directos y grupos.
• La reacción de estado en cola usa el mismo emoji de confirmación efectivo que las reacciones de confirmación simples.
• WhatsApp tiene un solo espacio de reacción de bot por mensaje, por lo que las actualizaciones del ciclo de vida reemplazan la reacción actual en el mismo lugar.
• messages.removeAckAfterReply: true borra la reacción de estado final después del tiempo de retención configurado para completado/error.
• Las categorías de emoji 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).
• Puertas de acciones:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• Las escrituras de configuración iniciadas por el canal están habilitadas de forma predeterminada (deshabilítalas 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>

Prompts del sistema

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

Jerarquía de resolución para mensajes de grupo:

El mapa efectivo de groups se determina primero: si la cuenta define sus propios groups, reemplaza por completo el mapa raíz de groups (sin fusión profunda). La búsqueda de prompt se ejecuta luego en el único mapa resultante:

1. Prompt del sistema específico de grupo (groups["<groupId>"].systemPrompt): se usa cuando la entrada del grupo específico existe en el mapa y su clave systemPrompt está definida. Si systemPrompt es una cadena vacía (""), el comodín se suprime y no se aplica ningún prompt del sistema.
2. Prompt del sistema comodín de grupo (groups["*"].systemPrompt): se usa cuando la entrada del grupo específico está ausente del mapa por completo, o cuando existe pero no define ninguna clave systemPrompt.

Jerarquía de resolución para mensajes directos:

El mapa efectivo de direct se determina primero: si la cuenta define su propio direct, reemplaza por completo el mapa raíz de direct (sin fusión profunda). La búsqueda de prompt se ejecuta luego en el único mapa resultante:

1. Prompt del sistema específico de directo (direct["<peerId>"].systemPrompt): se usa cuando la entrada del par específico existe en el mapa y su clave systemPrompt está definida. Si systemPrompt es una cadena vacía (""), el comodín se suprime y no se aplica ningún prompt del sistema.
2. Prompt del sistema comodín de directo (direct["*"].systemPrompt): se usa cuando la entrada del par específico está ausente del mapa por completo, o cuando existe pero no define ninguna clave systemPrompt.

Diferencia respecto del comportamiento de varias cuentas de Telegram: En Telegram, groups raíz se suprime intencionalmente para todas las cuentas en una configuración de varias cuentas, incluso las cuentas que no definen groups propios, para evitar que un bot reciba mensajes de grupo de grupos a los que no pertenece. WhatsApp no aplica esta protección: groups raíz y direct raíz siempre son heredados por cuentas que no definen ninguna anulación a nivel de cuenta, independientemente de cuántas cuentas estén configuradas. En una configuración de varias cuentas de WhatsApp, si quieres prompts de grupo o directos por cuenta, define explícitamente el mapa completo bajo cada cuenta en lugar de depender de valores predeterminados a nivel raíz.

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. En el ámbito raíz o de cuenta, groups["*"] significa "se admiten todos los grupos" para ese ámbito.
• Añade un systemPrompt de grupo comodín solo cuando ya quieras que ese ámbito admita todos los grupos. Si aún quieres que solo un conjunto fijo de ids de grupo sea elegible, no uses groups["*"] para el prompt predeterminado. En su lugar, repite el prompt en cada entrada de grupo incluida explícitamente en la lista de permitidos.
• La admisión de grupo y la autorización de remitentes son comprobaciones separadas. groups["*"] amplía el conjunto de grupos que pueden llegar al manejo de grupos, pero por sí solo no autoriza a todos los remitentes de esos grupos. El acceso de remitentes sigue controlado por separado por channels.whatsapp.groupPolicy y channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct no tiene el mismo efecto secundario para DMs. direct["*"] solo proporciona una configuración predeterminada de chat directo después de que un DM ya haya sido admitido por dmPolicy más allowFrom o las reglas del almacén de emparejamiento.

Ejemplo:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

Punteros de referencia de configuración

Referencia principal:

• Referencia de configuración - WhatsApp

Campos de WhatsApp de alta señal:

• acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• entrega: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multicuenta: accounts.<id>.enabled, accounts.<id>.authDir, sobrescrituras a nivel de cuenta
• operaciones: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• comportamiento de sesión: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

Relacionado

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