Zalo

​

Plugin incluido

• Instalación: openclaw plugins install @openclaw/zalo
• Versión fijada: openclaw plugins install @openclaw/zalo@2026.6.11
• Desde un repositorio local: openclaw plugins install ./path/to/local/zalo-plugin
• Detalles: Plugins

​

Configuración rápida

1. Cree un token de bot en https://bot.zaloplatforms.com (inicie sesión, cree un bot y configure los ajustes). El token es numeric_id:secret; en los bots de Marketplace, el token utilizable en tiempo de ejecución puede aparecer en el mensaje de bienvenida del bot.
2. Establezca el token, ya sea mediante la variable de entorno ZALO_BOT_TOKEN=... (solo para la cuenta predeterminada) o en la configuración.
3. Reinicie el Gateway.
4. Apruebe el código de vinculación en el primer contacto por mensaje directo (la política predeterminada para mensajes directos es la vinculación).

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

​

Qué es

​

Cómo funciona

• Los mensajes entrantes se normalizan en el sobre de canal compartido con marcadores de posición para contenido multimedia.
• Las respuestas siempre se enrutan de vuelta al mismo chat de Zalo; no se utilizan respuestas con cita (replyToMode está desactivado de forma fija).
• De forma predeterminada, se utiliza sondeo prolongado (getUpdates); el modo Webhook está disponible mediante channels.zalo.webhookUrl.
• Los grupos requieren una @mención para activar el bot; esto no se puede configurar por canal.

​

Límites

​

Control de acceso

​

Mensajes directos

• channels.zalo.dmPolicy: pairing (predeterminado) | allowlist | open | disabled.
• Vinculación: los remitentes desconocidos reciben un código de vinculación; los mensajes se ignoran hasta que se apruebe. Los códigos caducan después de 1 hora.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Detalles: Vinculación
• channels.zalo.allowFrom acepta identificadores numéricos de usuario de Zalo (sin búsqueda por nombre de usuario). open requiere "*".

​

Grupos

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restringe qué identificadores de remitente pueden activar el bot en grupos; si no está establecido, utiliza allowFrom como alternativa.
• Resolución predeterminada: cuando channels.zalo está configurado, un valor no establecido de groupPolicy se resuelve como open. Cuando channels.zalo falta por completo, el tiempo de ejecución adopta de forma segura allowlist.
• Advertencia observada en entornos reales: en algunas configuraciones de bots de Marketplace, el bot no pudo añadirse a ningún grupo. Si ocurre, compruébelo en los ajustes de Zalo Bot Platform del bot; se trata de una restricción de la plataforma, no de una política de OpenClaw.

​

Sondeo prolongado frente a Webhook

• Valor predeterminado: sondeo prolongado (no se requiere una URL pública).
• Modo Webhook: establezca channels.zalo.webhookUrl y channels.zalo.webhookSecret.
  • La URL del Webhook debe utilizar HTTPS.
  • El secreto del Webhook debe tener entre 8 y 256 caracteres.
  • Zalo envía eventos con una cabecera X-Bot-Api-Secret-Token, que se comprueba mediante una comparación de tiempo constante.
  • El HTTP del Gateway gestiona las solicitudes del Webhook en channels.zalo.webhookPath (de forma predeterminada, la ruta de la URL del Webhook).
  • Las solicitudes deben utilizar Content-Type: application/json (o un tipo multimedia +json).
  • HTTP 200 solo se devuelve después de que el evento sin procesar se almacene de forma persistente; los fallos de almacenamiento devuelven HTTP 500.
  • Según la documentación de la API de Zalo, el sondeo getUpdates y el Webhook son mutuamente excluyentes.

​

Tipos de mensajes compatibles

• Texto: compatibilidad completa, dividido en fragmentos de 2000 caracteres.
• Contenido multimedia: entrante y saliente, limitado por mediaMaxMb.
• Reacciones, hilos, encuestas y comandos nativos: no son compatibles con el Plugin.
• Transmisión: el Plugin declara la capacidad de transmisión por bloques, pero Zalo no dispone de opciones específicas para ajustar la cola de salida ni la combinación de texto (a diferencia de otros canales regionales); si esto es importante para el caso de uso, compruebe el comportamiento actual en su entorno.

​

Capacidades

​

Destinos de entrega (CLI/Cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

Solución de problemas

• Compruebe el token: openclaw channels status --probe
• Compruebe que el remitente esté aprobado (mediante vinculación o allowFrom)
• Compruebe los registros del Gateway: openclaw logs --follow

• Confirme que la URL del Webhook utiliza HTTPS
• Confirme que el secreto tiene entre 8 y 256 caracteres
• Confirme que se puede acceder al extremo HTTP del Gateway en la ruta configurada
• Confirme que el sondeo getUpdates no se esté ejecutando también (son mutuamente excluyentes)
• Una ráfaga de solicitudes puede devolver HTTP 429 (120 solicitudes / 60s por ruta+IP); espere y vuelva a intentarlo

​

Referencia de configuración

​

Contenido relacionado

• Descripción general de los canales - todos los canales compatibles
• Vinculación - autenticación de mensajes directos y flujo de vinculación
• Grupos - comportamiento de los chats grupales y activación mediante menciones
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y refuerzo de seguridad