Regional platforms

Zalo personnel

Statut : expérimental. Cette intégration automatise un compte Zalo personnel via zca-js natif dans OpenClaw.

Plugin intégré

Zalo Personal est fourni comme Plugin intégré dans les versions actuelles d’OpenClaw ; les builds empaquetés normaux ne nécessitent donc pas d’installation séparée.

Si vous utilisez un ancien build ou une installation personnalisée qui exclut Zalo Personal, installez directement le package npm :

Installer via la CLI : openclaw plugins install @openclaw/zalouser
Version épinglée : openclaw plugins install @openclaw/[email protected]
Ou depuis un checkout source : openclaw plugins install ./path/to/local/zalouser-plugin
Détails : Plugins

Aucun binaire CLI externe zca/openzca n’est requis.

Configuration rapide (débutant)

Vérifiez que le Plugin Zalo Personal est disponible.
- Les versions OpenClaw empaquetées actuelles l’intègrent déjà.
- Les installations plus anciennes/personnalisées peuvent l’ajouter manuellement avec les commandes ci-dessus.
Connectez-vous (QR, sur la machine du Gateway) :
- openclaw channels login --channel zalouser
- Scannez le code QR avec l’application mobile Zalo.
Activez le canal :

json5

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

Redémarrez le Gateway (ou terminez la configuration).
L’accès DM utilise le jumelage par défaut ; approuvez le code de jumelage au premier contact.

Ce que c’est

S’exécute entièrement dans le processus via zca-js.
Utilise des écouteurs d’événements natifs pour recevoir les messages entrants.
Envoie les réponses directement via l’API JS (texte/média/lien).
Conçu pour les cas d’usage de « compte personnel » lorsque l’API Zalo Bot n’est pas disponible.

Nommage

L’id de canal est zalouser pour indiquer explicitement que cela automatise un compte utilisateur Zalo personnel (non officiel). Nous réservons zalo à une éventuelle future intégration officielle de l’API Zalo.

Trouver les ID (répertoire)

Utilisez la CLI de répertoire pour découvrir les pairs/groupes et leurs ID :

bash

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

Limites

Le texte sortant est découpé en segments d’environ 2000 caractères (limites du client Zalo).
Le streaming est bloqué par défaut.

Contrôle d’accès (DM)

channels.zalouser.dmPolicy prend en charge : pairing | allowlist | open | disabled (par défaut : pairing).

channels.zalouser.allowFrom doit utiliser des ID utilisateur Zalo stables. Il peut aussi référencer des groupes d’accès d’expéditeurs statiques (accessGroup:<name>). Pendant la configuration interactive, les noms saisis peuvent être résolus en ID à l’aide de la recherche de contacts en cours de processus du Plugin.

Si un nom brut reste dans la configuration, le démarrage ne le résout que lorsque channels.zalouser.dangerouslyAllowNameMatching: true est activé. Sans cette option explicite, les vérifications d’expéditeur à l’exécution se font uniquement par ID et les noms bruts sont ignorés pour l’autorisation.

Approuvez via :

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

Accès aux groupes (facultatif)

Par défaut : channels.zalouser.groupPolicy = "open" (groupes autorisés). Utilisez channels.defaults.groupPolicy pour remplacer la valeur par défaut lorsqu’elle n’est pas définie.
Restreindre à une liste d’autorisation avec :
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (les clés doivent être des ID de groupe stables ; les noms sont résolus en ID au démarrage uniquement lorsque channels.zalouser.dangerouslyAllowNameMatching: true est activé)
- channels.zalouser.groupAllowFrom (contrôle quels expéditeurs dans les groupes autorisés peuvent déclencher le bot ; les groupes d’accès d’expéditeurs statiques peuvent être référencés avec accessGroup:<name>)
Bloquer tous les groupes : channels.zalouser.groupPolicy = "disabled".
L’assistant de configuration peut demander des listes d’autorisation de groupes.
Au démarrage, OpenClaw résout les noms de groupes/utilisateurs dans les listes d’autorisation en ID et journalise la correspondance uniquement lorsque channels.zalouser.dangerouslyAllowNameMatching: true est activé.
La correspondance de liste d’autorisation de groupes se fait uniquement par ID par défaut. Les noms non résolus sont ignorés pour l’authentification, sauf si channels.zalouser.dangerouslyAllowNameMatching: true est activé.
channels.zalouser.dangerouslyAllowNameMatching: true est un mode de compatibilité de dernier recours qui réactive la résolution de noms mutable au démarrage et la correspondance des noms de groupe à l’exécution.
Si groupAllowFrom n’est pas défini, l’exécution se rabat sur allowFrom pour les vérifications des expéditeurs de groupe.
Les vérifications d’expéditeur s’appliquent à la fois aux messages de groupe normaux et aux commandes de contrôle (par exemple /new, /reset).

Exemple :

json5

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

Garde par mention dans les groupes

channels.zalouser.groups.<group>.requireMention contrôle si les réponses de groupe nécessitent une mention.
Ordre de résolution : id/nom de groupe exact -> slug de groupe normalisé -> * -> valeur par défaut (true).
Cela s’applique à la fois aux groupes sur liste d’autorisation et au mode groupe ouvert.
Citer un message du bot compte comme une mention implicite pour l’activation de groupe.
Les commandes de contrôle autorisées (par exemple /new) peuvent contourner la garde par mention.
Lorsqu’un message de groupe est ignoré parce qu’une mention est requise, OpenClaw l’enregistre comme historique de groupe en attente et l’inclut dans le prochain message de groupe traité.
La limite d’historique de groupe utilise par défaut messages.groupChat.historyLimit (repli 50). Vous pouvez la remplacer par compte avec channels.zalouser.historyLimit.

Exemple :

json5

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

Multi-compte

Les comptes correspondent aux profils zalouser dans l’état d’OpenClaw. Exemple :

json5

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

Saisie, réactions et accusés de livraison

OpenClaw envoie un événement de saisie avant d’envoyer une réponse (au mieux).
L’action de réaction de message react est prise en charge pour zalouser dans les actions de canal.
- Utilisez remove: true pour retirer un emoji de réaction spécifique d’un message.
- Sémantique des réactions : Réactions
Pour les messages entrants qui incluent des métadonnées d’événement, OpenClaw envoie des accusés de livraison + de lecture (au mieux).

Dépannage

La connexion ne persiste pas :

openclaw channels status --probe
Reconnexion : openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Le nom de liste d’autorisation/groupe n’a pas été résolu :

Utilisez des ID numériques dans allowFrom/groupAllowFrom et des ID de groupe stables dans groups. Si vous avez intentionnellement besoin de noms exacts d’amis/groupes, activez channels.zalouser.dangerouslyAllowNameMatching: true.

Mise à niveau depuis l’ancienne configuration basée sur la CLI :

Supprimez toute ancienne hypothèse liée à un processus zca externe.
Le canal s’exécute désormais entièrement dans OpenClaw sans binaires CLI externes.

Associé

Vue d’ensemble des canaux — tous les canaux pris en charge
Jumelage — authentification DM et flux de jumelage
Groupes — comportement des discussions de groupe et garde par mention
Routage de canal — routage de session pour les messages
Sécurité — modèle d’accès et renforcement

Was this useful?