Passer au contenu principal

​
WhatsApp (canal Web)

Statut : prêt pour la production via WhatsApp Web (Baileys). La Gateway possède la ou les sessions liées.

​
Installation (à la demande)

  • L’onboarding (openclaw onboard) et openclaw channels add --channel whatsapp proposent d’installer le plugin WhatsApp la première fois que vous le sélectionnez.
  • openclaw channels login --channel whatsapp propose également le flux d’installation lorsque le plugin n’est pas encore présent.
  • Canal de dev + extraction git : utilise par défaut le chemin du plugin local.
  • Stable/Beta : utilise par défaut le package npm @openclaw/whatsapp.
L’installation manuelle reste disponible : 
openclaw plugins install @openclaw/whatsapp

Appairage

La politique DM par défaut est l’appairage pour les expéditeurs inconnus.

Dépannage du canal

Diagnostics inter-canaux et guides de réparation.

Configuration de la Gateway

Modèles et exemples complets de configuration de canal.

​
Configuration rapide

1

Configurer la politique d’accès WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
2

Lier WhatsApp (QR)

openclaw channels login --channel whatsapp
Pour un compte spécifique :
openclaw channels login --channel whatsapp --account work
3

Démarrer la Gateway

openclaw gateway
4

Approuver la première demande d’appairage (si vous utilisez le mode appairage)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
Les demandes d’appairage expirent après 1 heure. Les demandes en attente sont limitées à 3 par canal.
OpenClaw recommande d’exécuter WhatsApp sur un numéro distinct lorsque c’est possible. (Les métadonnées du canal et le flux de configuration sont optimisés pour cette configuration, mais les configurations avec numéro personnel sont également prises en charge.)

​
Modèles de déploiement

Il s’agit du mode opérationnel le plus propre :
  • identité WhatsApp distincte pour OpenClaw
  • limites de routage et listes d’autorisation DM plus claires
  • risque plus faible de confusion avec l’auto-discussion
Modèle de politique minimale :
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
L’onboarding prend en charge le mode numéro personnel et écrit une base adaptée à l’auto-discussion :
  • dmPolicy: "allowlist"
  • allowFrom inclut votre numéro personnel
  • selfChatMode: true
À l’exécution, les protections d’auto-discussion dépendent du numéro lié à soi-même et de allowFrom.
Le canal de plateforme de messagerie est basé sur WhatsApp Web (Baileys) dans l’architecture actuelle des canaux OpenClaw.Il n’existe pas de canal de messagerie WhatsApp Twilio distinct dans le registre intégré des canaux de chat.

​
Modèle d’exécution

  • La Gateway possède le socket WhatsApp et la boucle de reconnexion.
  • Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible.
  • Les discussions de statut et de diffusion sont ignorées (@status, @broadcast).
  • Les discussions directes utilisent les règles de session DM (session.dmScope ; par défaut main regroupe les DM dans la session principale de l’agent).
  • Les sessions de groupe sont isolées (agent:<agentId>:whatsapp:group:<jid>).

​
Contrôle d’accès et activation

channels.whatsapp.dmPolicy contrôle l’accès aux discussions directes :
  • pairing (par défaut)
  • allowlist
  • open (nécessite que allowFrom inclue "*")
  • disabled
allowFrom accepte des numéros au format E.164 (normalisés en interne).Remplacement multi-comptes : channels.whatsapp.accounts.<id>.dmPolicy (et allowFrom) ont priorité sur les valeurs par défaut au niveau du canal pour ce compte.Détails du comportement à l’exécution :
  • les appairages sont persistés dans le magasin d’autorisations du canal et fusionnés avec allowFrom configuré
  • si aucune liste d’autorisation n’est configurée, le numéro lié à soi-même est autorisé par défaut
  • les DM sortants fromMe ne sont jamais appairés automatiquement

​
Comportement avec numéro personnel et auto-discussion

Lorsque le numéro lié à soi-même est également présent dans allowFrom, les protections d’auto-discussion WhatsApp s’activent :
  • ignorer les accusés de lecture pour les tours d’auto-discussion
  • ignorer le comportement de déclenchement automatique par mention-JID qui vous notifierait autrement vous-même
  • si messages.responsePrefix n’est pas défini, les réponses d’auto-discussion utilisent par défaut [{identity.name}] ou [openclaw]

​
Normalisation des messages et contexte

Les messages WhatsApp entrants sont encapsulés dans l’enveloppe entrante partagée.Si une réponse citée existe, le contexte est ajouté sous cette forme :
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
Les champs de métadonnées de réponse sont également renseignés lorsqu’ils sont disponibles (ReplyToId, ReplyToBody, ReplyToSender, expéditeur JID/E.164).
Les messages entrants composés uniquement de média sont normalisés avec des espaces réservés tels que :
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
Les charges utiles de lieu et de contact sont normalisées en contexte textuel avant le routage.
Pour les groupes, les messages non traités peuvent être mis en mémoire tampon et injectés comme contexte lorsque le bot est finalement déclenché.
  • limite par défaut : 50
  • configuration : channels.whatsapp.historyLimit
  • solution de repli : messages.groupChat.historyLimit
  • 0 désactive
Marqueurs d’injection :
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
Les accusés de lecture sont activés par défaut pour les messages WhatsApp entrants acceptés.Désactivation globale :
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
Remplacement par compte :
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
Les tours d’auto-discussion ignorent les accusés de lecture même lorsqu’ils sont activés globalement.

​
Livraison, segmentation et médias

  • limite de segment par défaut : channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • le mode newline privilégie les limites de paragraphe (lignes vides), puis revient à une segmentation sûre par longueur
  • prend en charge les charges utiles image, vidéo, audio (note vocale PTT) et document
  • audio/ogg est réécrit en audio/ogg; codecs=opus pour la compatibilité des notes vocales
  • la lecture GIF animée est prise en charge via gifPlayback: true lors des envois vidéo
  • les légendes sont appliquées au premier élément média lors de l’envoi de charges utiles de réponse multimédia
  • la source média peut être HTTP(S), file:// ou des chemins locaux
  • limite de sauvegarde des médias entrants : channels.whatsapp.mediaMaxMb (par défaut 50)
  • limite d’envoi des médias sortants : channels.whatsapp.mediaMaxMb (par défaut 50)
  • les remplacements par compte utilisent channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • les images sont automatiquement optimisées (redimensionnement/balayage qualité) pour respecter les limites
  • en cas d’échec d’envoi média, le repli du premier élément envoie un avertissement texte au lieu d’ignorer silencieusement la réponse

​
Niveau de réaction

channels.whatsapp.reactionLevel contrôle l’ampleur de l’utilisation des réactions emoji par l’agent sur WhatsApp :
NiveauRéactions d’accuséRéactions initiées par l’agentDescription
"off"NonNonAucune réaction
"ack"OuiNonRéactions d’accusé uniquement (accusé pré-réponse)
"minimal"OuiOui (conservateur)Accusé + réactions agent avec recommandations conservatrices
"extensive"OuiOui (encouragé)Accusé + réactions agent avec recommandations encouragées
Par défaut : "minimal". Les remplacements par compte utilisent channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
Réactions d’accusé de réception

WhatsApp prend en charge les réactions d’accusé immédiates à la réception entrante via channels.whatsapp.ackReaction. Les réactions d’accusé sont contrôlées par reactionLevel — elles sont supprimées lorsque reactionLevel vaut "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
Remarques sur le comportement :
  • envoyées immédiatement après l’acceptation de l’entrée (avant réponse)
  • les échecs sont journalisés mais ne bloquent pas la livraison normale de la réponse
  • le mode de groupe mentions réagit lors des tours déclenchés par mention ; l’activation de groupe always agit comme contournement de cette vérification
  • WhatsApp utilise channels.whatsapp.ackReaction (l’ancien messages.ackReaction n’est pas utilisé ici)

​
Multi-comptes et identifiants

  • les ID de compte proviennent de channels.whatsapp.accounts
  • sélection du compte par défaut : default s’il est présent, sinon le premier ID de compte configuré (trié)
  • les ID de compte sont normalisés en interne pour la recherche
  • chemin d’authentification actuel : ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • fichier de sauvegarde : creds.json.bak
  • l’ancienne authentification par défaut dans ~/.openclaw/credentials/ est toujours reconnue/migrée pour les flux de compte par défaut
openclaw channels logout --channel whatsapp [--account <id>] efface l’état d’authentification WhatsApp pour ce compte.Dans les anciens répertoires d’authentification, oauth.json est conservé tandis que les fichiers d’authentification Baileys sont supprimés.

​
Outils, actions et écritures de configuration

  • La prise en charge des outils d’agent inclut l’action de réaction WhatsApp (react).
  • Barrières d’action :
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • Les écritures de configuration initiées depuis le canal sont activées par défaut (désactivation via channels.whatsapp.configWrites=false).

​
Dépannage

Symptôme : le statut du canal indique qu’il n’est pas lié.Correctif :
openclaw channels login --channel whatsapp
openclaw channels status
Symptôme : compte lié avec déconnexions répétées ou tentatives de reconnexion.Correctif :
openclaw doctor
openclaw logs --follow
Si nécessaire, reliez avec channels login.
Les envois sortants échouent rapidement lorsqu’aucun écouteur Gateway actif n’existe pour le compte cible.Assurez-vous que la Gateway est en cours d’exécution et que le compte est lié.
Vérifiez dans cet ordre :
  • groupPolicy
  • groupAllowFrom / allowFrom
  • entrées de liste d’autorisation groups
  • filtrage par mention (requireMention + motifs de mention)
  • clés dupliquées dans openclaw.json (JSON5) : les entrées ultérieures remplacent les précédentes, donc gardez un seul groupPolicy par portée
L’exécution Gateway WhatsApp doit utiliser Node. Bun est signalé comme incompatible avec un fonctionnement stable de la Gateway WhatsApp/Telegram.

​
Pointeurs de référence de configuration

Référence principale : Champs WhatsApp à fort signal :
  • accès : dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
  • livraison : textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
  • multi-comptes : accounts.<id>.enabled, accounts.<id>.authDir, remplacements au niveau du compte
  • opérations : configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*
  • comportement de session : session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit

​
Lié