Zalo Personal (non officiel)

Statut : experimental. Cette integration automatise un compte Zalo personnel via zca-js natif dans OpenClaw.

Avertissement : Il s’agit d’une integration non officielle qui peut entrainer la suspension/le bannissement du compte. Utilisez a vos propres risques.

Plugin requis

Zalo Personal est fourni comme plugin et n’est pas inclus dans l’installation de base.

Installation via CLI : openclaw plugins install @openclaw/zalouser
Ou depuis un checkout source : openclaw plugins install ./extensions/zalouser
Details : Plugins

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

Configuration rapide (debutant)

Installez le plugin (voir ci-dessus).
Connexion (QR, sur la machine de la Gateway) :
- openclaw channels login --channel zalouser
- Scannez le code QR avec l’application mobile Zalo.
Activez le canal :

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

Redemarrez la Gateway (ou terminez l’onboarding).
L’acces DM est par defaut en mode appairage ; approuvez le code d’appairage au premier contact.

Description

Fonctionne entierement en processus via zca-js.
Utilise des ecouteurs d’evenements natifs pour recevoir les messages entrants.
Envoie les reponses directement via l’API JS (texte/media/lien).
Concu pour les cas d’utilisation de « compte personnel » ou l’API Bot Zalo n’est pas disponible.

Nommage

L’ID de canal est zalouser pour indiquer explicitement que ceci automatise un compte utilisateur Zalo personnel (non officiel). Nous reservons zalo pour une potentielle future integration API Zalo officielle.

Trouver les IDs (annuaire)

Utilisez le CLI annuaire pour decouvrir les pairs/groupes et leurs IDs :

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

Limites

Le texte sortant est decoupe a ~2000 caracteres (limites du client Zalo).
Le streaming est bloque par defaut.

Controle d’acces (DMs)

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

channels.zalouser.allowFrom accepte les IDs utilisateur ou les noms. Pendant l’onboarding, les noms sont resolus en IDs en utilisant la recherche de contacts en processus du plugin.

Approbation via :

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

Acces aux groupes (optionnel)

Par defaut : channels.zalouser.groupPolicy = "open" (groupes autorises). Utilisez channels.defaults.groupPolicy pour surcharger la valeur par defaut quand non defini.
Restreignez a une liste d’autorisation avec :
- channels.zalouser.groupPolicy = "allowlist"
- channels.zalouser.groups (les cles doivent etre des IDs de groupe stables ; les noms sont resolus en IDs au demarrage quand c’est possible)
- channels.zalouser.groupAllowFrom (controle quels expediteurs dans les groupes autorises peuvent declencher le bot)
Bloquer tous les groupes : channels.zalouser.groupPolicy = "disabled".
L’assistant de configuration peut demander des listes d’autorisation de groupe.
Au demarrage, OpenClaw resout les noms de groupe/utilisateur dans les listes d’autorisation en IDs et enregistre la correspondance.
La correspondance de liste d’autorisation de groupe est par defaut sur ID uniquement. Les noms non resolus sont ignores pour l’authentification sauf si channels.zalouser.dangerouslyAllowNameMatching: true est active.
channels.zalouser.dangerouslyAllowNameMatching: true est un mode de compatibilite d’urgence qui reactive la correspondance par nom de groupe mutable.
Si groupAllowFrom n’est pas defini, l’execution se replie sur allowFrom pour les verifications d’expediteur de groupe.
Les verifications d’expediteur s’appliquent aux messages de groupe normaux et aux commandes de controle (par exemple /new, /reset).

Exemple :

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

Filtrage par mention dans les groupes

channels.zalouser.groups.<group>.requireMention controle si les reponses de groupe necessitent une mention.
Ordre de resolution : ID de groupe exact -> slug de groupe normalise -> * -> defaut (true).
Cela s’applique aux groupes autorises et au mode groupe ouvert.
Les commandes de controle autorisees (par exemple /new) peuvent contourner le filtrage par mention.
Quand un message de groupe est ignore parce qu’une mention est requise, OpenClaw le stocke comme historique de groupe en attente et l’inclut au prochain message de groupe traite.
La limite d’historique de groupe est par defaut messages.groupChat.historyLimit (repli 50). Vous pouvez la surcharger par compte avec channels.zalouser.historyLimit.

Exemple :

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

Multi-comptes

Les comptes correspondent a des profils zalouser dans l’etat OpenClaw. Exemple :

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

Saisie, reactions et accuses de reception

OpenClaw envoie un evenement de saisie avant d’envoyer une reponse (meilleur effort).
L’action de reaction de message react est prise en charge pour zalouser dans les actions de canal.
- Utilisez remove: true pour retirer un emoji de reaction specifique d’un message.
- Semantique des reactions : Reactions
Pour les messages entrants qui incluent des metadonnees d’evenement, OpenClaw envoie des accuses de reception de livraison + lecture (meilleur effort).

Depannage

La connexion ne persiste pas :

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

Le nom dans la liste d’autorisation/groupe n’a pas ete resolu :

Utilisez des IDs numeriques dans allowFrom/groupAllowFrom/groups, ou des noms exacts d’amis/groupes.

Mise a jour depuis une ancienne configuration basee sur CLI :

Supprimez toute hypothese d’ancien processus zca externe.
Le canal fonctionne maintenant entierement dans OpenClaw sans binaires CLI externes.