2026 WeChat ClawBot officiel pour OpenClaw : installation, pièges et matrice de décision

En mai 2026, Tencent a publié le plugin WeChat officiel ClawBot pour OpenClaw. Les développeurs peuvent ainsi relier leur messagerie personnelle WeChat à une passerelle OpenClaw locale ou hébergée, sans passer par des ponts Wechaty non officiels. Ce guide couvre la diagnostic en quatre couches, l’installation en une commande npx, les seuils de version et les pièges de production — avec une matrice de décision pour choisir entre compte principal, compte secondaire et hébergement Mac distant 24 h/24.

1. Diagnostic en quatre couches avant d’installer

La plupart des tickets support ClawBot proviennent d’une mauvaise couche de diagnostic. Traitez chaque symptôme indépendamment :

1. N0 — Entrée plugin absente : Réglages WeChat → Extensions sans OpenClaw. Causes : client < 8.0.70, déploiement progressif non activé sur votre compte, ou région hors liste. Mettez à jour l’app mobile ; n’attendez pas WeChat PC (non pris en charge pour ClawBot).
2. N1 — Échec du scan QR : La passerelle tourne mais l’appairage expire. Vérifiez l’horloge NTP, la connectivité entrante vers l’hôte (IP publique ou mesh Tailscale), et les règles pare-feu sur le port du canal.
3. N2 — Passerelle arrêtée : openclaw gateway status indique stopped. Exécutez openclaw gateway restart et consultez le guide redémarrage passerelle macOS (procédures équivalentes sur Mac distant).
4. N3 — Connecté sans réponse : Canal vert côté CLI, silence côté WeChat. Souvent OpenClaw < 2026.3.22 ou plugin 2.0.x non chargé. Lancez openclaw channels status --probe et le runbook pairing (contenu technique identique sur nœud Mac).

Conservez pour chaque couche une capture d’écran et un extrait de log (~/.openclaw/logs/). Cela accélère les revues de sécurité internes et les audits RGPD sur la traçabilité des traitements.

2. Qu’est-ce que le ClawBot officiel — et ce qu’il n’est pas

ClawBot désigne le plugin Tencent distribué via @tencent-weixin/openclaw-weixin-cli. Les messages transitent par l’infrastructure WeChat officielle ; les capacités d’action (fichiers, shell, recherche web) restent bornées par votre openclaw.json et la politique plugins.fs.

Face à Wechaty ou à l’émulation de protocole iPad, le risque de bannissement de compte personnel chute. Face à WeCom (WeChat Entreprise), ClawBot cible le chat personnel — pratique pour les makers, insuffisant seul pour la gouvernance SSO et les workflows RH formels.

Point RGPD : les métadonnées et contenus peuvent transiter par Tencent. N’acheminez pas de données sensibles Art. 9 via ce canal ; utilisez des comptes de test pseudonymisés pour le staging.

3. Prérequis : client WeChat, hôte OpenClaw, disponibilité

• WeChat mobile : iOS ≥ 8.0.70, Android ≥ 8.0.69 (8.0.70+ recommandé).
• OpenClaw : plugin 2.0.x exige hôte ≥ 2026.3.22 — validez avec openclaw doctor.
• Node.js v22+ selon le guide d’installation (référence technique DE, étapes identiques).
• Hôte toujours allumé : un portable en veille coupe les WebSockets ; la production exige launchd sur Mac dédié.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw channels status --probe

4. Cinq étapes : commande officielle, QR, redémarrage passerelle

1. Copier la commande depuis WeChat → Réglages → Extensions → ClawBot.
2. Exécuter sur l’hôte passerelle :

   npx -y @tencent-weixin/openclaw-weixin-cli@latest install

   Utilisez le même utilisateur OS que le service openclaw gateway.
3. Scanner le QR avec le téléphone du compte qui enverra les messages (compte secondaire conseillé en prod).
4. Redémarrer la passerelle (obligatoire) :

   openclaw gateway restart
   openclaw channels status --probe

5. Test de bout en bout : message #oc-test-20260522, latence < 5 s, logs openclaw logs --follow sans erreur channel.

Erreur fréquente : relancer npx install sans gateway restart, ce qui laisse le canal en état « enregistré mais inactif ».

5. Matrice des pièges et décisions de production

Limitez la rétention des journaux contenant du contenu de chat. Synchronisez le workspace par rsync/SFTP vers des chemins isolés — jamais vers des buckets publics de artefacts CI.

6. Multi-comptes : dmScope et routage d’agents

{
  "session": {
    "dmScope": "per-account-channel-peer"
  },
  "agents": {
    "routing": {
      "default": "main",
      "rules": [
        { "channel": "weixin", "peer": "*", "agent": "main" }
      ]
    }
  }
}

Deux numéros WeChat sur une même passerelle exigent des agents séparés et des allowedPaths disjoints. Sinon, un DM du compte A peut déclencher des opérations fichier pour le workspace du compte B — violation de séparation des contextes.

Architecture stricte : une passerelle par numéro, chacune sur un Mac distant dédié — coût plus élevé, isolation incident maximale.

7. Pourquoi héberger la passerelle sur un Mac distant

ClawBot n’est fiable que si le processus gateway survive aux nuits et aux mises à jour OS. Un VPS Linux générique complique la chaîne rsync/APFS pour les builds iOS ; un portable coupe les WebSockets.

SFTPMAC fournit un nœud macOS avec Apple Silicon, service launchd pour openclaw gateway, et SFTP/rsync pour pousser config + skills depuis votre CI. Après chaque mise à jour plugin : rsync → gateway restart → channels --probe.

Cadence ops : openclaw doctor hebdomadaire ; @latest npx uniquement en staging ; revue trimestrielle des politiques Tencent sur les bots.

7a. Configuration canal et validation openclaw.json

Après npx install, le canal WeChat doit apparaître dans la configuration centrale. Vérifiez le bloc sous channels.weixin ; les clés exactes peuvent varier légèrement selon la version CLI — fiez-vous à openclaw doctor et à channels status.

{
  "channels": {
    "weixin": {
      "enabled": true,
      "mode": "clawbot",
      "pairing": { "status": "paired" }
    }
  },
  "gateway": {
    "listen": "127.0.0.1:18789",
    "auth": { "mode": "short_lived", "token_ttl": 3600 }
  }
}

En production, n’exposez pas le listener sur 0.0.0.0 sans reverse proxy TLS et allowedOrigins. Sur Mac distant : loopback + Tailscale ou tunnel SSH. Après toute édition JSON : openclaw gateway restart puis openclaw channels status --probe jusqu’à statut ok.

Checklist d’acceptation : menu plugin visible, QR réussi une fois, DM test avec préfixe unique, logs sans spawn_failed, doctor vert sur credentials, chemins workspace alignés avec rsync CI, sauvegarde ~/.openclaw planifiée.

7b. Tableau comparatif ClawBot, Wechaty, WeCom

7c. Exploitation : monitoring, rotation, CI

La mise en prod ClawBot exige des SLI : latence P95 des réponses, taux d’échec de channels --probe, RAM du processus gateway, sous-agents ZOMBIE. Alertez si le gateway reste en updating plus de 60 secondes — schéma connu sur d’autres montées de version OpenClaw.

Rotation des credentials : ré-appairage trimestriel sur numéro secondaire ; sauvegarde chiffrée de ~/.openclaw/credentials/ avant rotation ; destruction des anciennes clés (droit à l’effacement). Déploiements workspace : rsync vers staging avec tests, bascule atomique en prod.

Pipeline CI : build skills → rsync Mac distant → SSH gateway restart → channels --probe. La session WeChat reste sur le gateway actif pendant que la config est versionnée — fini les déploiements depuis le portable du développeur.

RGPD : registre des traitements « assistant IA via WeChat », durée de conservation des logs 30–90 jours avec purge auto, chiffrement APFS, SSH par clé matérielle. Interdisez les numéros WeChat personnels des employés — téléphone dédié ou SIM test uniquement.

Performance : évitez les pavés de code dans le chat ; stockez les artefacts dans le workspace synchronisé par SFTP/rsync. Cela réduit les filtres Tencent et la facture API des modèles.

Reprise après sinistre : second Mac distant avec même version OpenClaw. Procédure : restaurer ~/.openclaw, gateway install --force, restart, QR staging si révocation canal, bascule firewall. Documentez RTO/RPO — souvent RPO 24 h avec backup quotidien de config.

Scénario fréquent en équipe distribuée : un développeur en France et un opérateur en Chine. Le créneau horaire où le QR expire peut diverger — synchronisez NTP sur l’hôte gateway (Remote Mac en UTC ou timezone documentée) et planifiez le pairing dans une fenêtre où les deux parties sont en ligne. Si le scan échoue trois fois, effacez le demi-état dans credentials uniquement après arrêt gateway, puis relancez install + restart — jamais en boucle sur gateway actif.

Intégration multi-canal : beaucoup d’équipes gardent Telegram pour les alertes ops et WeChat pour les utilisateurs métier chinois. Séparez les agents (routing.rules) pour que une commande shell déclenchée depuis Telegram ne s’exécute pas sur le workspace lié à WeChat. Testez les deux probes après chaque upgrade OpenClaw — les régressions 4.x sur l’initialisation des channels sont documentées dans nos articles v2026.4.26 et gateway restart.

Conservez aussi la sortie de channels status --probe après chaque redémarrage — preuve que le canal WeChat est réellement à l’écoute, pas seulement « paired » côté mobile.

En audit interne, archivez la date du QR, la version openclaw-weixin-cli installée et le hash du fichier openclaw.json — trois champs suffisent pour reproduire un incident ClawBot en revue post-mortem sans exposer le contenu des conversations.

Stabilité transversale : les plugins OpenClaw partagent le processus gateway avec les sous-agents et les workers MCP stdio. Une mise à jour de skill défectueuse peut bloquer indirectement WeChat alors que ClawBot reste « paired ». Découplez les rollouts : canal staging avec numéro test, puis production. Mesurez la première réponse sous cinq minutes après chaque déploiement — un SLO simple qui révèle les régressions plus vite que des heures d’analyse de logs.

8. FAQ et articles connexes

Faut-il rescanner après chaque reboot ? Non, si ~/.openclaw/credentials/ est persistant et le canal n’a pas été révoqué côté WeChat.

ClawBot + Telegram en parallèle ? Oui — canaux distincts ; surveillez la RAM avec openclaw status après chaque ajout de plugin.

Version minimale 2026.3.22 suffit ? Pour le plugin 2.0.x oui ; pour failover multi-modèles et sub-agents, préférez v2026.5.x (guide v2026.5.19).

Runbook multi-canal : documentez qui rescane le QR de test, quels fournisseurs de modèles basculent en premier en cas de 429, et comment rsync pousse ~/.openclaw depuis CI sans écraser credentials/ — trois lignes dans Confluence évitent des heures de ping-pong entre équipe mobile, ops gateway et sécurité.

Conclusion : le ClawBot officiel remplace les ponts fragiles par un canal Tencent supporté, à condition de respecter les seuils de version, le redémarrage passerelle et un hôte 7×24. Pour une messagerie WeChat fiable en production, installez OpenClaw sur un Mac distant documenté — pas sur un portable qui s’endort à minuit.