Canal Zalo Personal de OpenClaw
Mensajería
Medio
Conecta OpenClaw a tu cuenta personal de Zalo utilizando la herramienta no oficial zca-cli. A diferencia de la integracion con la plataforma Zalo Bot, este canal permite que tu asistente de IA opere a traves de una cuenta personal real de Zalo, con soporte para chats grupales, medios y listas de amigos. La autenticacion se realiza escaneando un QR code, igual que al vincular un nuevo dispositivo.
Info rápida
DificultadMedio
CategoríaMensajería
Funciones compatibles3 / 6
Zalo Personal Funciones compatibles
Mensajes de texto
Compatible
Medios y archivos
Compatible
Reacciones
No compatible
Hilos
No compatible
Mensajes de voz
No compatible
Chat grupal
Compatible
Zalo Personal Requisitos previos
- Una cuenta personal de Zalo (cuenta estandar, no un Official Account)
- El binario zca instalado y disponible en el PATH de tu sistema
- OpenClaw Gateway en ejecucion y configurado
- La aplicacion movil de Zalo para escanear el QR code durante el inicio de sesion
Zalo Personal Configuración rápida
1
Instalar el plugin zalouser y zca-cli
Instala el plugin de OpenClaw con 'openclaw plugins install @openclaw/zalouser'. Luego instala la herramienta zca-cli y asegurate de que este en tu PATH. Verifica con 'zca --version'.
2
Iniciar sesion mediante QR code
Ejecuta 'openclaw channels login --channel zalouser' para mostrar un QR code en tu terminal. Abre la aplicacion Zalo en tu telefono y escanea el QR code para autenticar la sesion.
3
Configurar y comenzar a chatear
Agrega la configuracion del canal zalouser en ~/.openclaw/openclaw.json con tus preferencias de dmPolicy y groupPolicy. Inicia el Gateway con 'openclaw start' y envia un mensaje a tu cuenta de Zalo para probar.
Zalo Personal Ejemplo de configuración
config.json
{
"channels": {
"zalouser": {
"enabled": true,
"dmPolicy": "pairing",
"groupPolicy": "open"
}
}
}Zalo Personal Documentación Detallada
Vision general de la arquitectura
OpenClaw se conecta a Zalo a traves de la herramienta zca-cli, un cliente de linea de comandos no oficial para cuentas personales de Zalo. A diferencia de la integracion con la plataforma Zalo Bot (que utiliza APIs HTTP), este canal usa el binario zca para escuchar mensajes entrantes y enviar respuestas salientes.
El Gateway ejecuta 'zca listen' como un proceso en segundo plano para recibir mensajes en tiempo real, y utiliza 'zca msg' para enviar respuestas. Este enfoque funciona completamente en local: no se necesita URL publica, Webhook ni certificado HTTPS.
Dado que utiliza una cuenta personal, el bot puede participar en chats grupales, acceder a listas de amigos y enviar medios, funcionalidades que no estan disponibles a traves de la plataforma Bot oficial.
Esta es una integracion no oficial. Su uso puede conllevar la suspension o el bloqueo de tu cuenta de Zalo. Utiliza una cuenta dedicada en lugar de tu cuenta personal principal.
La herramienta zca-cli gestiona la capa de protocolo. Mantenla actualizada para asegurar la compatibilidad con el servicio de Zalo.
Esta es una integracion experimental que utiliza una herramienta no oficial. Zalo puede suspender o bloquear cuentas que utilicen automatizacion de terceros. Usala bajo tu propia responsabilidad.
Instalacion de zca-cli
El binario zca-cli es un requisito previo para este canal. Debe estar instalado y accesible en el PATH de tu sistema antes de que el Gateway pueda utilizar el canal Zalo Personal.
Despues de la instalacion, verifica que funciona correctamente ejecutando 'zca --version' en tu terminal. Si el comando no se encuentra, revisa la configuracion de tu PATH o reinstala la herramienta.
terminal
zca --versionSi zca esta instalado pero no esta en el PATH, puedes agregar su directorio al PATH en el perfil de tu shell (~/.bashrc, ~/.zshrc, etc.).
Autenticacion por QR Code
La autenticacion se realiza escaneando un QR code con tu aplicacion movil de Zalo, de forma similar a como vinculas un nuevo dispositivo. No se necesitan API Tokens ni Bot Tokens.
Ejecuta el comando de inicio de sesion para mostrar el QR code en tu terminal. Abre Zalo en tu telefono, navega al escaner QR y escanea el codigo. La sesion se establecera y las credenciales se almacenaran localmente.
Si la sesion no persiste despues de un reinicio, intenta cerrar sesion y volver a iniciarla para renovar la sesion.
terminal
# Login
openclaw channels login --channel zalouser
# If login doesn't persist, re-authenticate
openclaw channels logout --channel zalouser
openclaw channels login --channel zalouserManten tu telefono conectado a Internet durante el escaneo del QR code. La sesion se valida a traves de los servidores de Zalo.
Politicas de mensajes directos
Las politicas de DM (mensajes directos) controlan quien puede interactuar con tu asistente de IA a traves de mensajes privados. OpenClaw soporta cuatro politicas:
• pairing (predeterminado) — Los contactos nuevos reciben un codigo de emparejamiento cuando envian su primer mensaje. Apruebalos mediante 'openclaw pairing approve zalouser <code>'. Los codigos expiran despues de 1 hora.
• allowlist — Solo los IDs de usuario o nombres listados en allowFrom pueden enviar mensajes al bot. Los nombres se resuelven a IDs mediante 'zca friend find'.
• open — Cualquier persona que envie un mensaje a la cuenta recibe una respuesta.
• disabled — La gestion de mensajes directos esta completamente desactivada.
openclaw.json
{
"channels": {
"zalouser": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789", "Friend Name"]
}
}
}La politica 'open' permite que cualquier persona interactue con tu cuenta personal. Como se trata de una cuenta real de Zalo visible para tus contactos, usala con precaucion.
Gestion de chats grupales
A diferencia de la integracion con la plataforma Zalo Bot, Zalo Personal soporta completamente los chats grupales. Por defecto, groupPolicy esta configurado en 'open', lo que significa que el bot respondera en todas las conversaciones de grupo.
Puedes restringir el acceso a grupos usando la politica 'allowlist' con un mapeo de groups. Los grupos pueden referenciarse por su ID numerico o por su nombre.
Establece groupPolicy en 'disabled' para ignorar completamente todos los mensajes de grupo.
openclaw.json
{
"channels": {
"zalouser": {
"groupPolicy": "allowlist",
"groups": {
"123456789": { "allow": true },
"Work Chat": { "allow": true }
}
}
}
}Usa 'openclaw directory groups list --channel zalouser --query "name"' para encontrar IDs y nombres de grupos.
Los nombres de grupo distinguen entre mayusculas y minusculas. Usa el nombre exacto tal como aparece en tu aplicacion de Zalo.
Gestion de mensajes
OpenClaw soporta el envio de mensajes de texto, imagenes, archivos y enlaces a traves de Zalo Personal. Los mensajes de texto se dividen automaticamente en fragmentos de aproximadamente 2.000 caracteres para cumplir con los limites del cliente de Zalo.
Los mensajes entrantes de contactos y grupos se reciben a traves del proceso 'zca listen' y se reenvian a la IA. Las respuestas salientes se envian usando 'zca msg'.
Las respuestas en streaming estan bloqueadas por defecto debido a la restriccion del limite de caracteres.
Las respuestas largas de la IA se dividen automaticamente en multiples mensajes en el limite de aproximadamente 2.000 caracteres.
Las capacidades de envio de medios dependen de la version de zca-cli instalada. Mantenla actualizada para la mejor compatibilidad.
Configuracion de multiples cuentas
OpenClaw soporta la ejecucion simultanea de multiples cuentas personales de Zalo mediante la asignacion a diferentes perfiles de zca. Cada cuenta tiene su propio nombre de perfil, politica de DM y configuracion de grupos.
Esto es util si deseas ejecutar asistentes de IA separados para diferentes propositos, por ejemplo, una cuenta de trabajo y una cuenta personal.
openclaw.json
{
"channels": {
"zalouser": {
"enabled": true,
"defaultAccount": "default",
"accounts": {
"work": {
"enabled": true,
"profile": "work"
},
"personal": {
"enabled": true,
"profile": "personal"
}
}
}
}
}Directorio y descubrimiento
El canal Zalo Personal proporciona comandos de directorio para descubrir amigos y grupos en tu cuenta. Son utiles para encontrar IDs de usuario para listas de permitidos o IDs de grupo para politicas de grupo.
Puedes ver tu propio perfil, buscar amigos por nombre y buscar grupos por nombre, todo desde la linea de comandos.
terminal
# View your profile
openclaw directory self --channel zalouser
# Search friends
openclaw directory peers list --channel zalouser --query "name"
# Search groups
openclaw directory groups list --channel zalouser --query "work"Zalo Personal Referencia de Configuración
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Habilitar o deshabilitar el canal Zalo Personal |
| dmPolicy | string | "pairing" | Controla quien puede enviar mensajes directos al bot. Opciones: pairing, allowlist, open, disabled |
| allowFrom | string[] | [] | IDs o nombres de usuario permitidos para enviar mensajes al bot (cuando dmPolicy es allowlist) |
| groupPolicy | string | "open" | Controla el comportamiento de los chats grupales. Opciones: open, allowlist, disabled |
| groups | object | {} | Mapeo de IDs o nombres de grupo a objetos de permisos (cuando groupPolicy es allowlist) |
| defaultAccount | string | "default" | El nombre del perfil zca predeterminado a utilizar |
| accounts.<id>.enabled | boolean | true | Habilitar o deshabilitar una cuenta especifica en el modo de multiples cuentas |
| accounts.<id>.profile | string | "" | El nombre del perfil zca para una cuenta especifica |
enabled
Type: booleanDefault: false
Habilitar o deshabilitar el canal Zalo Personal
dmPolicy
Type: stringDefault: "pairing"
Controla quien puede enviar mensajes directos al bot. Opciones: pairing, allowlist, open, disabled
allowFrom
Type: string[]Default: []
IDs o nombres de usuario permitidos para enviar mensajes al bot (cuando dmPolicy es allowlist)
groupPolicy
Type: stringDefault: "open"
Controla el comportamiento de los chats grupales. Opciones: open, allowlist, disabled
groups
Type: objectDefault: {}
Mapeo de IDs o nombres de grupo a objetos de permisos (cuando groupPolicy es allowlist)
defaultAccount
Type: stringDefault: "default"
El nombre del perfil zca predeterminado a utilizar
accounts.<id>.enabled
Type: booleanDefault: true
Habilitar o deshabilitar una cuenta especifica en el modo de multiples cuentas
accounts.<id>.profile
Type: stringDefault: ""
El nombre del perfil zca para una cuenta especifica
Zalo Personal Preguntas Frecuentes
Zalo Personal Solución de Problemas
Comando zca no encontrado
El binario zca-cli no esta instalado o no esta en el PATH de tu sistema.
Instala zca-cli y asegurate de que este en tu PATH. Verifica con 'zca --version'. Si esta instalado pero no se encuentra, agrega su directorio de instalacion a tu PATH en ~/.bashrc o ~/.zshrc.
El inicio de sesion por QR code falla o la sesion no persiste
La sesion de Zalo puede haber expirado o la autenticacion inicial fue incompleta.
Intenta cerrar sesion y volver a iniciarla: 'openclaw channels logout --channel zalouser' y luego 'openclaw channels login --channel zalouser'. Asegurate de que tu telefono tenga una conexion a Internet estable durante el escaneo del QR code.
El bot no responde a los mensajes de grupo
groupPolicy puede estar configurado en 'disabled' o en 'allowlist' sin que el grupo este listado.
Verifica tu configuracion de groupPolicy. Si usas 'allowlist', asegurate de que el ID o nombre del grupo este listado en la configuracion de groups. Usa 'openclaw directory groups list --channel zalouser' para encontrar el ID de grupo correcto.
Los mensajes no se reciben
El proceso zca listen puede no estar en ejecucion, o la sesion ha expirado.
Ejecuta 'openclaw channels status --probe' para diagnosticar la conexion. Si la sesion ha expirado, vuelve a autenticarte mediante el inicio de sesion por QR code. Revisa los logs del Gateway para mensajes de error especificos.
La cuenta fue suspendida o bloqueada
Zalo detecto automatizacion no oficial en la cuenta.
Este es un riesgo conocido al usar integraciones no oficiales. Contacta al soporte de Zalo para intentar recuperar la cuenta. Considera cambiar a la integracion oficial con la plataforma Zalo Bot (canal zalo) que no tiene riesgo de bloqueo, aunque no soporta chats grupales.