Communitygithub.com

lroolle/wxclawbot-cli

Weixin ClawBot CLI - messagerie proactive pour les agents OpenClaw

Qu'est-ce que wxclawbot-cli ?

Ce skill permet aux agents OpenClaw d'envoyer activement des messages aux utilisateurs de WeChat, y compris du texte, des images, des vidéos et des fichiers. Contrairement à un robot WeChat standard qui ne fait que répondre passivement, ce skill offre une capacité de communication proactive, essentielle pour des scénarios comme les rappels planifiés, les alertes push ou l'envoi de rapports. Il fonctionne via l'outil en ligne de commande `wxclawbot` et s'intègre avec le système openclaw-weixin pour la gestion des identifiants et des tokens de contexte nécessaires à l'envoi push. Les agents peuvent l'utiliser dans des tâches automatisées (cron) et les appels programmatiques doivent impérativement utiliser le flag `--json` pour un traitement correct des résultats. Le skill prend en charge la détection de compte, la gestion des limites de débit (`ret=-2`) et le routage des erreurs structurées (timeout, DNS, etc.) pour une fiabilité accrue.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add lroolle/wxclawbot-cli

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

wxclawbot-send

Ce que ce skill résout

Le robot WeChat (iLink Bot) ne peut que répondre passivement aux messages des utilisateurs, sans pouvoir initier de conversation. Cela empêche les agents de prendre en charge des scénarios de contact proactif comme les rappels planifiés, les notifications d'alarme ou l'envoi de rapports.

Ce skill permet à l'agent d'envoyer activement des messages aux utilisateurs WeChat via la CLI wxclawbot : texte, image, vidéo, fichier. Combiné avec cron, il permet de réaliser des tâches planifiées.

Prérequis

  • Node.js >= 20
  • npm install -g @claw-lab/wxclawbot-cli
  • openclaw-weixin doit être connecté (les identifiants se trouvent dans ~/.openclaw/openclaw-weixin/accounts/)

Vérification : wxclawbot accounts --json

Démarrage rapide

wxclawbot send --text "Contenu du message" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "Veuillez consulter" --json

Quand utiliser quoi

Envoi de message texte        → wxclawbot send --text "msg" --json
Envoi de fichier/image        → wxclawbot send --file ./chemin --json
Vérification de l'état du compte → wxclawbot accounts --json
Appel programmatique          → voir references/programmatic-api.md

Référence des commandes

send

wxclawbot send --text "message" --json
wxclawbot send --to "[email protected]" --text "Bonjour" --json
wxclawbot send --file ./photo.jpg --json
wxclawbot send --file ./report.pdf --text "Veuillez consulter" --json
wxclawbot send --file "https://example.com/img.png" --json
echo "Rapport quotidien généré" | wxclawbot send --json
wxclawbot send --text "test" --dry-run
ParamètreDescription
--text <msg>Texte du message. "-" pour lire explicitement stdin
--file <chemin>Fichier local ou URL (image / vidéo / fichier)
--to <userId>ID de l'utilisateur cible. Par défaut : utilisateur lié au compte
--account <id>Compte spécifique. Par défaut : premier disponible
--jsonSortie au format JSON. Obligatoire pour les appels programmatiques
--dry-runAperçu, n'envoie pas

Les types de médias sont reconnus automatiquement par l'extension :

  • Image : .png .jpg .jpeg .gif .webp .bmp
  • Vidéo : .mp4 .mov .webm .mkv .avi
  • Fichier : tous les autres

accounts

wxclawbot accounts --json

Retourne : [{"id":"<botId>-im-bot","configured":true,"baseUrl":"..."}]

Mécanisme de découverte des comptes

La CLI découvre automatiquement les comptes depuis ~/.openclaw/openclaw-weixin/accounts/*.json. Chaque fichier contient token, baseUrl, userId (cible --to par défaut).

  • L'ID du bot est extrait du token à l'exécution (pas codé en dur)
  • L'ID du compte peut changer après une mise à niveau ou une réinscription d'openclaw-weixin
  • --to utilise par défaut userId du fichier de compte (utilisateur lié)
  • La variable d'environnement WXCLAW_TOKEN remplace la découverte par fichier

Context Token (clé de l'envoi push)

WeChat nécessite un context_token pour envoyer des messages de manière proactive. Sans lui, les messages restent sur le serveur jusqu'à ce que l'utilisateur ouvre activement la fenêtre de discussion – ce qui n'est plus un "envoi push".

La CLI lit automatiquement {accountId}.context-tokens.json (dans le même répertoire que les fichiers de compte). Ce fichier est maintenu par openclaw-weixin et contient une correspondance userId → contextToken. Aucune configuration manuelle n'est nécessaire – openclaw-weixin sauvegarde automatiquement après que l'utilisateur a envoyé un message au robot.

Si le context_token est manquant (nouvel utilisateur, token expiré), le message sera quand même envoyé avec succès (ok:true), mais la notification push ne sera pas active.

Après une mise à niveau d'openclaw-weixin, vérifiez toujours avec wxclawbot accounts --json.

Intégration avec l'agent

Les appels programmatiques doivent utiliser --json. Analysez le JSON pour déterminer le succès.

resultat=$(wxclawbot send --text "Tâche terminée" --json)
resultat=$(wxclawbot send --file ./chart.png --text "Indicateurs quotidiens" --json)
  • Succès : {"ok":true,"to":"[email protected]","clientId":"..."}
  • Échec : {"ok":false,"error":"..."}
  • Code de retour : 0 = exécution CLI réussie, 1 = échec

Remarque : le code 0 indique seulement que la CLI s'est exécutée, pas que le message a été livré. Regardez le champ ok.

Gestion des erreurs

ErreurSignificationAction
ret=-2Limite de fréquence (environ 7 messages / 5 min par bot, partagé entre tous les clients)Attendre 60-120 secondes avant de réessayer, pas de boucle serrée
ret=-14Session expiréeReconnectez-vous via openclaw
No account foundIdentifiants manquantsExécutez wxclawbot accounts pour diagnostiquer
CDN upload errorÉchec du téléchargement du fichierVérifiez la taille / le format du fichier, réessayez
Request timeoutProblème réseau (timeout de 15 secondes)Réessayez

La limite de fréquence est côté serveur, tous les clients partagent le même quota sous le même token de bot.

Erreurs de transmission structurées (v0.5.1+)

En mode --json, les échecs de couche de transmission incluent des champs supplémentaires :

{"ok":false,"error":"send failed: ...","errorKind":"timeout","retryable":true}
errorKindSignificationretryable
timeoutDélai d'attente dépassé (15 s)true
dnsÉchec de résolution DNStrue
connectionConnexion réinitialisée / socket hang uptrue
networkConnexion refusée / hôte inaccessible / fetch failedtrue
tlsErreur de certificat ou TLSfalse
unknownErreur non classifiéefalse

Utilisez le champ retryable pour décider s'il faut réessayer ou abandonner.

Pièges courants

  • Utilisez impérativement --json – sans cela, la sortie est en format lisible par l'humain et ne peut pas être analysée.
  • Regardez le champ ok – un code 0 indique seulement l'exécution de la CLI, pas la livraison du message.
  • N'effectuez pas de boucle serrée sur ret=-2 – attendez au moins 5 à 10 secondes.
  • Texte long via stdin – utilisez echo "..." | wxclawbot send --json pour éviter les problèmes de guillemets du shell.
  • Le fichier est chiffré et téléchargé vers le CDN de WeChat – les gros fichiers peuvent prendre un moment.

Variables d'environnement

VariableUsage
WXCLAW_TOKENRemplace le token du bot ([email protected]:your-token)
WXCLAW_BASE_URLRemplace le point d'accès API (par défaut : https://ilinkai.weixin.qq.com)

L'interface programmatique est détaillée dans references/programmatic-api.md.

Skills associés