WhatsApp

​

Installation

openclaw plugins install clawhub:@openclaw/whatsapp

​

Configuration rapide

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Modèles de déploiement

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

​

Modèle d’exécution

• Le Gateway gère le socket WhatsApp et la boucle de reconnexion.
• Un processus de surveillance suit indépendamment deux signaux : l’activité brute du transport WhatsApp Web et l’activité des messages applicatifs. Une session silencieuse mais connectée n’est pas redémarrée simplement parce qu’aucun message n’est arrivé récemment ; une reconnexion n’est forcée que lorsque les trames de transport cessent d’arriver pendant une fenêtre interne fixe (non configurable par l’utilisateur) ou lorsque les messages applicatifs restent silencieux au-delà de 4 fois le délai normal des messages. Juste après la reconnexion d’une session récemment active, cette première fenêtre utilise le délai normal des messages, plus court, au lieu de la fenêtre multipliée par 4. OpenClaw peut répondre automatiquement aux messages hors ligne que Baileys transmet au début de cette reconnexion, dans la limite de la durée de vie de la déduplication des identifiants de messages ; le démarrage initial conserve la courte protection contre l’historique obsolète.
• Les délais du socket Baileys sont définis explicitement sous web.whatsapp.* : keepAliveIntervalMs (intervalle des signaux ping de l’application), connectTimeoutMs (délai d’expiration de la négociation initiale), defaultQueryTimeoutMs (attentes des requêtes Baileys, ainsi que délais d’expiration d’OpenClaw pour les envois sortants, la présence et les accusés de lecture entrants).
• Les envois sortants nécessitent un écouteur WhatsApp actif pour le compte cible ; sinon, ils échouent immédiatement.
• Les envois aux groupes joignent des métadonnées natives de mention pour les jetons @+<digits> et @<digits> (dans le texte et les légendes des médias) lorsque le jeton correspond aux métadonnées actuelles d’un participant, y compris dans les groupes basés sur un LID.
• Les discussions de statut et de diffusion (@status, @broadcast) sont ignorées.
• Les discussions directes utilisent les règles de session des messages privés (session.dmScope ; la valeur par défaut main regroupe les messages privés dans la session principale de l’agent). Les sessions de groupe sont isolées par JID (agent:<agentId>:whatsapp:group:<jid>).
• Les canaux et newsletters WhatsApp peuvent être des cibles sortantes explicites par l’intermédiaire de leur JID @newsletter natif, en utilisant les métadonnées de session de canal (agent:<agentId>:whatsapp:channel:<jid>) plutôt que la sémantique des messages privés.
• Le transport WhatsApp Web respecte les variables d’environnement de proxy standard sur l’hôte du Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, ainsi que leurs variantes en minuscules). Préférez la configuration du proxy au niveau de l’hôte aux paramètres propres à chaque canal.
• Lorsque messages.removeAckAfterReply est activé, OpenClaw supprime la réaction d’accusé de réception dès qu’une réponse visible est remise.

​

Appeler le demandeur actuel avec MeowCaller (expérimental)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

​

Invites d’approbation

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

Hooks de plugin et confidentialité

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

​

Contrôle d’accès et activation

​

Liaisons ACP configurées

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

​

Comportement du numéro personnel et de la conversation avec soi-même

​

Normalisation des messages et contexte

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

​

Livraison, découpage et médias

​

Citation des réponses

{ channels: { whatsapp: { replyToMode: "first" } } }

​

Niveau de réaction

{ channels: { whatsapp: { reactionLevel: "ack" } } }

​

Réactions d’accusé de réception

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // toujours | mentions | jamais
      },
    },
  },
}

​

Réactions d’état du cycle de vie

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

​

Comptes multiples et identifiants

​

Outils, actions et écritures de configuration

• La prise en charge des outils de l’agent inclut l’action de réaction WhatsApp (react).
• Contrôles des actions : channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (les actions existantes utilisent par défaut true), channels.whatsapp.actions.calls (valeur par défaut : false, voir MeowCaller ci-dessus).
• Les écritures de configuration initiées par le canal sont activées par défaut ; désactivez-les via channels.whatsapp.configWrites: false.

​

Dépannage

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

Invites système

1. Invite propre au groupe (groups["<groupId>"].systemPrompt) : utilisée lorsque l’entrée du groupe existe et que sa clé systemPrompt est définie. Une chaîne vide ("") désactive le caractère générique et n’applique aucune invite.
2. Invite générique des groupes (groups["*"].systemPrompt) : utilisée lorsque l’entrée du groupe concerné est absente ou existe sans clé systemPrompt.

• channels.whatsapp.groups est à la fois une table de configuration propre à chaque groupe et la liste d’autorisation des groupes au niveau de la discussion. À la portée racine ou à celle du compte, groups["*"] signifie « tous les groupes sont autorisés » pour cette portée.
• N’ajoutez un caractère générique systemPrompt que si vous souhaitez déjà autoriser tous les groupes pour cette portée. Pour limiter l’admissibilité à un ensemble fixe d’identifiants de groupe, répétez l’invite dans chaque entrée explicitement autorisée au lieu d’utiliser groups["*"].
• L’admission des groupes et l’autorisation des expéditeurs sont deux vérifications distinctes. groups["*"] élargit l’ensemble des groupes qui atteignent le traitement des groupes ; il n’autorise pas tous les expéditeurs de ces groupes — cela reste contrôlé par groupPolicy/groupAllowFrom.
• channels.whatsapp.direct n’a aucun effet secondaire équivalent pour les messages directs : direct["*"] fournit uniquement une configuration par défaut après qu’un message direct a déjà été admis par dmPolicy ainsi que par allowFrom ou les règles du magasin de liaisons.

{
  channels: {
    whatsapp: {
      groups: {
        // À utiliser uniquement si tous les groupes doivent être autorisés à la portée racine.
        // S’applique à tous les comptes qui ne définissent pas leur propre table de groupes.
        "*": { systemPrompt: "Invite par défaut pour tous les groupes." },
      },
      direct: {
        // S’applique à tous les comptes qui ne définissent pas leur propre table de discussions directes.
        "*": { systemPrompt: "Invite par défaut pour toutes les discussions directes." },
      },
      accounts: {
        work: {
          groups: {
            // Ce compte définit ses propres groupes ; les groupes racines sont donc entièrement
            // remplacés. Pour conserver un caractère générique, définissez aussi explicitement "*" ici.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Se concentrer sur la gestion de projet.",
            },
            // À utiliser uniquement si tous les groupes doivent être autorisés pour ce compte.
            "*": { systemPrompt: "Invite par défaut pour les groupes professionnels." },
          },
          direct: {
            // Ce compte définit sa propre table de discussions directes ; les entrées directes racines sont donc
            // entièrement remplacées. Pour conserver un caractère générique, définissez aussi explicitement "*" ici.
            "+15551234567": { systemPrompt: "Invite pour une discussion professionnelle directe spécifique." },
            "*": { systemPrompt: "Invite par défaut pour les discussions professionnelles directes." },
          },
        },
      },
    },
  },
}

​

Renvois vers la référence de configuration

​

Pages connexes

• Liaison
• Groupes
• Sécurité
• Routage des canaux
• Routage multi-agent
• Dépannage