Zalo personal

Estado: experimental. Esta integración automatiza una cuenta personal de Zalo mediante zca-js nativo, dentro del proceso y sin ningún binario CLI externo.

Instalación

Zalo Personal es un plugin externo oficial que no está incluido en el núcleo. Instálelo antes de usarlo:

openclaw plugins install @openclaw/zalouser

• Fijar una versión: openclaw plugins install @openclaw/zalouser@<version>
• Desde una copia de trabajo del código fuente: openclaw plugins install ./path/to/local/zalouser-plugin
• Detalles: Plugins

Configuración rápida

1. Instale el plugin (como se indica arriba).
2. Inicie sesión (mediante QR, en la máquina del Gateway):
   • openclaw channels login --channel zalouser
   • Escanee el código QR con la aplicación móvil de Zalo.
3. Active el canal:

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

4. Reinicie el Gateway (o finalice la configuración).
5. El acceso por mensaje directo utiliza el emparejamiento de forma predeterminada; apruebe el código de emparejamiento en el primer contacto.

Qué es

• Se ejecuta íntegramente dentro del proceso mediante la biblioteca zca-js (sin ningún binario externo zca/openzca).
• Utiliza escuchas de eventos nativas (message, error) para recibir mensajes entrantes.
• Envía respuestas directamente mediante la API de JS (texto, contenido multimedia y enlaces).
• Está diseñado para casos de uso de «cuentas personales» en los que la API para bots de Zalo no está disponible.

Nomenclatura

El identificador del canal es zalouser para dejar claro que automatiza una cuenta personal de usuario de Zalo (de forma no oficial). zalo está reservado para una posible integración oficial futura con la API de Zalo.

Búsqueda de identificadores (directorio)

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

Límites

• El texto saliente se divide en fragmentos de 2000 caracteres (límite del cliente de Zalo).
• No se admite la transmisión en streaming.
• Los identificadores de mensajes entrantes completados se conservan durante 30 días, con un límite de las 1000 entradas más recientes por cuenta.

Durabilidad de los mensajes entrantes

OpenClaw almacena cada devolución de llamada de mensaje zca-js sin procesar antes de procesarla. Los mensajes pendientes se reanudan desde la cola de la cuenta después de reiniciar el Gateway y el procesamiento permanece serializado por chat directo o grupo.

La escucha del socket zca-js no expone una confirmación de entrega ni reproduce automáticamente los mensajes antiguos después de volver a conectarse. Por tanto, la cola duradera protege el intervalo de fallo local después de que una devolución de llamada llegue a OpenClaw; no puede recuperar un mensaje que el socket nunca entregó. Las marcas de eliminación para la reproducción sirven principalmente como protección frente a devoluciones de llamada repetidas con el mismo identificador de mensaje de Zalo.

Control de acceso (mensajes directos)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (valor predeterminado: pairing).

channels.zalouser.allowFrom debe utilizar identificadores estables de usuarios de Zalo. También puede hacer referencia a grupos estáticos de acceso de remitentes (accessGroup:<name>). Durante la configuración interactiva, los nombres introducidos pueden resolverse como identificadores mediante la búsqueda de contactos dentro del proceso del plugin.

Si permanece un nombre sin procesar en la configuración, el inicio solo lo resuelve cuando channels.zalouser.dangerouslyAllowNameMatching: true está activado. Sin esta habilitación explícita, las comprobaciones de remitentes durante la ejecución solo utilizan identificadores y los nombres sin procesar se ignoran para la autorización.

Apruebe mediante:

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

Acceso a grupos (opcional)

• Valor predeterminado: channels.zalouser.groupPolicy = "allowlist" (los grupos requieren una entrada explícita en la lista de permitidos).
• Abrir todos los grupos: channels.zalouser.groupPolicy = "open".
• Bloquear todos los grupos: channels.zalouser.groupPolicy = "disabled".
• Con groupPolicy = "allowlist":
  • Las claves de channels.zalouser.groups deben ser identificadores estables de grupos; los nombres solo se resuelven como identificadores al iniciar cuando channels.zalouser.dangerouslyAllowNameMatching: true está activado.
  • channels.zalouser.groupAllowFrom controla qué remitentes de los grupos permitidos pueden activar el bot; se puede hacer referencia a grupos estáticos de acceso de remitentes mediante accessGroup:<name>.
• El asistente de configuración puede solicitar listas de grupos permitidos.
• De forma predeterminada, la coincidencia con la lista de grupos permitidos solo utiliza identificadores. Los nombres sin resolver se ignoran para la autorización, salvo que channels.zalouser.dangerouslyAllowNameMatching: true esté activado.
• channels.zalouser.dangerouslyAllowNameMatching: true es un modo de compatibilidad de emergencia que vuelve a activar la resolución de nombres mutables durante el inicio y la coincidencia con nombres de grupos durante la ejecución.
• groupAllowFrom no recurre a allowFrom para los mensajes de grupo normales: si se deja vacío en un grupo incluido en la lista de permitidos, cualquier remitente podrá usar ese grupo. Los comandos de control autorizados (por ejemplo, /new) son la excepción; las comprobaciones de remitentes de comandos recurren a allowFrom cuando groupAllowFrom está vacío.

Ejemplo:

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

Restricción por mención en grupos

• channels.zalouser.groups.<group>.requireMention controla si las respuestas de grupo requieren una mención.
• Orden de resolución: identificador del grupo -> alias group:<id> -> nombre/slug del grupo (los candidatos basados en nombres solo se aplican cuando dangerouslyAllowNameMatching: true) -> * -> valor predeterminado (true).
• Se aplica tanto a los grupos de la lista de permitidos como al modo de grupos abiertos.
• Citar un mensaje del bot cuenta como una mención implícita para activar el grupo.
• Los comandos de control autorizados (por ejemplo, /new) pueden omitir la restricción por mención.
• Cuando se omite un mensaje de grupo porque se requiere una mención, OpenClaw lo almacena como historial de grupo pendiente y lo incluye en el siguiente mensaje de grupo procesado.
• Límite del historial del grupo: channels.zalouser.historyLimit, después messages.groupChat.historyLimit y, por último, un valor alternativo de 50.

Ejemplo:

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

Varias cuentas

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

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

Variables de entorno

La selección del perfil también puede proceder de variables de entorno:

Los nombres de perfil seleccionan las credenciales de inicio de sesión de Zalo guardadas en el estado de OpenClaw. Orden de resolución:

1. profile explícito en la configuración.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. El identificador de la cuenta para las cuentas no predeterminadas, o default para la cuenta predeterminada.

En configuraciones con varias cuentas, se recomienda establecer profile en cada cuenta de la configuración para evitar que una sola variable de entorno haga que varias cuentas compartan la misma sesión de inicio de sesión.

Escritura, reacciones y confirmaciones de entrega

• OpenClaw envía un evento de escritura 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.
  • Utilice remove: true para eliminar un emoji de reacción específico de un mensaje.
  • Semántica de las reacciones: Reacciones
• Para los mensajes entrantes que incluyen metadatos de eventos, OpenClaw envía confirmaciones de entrega y lectura (en la medida de lo posible).

Solución de problemas

El inicio de sesión no persiste:

• openclaw channels status --probe
• Vuelva a iniciar sesión: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

No se pudo resolver el nombre de la lista de permitidos o del grupo:

• Utilice identificadores numéricos en allowFrom/groupAllowFrom e identificadores estables de grupos en groups. Si necesita expresamente nombres exactos de amigos o grupos, active channels.zalouser.dangerouslyAllowNameMatching: true.

Actualización desde una configuración externa antigua basada en zca/CLI:

• Elimine cualquier supuesto relacionado con un proceso externo zca; ahora el canal se ejecuta íntegramente dentro del proceso mediante zca-js, sin ningún binario CLI externo.

Contenido relacionado

• Descripción general de los canales - todos los canales compatibles
• Emparejamiento - autenticación de mensajes directos y flujo de emparejamiento
• Grupos - comportamiento de los chats de grupo y restricción por mención
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y refuerzo de la seguridad