WhatsApp

Estado: listo para producción mediante WhatsApp Web (Baileys). Gateway gestiona 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: usa el paquete npm @openclaw/whatsapp en la etiqueta de versión oficial actual.

La instalación manual sigue disponible:

openclaw plugins install @openclaw/whatsapp

Usa el paquete base para seguir la etiqueta de versión oficial actual. Fija una versión exacta solo cuando necesites una instalación reproducible.

En Windows, el Plugin de WhatsApp necesita Git en PATH durante la instalación de npm porque una de sus dependencias de Baileys/libsignal se obtiene desde una URL de git. Instala Git for Windows, luego reinicia la shell y vuelve a ejecutar la instalación:

winget install --id Git.Git -e

Portable Git también funciona si su directorio bin está en PATH.

# 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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# Patrones de despliegue

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

# Modelo de tiempo de ejecución

• Gateway gestiona el socket de WhatsApp y el bucle de reconexión.
• El vigilante de reconexión usa la actividad de transporte de WhatsApp Web, no solo el volumen de mensajes entrantes de la aplicación, 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 sigue forzando una reconexión si los frames de transporte continúan llegando pero no se procesa ningún mensaje de aplicación durante la ventana del vigilante; después de una reconexión transitoria para una sesión activa recientemente, esa comprobación de silencio de la aplicación usa el tiempo de espera 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 tiempo de espera del handshake de apertura y defaultQueryTimeoutMs controla los tiempos de espera de consultas de Baileys.
• 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 vigilante de reconexión sigue la actividad de transporte de WhatsApp Web, no solo el volumen de mensajes entrantes de la aplicación: las sesiones silenciosas de dispositivo vinculado permanecen activas mientras continúen los frames de transporte, pero un bloqueo del transporte fuerza una 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>).
• Los canales/newsletters de WhatsApp pueden ser destinos salientes explícitos con su JID nativo @newsletter. Los envíos salientes a 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 de proxy estándar en el host de 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 acuse de WhatsApp después de que se entrega una respuesta visible.

# 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 cargas de hook message_received entrantes a plugins a menos que lo habilites explícitamente:

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

Puedes limitar la habilitación a una cuenta:

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

Habilita 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

# Comportamiento con número personal y chat contigo mismo

Cuando el número propio vinculado también está presente en allowFrom, se activan las salvaguardas de chat contigo mismo de WhatsApp:

• omitir confirmaciones de lectura para turnos de chat contigo mismo
• ignorar 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á 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 multimedia

# Citas en respuestas

WhatsApp admite citas nativas en respuestas, 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 reacción

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

Predeterminado: "minimal".

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

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

# Reacciones de acuse

WhatsApp admite reacciones de acuse inmediatas al recibir mensajes entrantes mediante channels.whatsapp.ackReaction. Las reacciones de acuse 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 el mensaje entrante (antes de la respuesta)
• los fallos se registran, pero no bloquean la entrega normal de la respuesta
• el modo de grupo mentions reacciona en turnos activados por menciones; 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í)

# 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 escrituras de configuración iniciadas por el canal están activadas de forma predeterminada (desactivar mediante channels.whatsapp.configWrites=false).

# Solución de problemas

openclaw channels login --channel whatsapp
openclaw channels status

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

openclaw doctor
openclaw logs --follow

# Prompts del sistema

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

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

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

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

Jerarquía de resolución para mensajes directos:

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

1. Prompt del sistema específico 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 directo (direct["*"].systemPrompt): se usa cuando la entrada del par específico está totalmente ausente del mapa, o cuando existe pero no define ninguna clave systemPrompt.

Diferencia respecto al comportamiento multicuenta de Telegram: En Telegram, la raíz groups se suprime intencionalmente para todas las cuentas en una configuración multicuenta, incluso para cuentas que no definen sus propios groups, para evitar que un bot reciba mensajes de grupos a los que no pertenece. WhatsApp no aplica esta protección: la raíz groups y la raíz direct siempre las heredan las cuentas que no definen ninguna sobrescritura a nivel de cuenta, independientemente de cuántas cuentas estén configuradas. En una configuración multicuenta 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 los 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 sea apto un conjunto fijo de IDs de grupo, no uses groups["*"] como valor predeterminado del prompt. En su lugar, repite el prompt en cada entrada de grupo incluida explícitamente en la lista de permitidos.
• La admisión de grupos y la autorización de remitentes son comprobaciones separadas. groups["*"] amplía el conjunto de grupos que pueden llegar al manejo de grupos, pero no autoriza por sí solo a todos los remitentes de esos grupos. El acceso de remitentes sigue controlándose por separado mediante channels.whatsapp.groupPolicy y channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct no tiene el mismo efecto secundario para los DM. 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 por 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.
            "[email protected]": {
              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 alta señal de WhatsApp:

• 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