Zalo personnel

​

Installation

openclaw plugins install @openclaw/zalouser

• Épingler une version : openclaw plugins install @openclaw/zalouser@<version>
• Depuis un dépôt source extrait : openclaw plugins install ./path/to/local/zalouser-plugin
• Détails : Plugins

​

Configuration rapide

1. Installez le plugin (ci-dessus).
2. Connectez-vous (par QR, sur la machine du Gateway) :
   • openclaw channels login --channel zalouser
   • Scannez le code QR avec l’application mobile Zalo.
3. Activez le canal :

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

4. Redémarrez le Gateway (ou terminez la configuration).
5. L’accès aux messages privés utilise l’association par défaut ; approuvez le code d’association lors du premier contact.

​

Présentation

• Fonctionne entièrement au sein du processus via la bibliothèque zca-js (sans binaire externe zca/openzca).
• Utilise les écouteurs d’événements natifs (message, error) pour recevoir les messages entrants.
• Envoie les réponses directement au moyen de l’API JS (texte, média ou lien).
• Conçu pour les cas d’utilisation d’un « compte personnel » où l’API Zalo Bot n’est pas disponible.

​

Nommage

​

Recherche des identifiants (annuaire)

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 découpé en segments de 2 000 caractères (limite du client Zalo).
• La diffusion en continu n’est pas prise en charge.

​

Contrôle d’accès (messages privés)

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

​

Accès aux groupes (facultatif)

• Valeur par défaut : channels.zalouser.groupPolicy = "allowlist" (les groupes nécessitent une entrée explicite dans la liste d’autorisation).
• Ouvrir tous les groupes : channels.zalouser.groupPolicy = "open".
• Bloquer tous les groupes : channels.zalouser.groupPolicy = "disabled".
• Avec groupPolicy = "allowlist" :
  • Les clés de channels.zalouser.groups doivent être des identifiants de groupe stables ; les noms ne sont résolus en identifiants au démarrage que lorsque channels.zalouser.dangerouslyAllowNameMatching: true est activé.
  • channels.zalouser.groupAllowFrom détermine quels expéditeurs des groupes autorisés peuvent déclencher le bot ; les groupes statiques d’accès des expéditeurs peuvent être référencés avec accessGroup:<name>.
• L’assistant de configuration peut demander les listes d’autorisation des groupes.
• Par défaut, la correspondance avec la liste d’autorisation des groupes repose uniquement sur les identifiants. 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é d’urgence qui réactive la résolution au démarrage des noms modifiables et la correspondance des noms de groupe à l’exécution.
• Pour les messages de groupe ordinaires, groupAllowFrom ne se rabat pas sur allowFrom : si cette option reste vide pour un groupe figurant dans la liste d’autorisation, tout expéditeur peut interagir dans ce groupe. Les commandes de contrôle autorisées (par exemple /new) constituent l’exception ; lorsque groupAllowFrom est vide, la vérification de leur expéditeur se rabat sur allowFrom.

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

​

Filtrage des mentions dans les groupes

• channels.zalouser.groups.<group>.requireMention détermine si les réponses dans les groupes nécessitent une mention.
• Ordre de résolution : identifiant du groupe -> alias group:<id> -> nom/slug du groupe (les correspondances fondées sur le nom ne s’appliquent que lorsque dangerouslyAllowNameMatching: true) -> * -> valeur par défaut (true).
• S’applique aussi bien aux groupes figurant dans la liste d’autorisation qu’au mode de groupes ouverts.
• Citer un message du bot compte comme une mention implicite pour l’activation dans un groupe.
• Les commandes de contrôle autorisées (par exemple /new) peuvent contourner le filtrage des mentions.
• Lorsqu’un message de groupe est ignoré parce qu’une mention est requise, OpenClaw le conserve dans l’historique de groupe en attente et l’inclut dans le prochain message de groupe traité.
• Limite de l’historique des groupes : channels.zalouser.historyLimit, puis messages.groupChat.historyLimit, puis une valeur de repli de 50.

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

​

Comptes multiples

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

​

Variables d’environnement

1. profile explicite dans la configuration.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. L’identifiant du compte pour les comptes autres que celui par défaut, ou default pour le compte par défaut.

​

Saisie, réactions et accusés de réception

• OpenClaw envoie un événement de saisie avant d’envoyer une réponse (dans la mesure du possible).
• L’action de réaction aux messages react est prise en charge pour zalouser dans les actions de canal.
  • Utilisez remove: true pour supprimer d’un message un émoji de réaction précis.
  • Sémantique des réactions : Réactions
• Pour les messages entrants comportant des métadonnées d’événement, OpenClaw envoie des accusés de livraison et de lecture (dans la mesure du possible).

​

Dépannage

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

• Utilisez des identifiants numériques dans allowFrom/groupAllowFrom et des identifiants de groupe stables dans groups. Si vous devez intentionnellement utiliser les noms exacts d’amis ou de groupes, activez channels.zalouser.dangerouslyAllowNameMatching: true.

• Supprimez toute dépendance supposée à un processus zca externe ; le canal fonctionne désormais entièrement au sein du processus via zca-js, sans binaire CLI externe.

​

Pages connexes

• Vue d’ensemble des canaux - tous les canaux pris en charge
• Association - authentification des messages privés et processus d’association
• Groupes - comportement des discussions de groupe et filtrage des mentions
• Routage des canaux - routage des sessions pour les messages
• Sécurité - modèle d’accès et durcissement