Automatiza Zalo Personal con OpenClaw: Guía rápida

¿Alguna vez has intentado automatizar una cuenta personal en una plataforma que no ofrece una API oficial? Es un reto técnico que suele terminar en frustraciones con binarios externos o procesos complejos. Si necesitas integrar Zalo en tu flujo de trabajo de OpenClaw de forma directa, esta guía te ayudará a configurar la integración sin complicaciones innecesarias.

Zalo Personal (no oficial)

Estado: experimental. Esta integración automatiza una cuenta personal de Zalo mediante zca-js nativo dentro de OpenClaw.

Advertencia: Esta es una integración no oficial y puede resultar en la suspensión o baneo de tu cuenta. Úsala bajo tu propio riesgo.

Plugin requerido

Zalo Personal funciona como un plugin y no viene incluido en la instalación base.

• Instala mediante CLI: openclaw plugins install @openclaw/zalouser
• O desde un repositorio local: openclaw plugins install ./path/to/local/zalouser-plugin
• Detalles: Plugins

No necesitas ningún binario externo de CLI como zca o openzca.

Configuración rápida (principiante)

1. Instala el plugin (mira arriba).
2. Inicia sesión (QR, en la máquina del Gateway):
   • openclaw channels login --channel zalouser
   • Escanea el código QR con la aplicación móvil de Zalo.
3. Activa el canal:

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

4. Reinicia el Gateway (o termina la configuración).
5. El acceso por DM está configurado como “pairing” por defecto; aprueba el código de emparejamiento en el primer contacto.

Qué es esto

• Se ejecuta totalmente dentro del proceso mediante zca-js.
• Usa event listeners nativos para recibir mensajes entrantes.
• Envía respuestas directamente a través de la API de JS (texto, media, links).
• Está diseñado para casos de uso de “cuentas personales” donde la API oficial de Zalo Bot no está disponible.

Nomenclatura

El ID del canal es zalouser para dejar claro que automatiza una cuenta de usuario personal de Zalo (no oficial). Reservamos el nombre zalo para una posible integración futura con la API oficial de Zalo.

Encontrar IDs (directorio)

Usa el CLI de directorio para descubrir contactos o grupos y sus IDs:

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

Límites

• El texto de salida se divide en fragmentos de aproximadamente 2000 caracteres (límite del cliente de Zalo).
• El streaming está bloqueado por defecto.

Control de acceso (DMs)

channels.zalouser.dmPolicy admite: pairing | allowlist | open | disabled (por defecto: pairing).

channels.zalouser.allowFrom acepta IDs de usuario o nombres. Durante la configuración, los nombres se resuelven a IDs usando la búsqueda de contactos interna del plugin.

Aprueba mediante:

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

Acceso a grupos (opcional)

• Por defecto: channels.zalouser.groupPolicy = "open" (grupos permitidos). Usa channels.defaults.groupPolicy para sobrescribir este valor si no está definido.
• Restringe a una lista de permitidos con:
  • channels.zalouser.groupPolicy = "allowlist"
  • channels.zalouser.groups (las keys deben ser IDs de grupo estables; los nombres se resuelven a IDs al iniciar cuando es posible)
  • channels.zalouser.groupAllowFrom (controla qué remitentes en los grupos permitidos pueden activar el bot)
• Bloquea todos los grupos: channels.zalouser.groupPolicy = "disabled".
• El asistente de configuración puede solicitar listas de grupos permitidos.
• Al iniciar, OpenClaw resuelve los nombres de grupos y usuarios en las listas de permitidos a IDs y registra el mapeo.
• La coincidencia en la lista de grupos es solo por ID por defecto. Los nombres no resueltos se ignoran para la autenticación a menos que actives channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true es un modo de compatibilidad de emergencia que reactiva la coincidencia por nombres de grupo mutables.
• Si groupAllowFrom no está definido, el sistema usa allowFrom para las comprobaciones de remitentes en grupos.
• Las comprobaciones de remitente se aplican tanto a mensajes normales de grupo como a comandos de control (por ejemplo /new, /reset).

Ejemplo:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}

Restricción por mención en grupos

• channels.zalouser.groups.<group>.requireMention controla si las respuestas en grupo requieren una mención.
• Orden de resolución: ID/nombre exacto del grupo -> slug de grupo normalizado -> * -> por defecto (true).
• Esto se aplica tanto a grupos en allowlist como al modo de grupo abierto.
• Los comandos de control autorizados (por ejemplo /new) pueden saltarse esta restricción.
• Cuando se ignora un mensaje de grupo porque falta la mención, OpenClaw lo guarda como historial pendiente y lo incluye en el siguiente mensaje de grupo procesado.
• El límite del historial de grupo es por defecto messages.groupChat.historyLimit (valor de respaldo 50). Puedes sobrescribirlo por cuenta con channels.zalouser.historyLimit.

Ejemplo:

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}

Multicuenta

Las cuentas se mapean a perfiles de zalouser en el estado de OpenClaw. Ejemplo:

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

Escritura, reacciones y confirmaciones de entrega

• OpenClaw envía un evento de “escribiendo” antes de despachar una respuesta (en la medida de lo posible).
• La acción de reacción a mensajes react es compatible con zalouser en las acciones del canal.
  • Usa remove: true para eliminar un emoji de reacción específico de un mensaje.
  • Semántica de reacciones: Reactions
• Para mensajes entrantes que incluyen metadatos de eventos, OpenClaw envía confirmaciones de “entregado” y “visto” (en la medida de lo posible).

Solución de problemas

El inicio de sesión no se mantiene:

• openclaw channels status --probe
• Re-identifícate: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

No se resolvió el nombre del grupo o de la lista de permitidos:

• Usa IDs numéricos en allowFrom, groupAllowFrom o groups, o asegúrate de usar nombres exactos de amigos o grupos.

Actualización desde una configuración antigua basada en CLI:

• Elimina cualquier suposición sobre procesos zca externos antiguos.
• El canal ahora se ejecuta totalmente dentro de OpenClaw sin binarios de CLI externos.

Relacionado

• Channels Overview — todos los canales compatibles
• Pairing — flujo de autenticación y emparejamiento por DM
• Groups — comportamiento de chats grupales y menciones
• Channel Routing — enrutamiento de sesiones para mensajes
• Security — modelo de acceso y seguridad

Pasos siguientes

• Revisa la Seguridad del Gateway para proteger tu integración.
• Configura el Enrutamiento de Canales para gestionar múltiples cuentas.

¿Necesitas ayuda con la configuración? Prueba nuestro AI Setup Assistant.