WhatsApp

​

Installation

openclaw plugins install clawhub:@openclaw/whatsapp

​

Schnelleinrichtung

{
  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>

​

Bereitstellungsmuster

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

​

Laufzeitmodell

• Der Gateway verwaltet den WhatsApp-Socket und die Wiederverbindungsschleife.
• Ein Watchdog überwacht zwei Signale unabhängig voneinander: die rohe WhatsApp-Web-Transportaktivität und die Aktivität der Anwendungsnachrichten. Eine ruhige, aber verbundene Sitzung wird nicht neu gestartet, nur weil kürzlich keine Nachricht eingegangen ist; eine Wiederverbindung wird nur erzwungen, wenn für ein festes internes Zeitfenster (nicht vom Benutzer konfigurierbar) keine Transport-Frames mehr eingehen oder Anwendungsnachrichten länger als das Vierfache des normalen Nachrichten-Timeouts ausbleiben. Direkt nach einer Wiederverbindung für eine kürzlich aktive Sitzung verwendet dieses erste Zeitfenster statt des vierfachen Fensters den kürzeren normalen Nachrichten-Timeout. OpenClaw kann automatisch auf Offline-Nachrichten antworten, die Baileys früh während dieser Wiederverbindung zustellt, begrenzt durch die Lebensdauer der Deduplizierung eingehender Nachrichten-IDs; beim ersten Start bleibt die kurze Schutzfrist gegen veraltete Verlaufsnachrichten bestehen.
• Ausgehende Sendungen erfordern einen aktiven WhatsApp-Listener für das Zielkonto; andernfalls schlagen sie sofort fehl.
• Gruppensendungen fügen native Erwähnungsmetadaten für @+<digits>- und @<digits>-Token (in Text und Medienbeschriftungen) hinzu, wenn das Token mit aktuellen Teilnehmermetadaten übereinstimmt, einschließlich LID-basierter Gruppen.
• Status- und Broadcast-Chats (@status, @broadcast) werden ignoriert.
• Direktchats verwenden DM-Sitzungsregeln (session.dmScope; der Standardwert main führt DMs in der Hauptsitzung des Agenten zusammen). Gruppensitzungen werden pro JID isoliert (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters können über ihre native @newsletter-JID explizite ausgehende Ziele sein und verwenden Kanal-Sitzungsmetadaten (agent:<agentId>:whatsapp:channel:<jid>) anstelle der DM-Semantik.
• Der WhatsApp-Web-Transport berücksichtigt die standardmäßigen Proxy-Umgebungsvariablen auf dem Gateway-Host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, Varianten in Kleinschreibung). Bevorzugen Sie eine Proxy-Konfiguration auf Hostebene gegenüber kanalspezifischen Einstellungen.

​

Aktuellen Anfragenden mit MeowCaller anrufen (experimentell)

{
  "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"

​

Genehmigungsaufforderungen

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

​

Reaktionen auf Fragen

​

Plugin-Hooks und Datenschutz

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

​

Zugriffskontrolle und Aktivierung

​

Konfigurierte ACP-Bindungen

{
  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" },
      },
    },
  ],
}

​

Verhalten bei persönlicher Nummer und Selbstchat

​

Nachrichtennormalisierung und Kontext

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

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

​

Zustellung, Aufteilung und Medien

​

Antwortzitate

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

​

Reaktionsstufe

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

​

Bestätigungsreaktionen

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

​

Lebenszyklus-Statusreaktionen

{
  messages: {
    statusReactions: {
      enabled: true,
    },
  },
}

​

Mehrere Konten und Anmeldedaten

​

Tools, Aktionen und Konfigurationsänderungen

• Die Unterstützung für Agent-Tools umfasst die WhatsApp-Reaktionsaktion (react).
• Aktionsfreigaben: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (vorhandene Aktionen verwenden standardmäßig true), channels.whatsapp.actions.calls (Standardwert false, siehe MeowCaller oben).
• Vom Kanal initiierte Konfigurationsänderungen sind standardmäßig aktiviert; deaktivieren Sie sie über channels.whatsapp.configWrites: false.

​

Fehlerbehebung

openclaw channels login --channel whatsapp
openclaw channels status

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>

​

System-Prompts

1. Gruppenspezifischer Prompt (groups["<groupId>"].systemPrompt): wird verwendet, wenn der Gruppeneintrag vorhanden und sein Schlüssel systemPrompt definiert ist. Eine leere Zeichenfolge ("") unterdrückt den Platzhalter und wendet keinen Prompt an.
2. Gruppen-Platzhalter-Prompt (groups["*"].systemPrompt): wird verwendet, wenn der spezifische Gruppeneintrag fehlt oder ohne Schlüssel systemPrompt vorhanden ist.

• channels.whatsapp.groups ist sowohl eine gruppenspezifische Konfigurationszuordnung als auch die Positivliste für Gruppen auf Chat-Ebene. Sowohl im Stamm- als auch im Kontogültigkeitsbereich bedeutet groups["*"], dass für diesen Gültigkeitsbereich „alle Gruppen zugelassen sind“.
• Fügen Sie den Platzhalter systemPrompt nur hinzu, wenn in diesem Gültigkeitsbereich bereits alle Gruppen zugelassen werden sollen. Damit nur eine festgelegte Gruppe von Gruppen-IDs zulässig bleibt, wiederholen Sie den Prompt für jeden ausdrücklich in der Positivliste aufgeführten Eintrag, anstatt groups["*"] zu verwenden.
• Gruppenzulassung und Absenderautorisierung sind separate Prüfungen. groups["*"] erweitert die Auswahl der Gruppen, die die Gruppenverarbeitung erreichen; dadurch werden nicht alle Absender in diesen Gruppen autorisiert — dies wird weiterhin durch groupPolicy/groupAllowFrom gesteuert.
• channels.whatsapp.direct hat für DMs keine entsprechende Nebenwirkung: direct["*"] stellt lediglich eine Standardkonfiguration bereit, nachdem eine DM bereits durch dmPolicy zusammen mit allowFrom oder Regeln des Kopplungsspeichers zugelassen wurde.

{
  channels: {
    whatsapp: {
      groups: {
        // Nur verwenden, wenn im Stammgültigkeitsbereich alle Gruppen zugelassen werden sollen.
        // Gilt für alle Konten, die keine eigene groups-Zuordnung definieren.
        "*": { systemPrompt: "Standard-Prompt für alle Gruppen." },
      },
      direct: {
        // Gilt für alle Konten, die keine eigene direct-Zuordnung definieren.
        "*": { systemPrompt: "Standard-Prompt für alle Direktchats." },
      },
      accounts: {
        work: {
          groups: {
            // Dieses Konto definiert eigene groups, daher werden die groups des Stammbereichs
            // vollständig ersetzt. Um einen Platzhalter beizubehalten, definieren Sie "*" auch hier ausdrücklich.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Konzentrieren Sie sich auf das Projektmanagement.",
            },
            // Nur verwenden, wenn in diesem Konto alle Gruppen zugelassen werden sollen.
            "*": { systemPrompt: "Standard-Prompt für Arbeitsgruppen." },
          },
          direct: {
            // Dieses Konto definiert eine eigene direct-Zuordnung, daher werden die direct-Einträge
            // des Stammbereichs vollständig ersetzt. Um einen Platzhalter beizubehalten, definieren Sie "*" auch hier ausdrücklich.
            "+15551234567": { systemPrompt: "Prompt für einen bestimmten geschäftlichen Direktchat." },
            "*": { systemPrompt: "Standard-Prompt für geschäftliche Direktchats." },
          },
        },
      },
    },
  },
}

​

Verweise zur Konfigurationsreferenz

​

Verwandte Themen

• Kopplung
• Gruppen
• Sicherheit
• Kanalrouting
• Multi-Agent-Routing
• Fehlerbehebung