English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Configuration

WhatsApp-Gruppennachrichten

Für das kanalübergreifende Gruppenmodell (Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo) siehe Gruppen. Diese Seite behandelt das WhatsApp-spezifische Verhalten zusätzlich zu diesem Modell: Aktivierung, Gruppen-Allowlists, Sitzungsschlüssel pro Gruppe und Kontextinjektion aus ausstehenden Nachrichten.

Ziel: OpenClaw kann in WhatsApp-Gruppen sitzen, nur bei einem Ping aufwachen und diesen Thread von der persönlichen DM-Sitzung getrennt halten.

Verhalten

  • Aktivierungsmodi: mention (Standard) oder always. mention erfordert einen Ping (echte WhatsApp-@-Erwähnungen über mentionedJids, sichere Regex-Muster oder die E.164-Nummer des Bots an beliebiger Stelle im Text). always weckt den Agent bei jeder Nachricht, er sollte aber nur antworten, wenn er einen sinnvollen Mehrwert liefern kann; andernfalls gibt er das exakte stille Token NO_REPLY / no_reply zurück. Standardwerte können in der Konfiguration (channels.whatsapp.groups) festgelegt und pro Gruppe über /activation überschrieben werden. Wenn channels.whatsapp.groups gesetzt ist, dient es außerdem als Gruppen-Allowlist (fügen Sie "*" hinzu, um alle zu erlauben).
  • Gruppenrichtlinie: channels.whatsapp.groupPolicy steuert, ob Gruppennachrichten akzeptiert werden (open|disabled|allowlist). allowlist verwendet channels.whatsapp.groupAllowFrom (Fallback: explizites channels.whatsapp.allowFrom). Standard ist allowlist (blockiert, bis Sie Absender hinzufügen).
  • Sitzungen pro Gruppe: Sitzungsschlüssel sehen wie agent:<agentId>:whatsapp:group:<jid> aus, sodass Befehle wie /verbose on, /trace on oder /think high (als eigenständige Nachrichten gesendet) auf diese Gruppe beschränkt sind; der persönliche DM-Status bleibt unverändert. Heartbeats werden für Gruppen-Threads übersprungen.
  • Kontextinjektion: nur ausstehende Gruppennachrichten (Standard 50), die keinen Lauf ausgelöst haben, werden unter [Chat messages since your last reply - for context] vorangestellt, mit der auslösenden Zeile unter [Current message - respond to this]. Nachrichten, die bereits in der Sitzung enthalten sind, werden nicht erneut injiziert.
  • Absenderanzeige: Jeder Gruppen-Batch endet jetzt mit [from: Sender Name (+E164)], damit Pi weiß, wer spricht.
  • Ephemer/Einmalansicht: Wir entpacken diese Nachrichten vor dem Extrahieren von Text/Erwähnungen, sodass Pings darin weiterhin auslösen.
  • Gruppen-System-Prompt: Beim ersten Turn einer Gruppensitzung (und immer dann, wenn /activation den Modus ändert) injizieren wir einen kurzen Hinweis in den System-Prompt wie You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. Wenn keine Metadaten verfügbar sind, teilen wir dem Agent trotzdem mit, dass es sich um einen Gruppenchat handelt.

Konfigurationsbeispiel (WhatsApp)

Fügen Sie einen groupChat-Block zu ~/.openclaw/openclaw.json hinzu, damit Pings über Anzeigenamen auch dann funktionieren, wenn WhatsApp das sichtbare @ im Textkörper entfernt:

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

Hinweise:

  • Die Regexes sind groß-/kleinschreibungsunabhängig und verwenden dieselben Safe-Regex-Schutzmechanismen wie andere Regex-Oberflächen in der Konfiguration; ungültige Muster und unsichere verschachtelte Wiederholungen werden ignoriert.
  • WhatsApp sendet weiterhin kanonische Erwähnungen über mentionedJids, wenn jemand auf den Kontakt tippt. Der Nummern-Fallback wird daher selten benötigt, ist aber ein nützliches Sicherheitsnetz.

Aktivierungsbefehl (nur Owner)

Verwenden Sie den Gruppenchat-Befehl:

  • /activation mention
  • /activation always

Nur die Owner-Nummer (aus channels.whatsapp.allowFrom oder, falls nicht gesetzt, die eigene E.164-Nummer des Bots) kann dies ändern. Senden Sie /status als eigenständige Nachricht in der Gruppe, um den aktuellen Aktivierungsmodus zu sehen.

Verwendung

  1. Fügen Sie Ihr WhatsApp-Konto (das Konto, auf dem OpenClaw läuft) zur Gruppe hinzu.
  2. Schreiben Sie @openclaw … (oder fügen Sie die Nummer ein). Nur Absender auf der Allowlist können es auslösen, sofern Sie nicht groupPolicy: "open" festlegen.
  3. Der Agent-Prompt enthält den aktuellen Gruppenkontext plus die abschließende [from: …]-Markierung, damit er die richtige Person ansprechen kann.
  4. Sitzungsbezogene Anweisungen (/verbose on, /trace on, /think high, /new oder /reset, /compact) gelten nur für die Sitzung dieser Gruppe; senden Sie sie als eigenständige Nachrichten, damit sie registriert werden. Ihre persönliche DM-Sitzung bleibt unabhängig.

Testen / Verifizierung

  • Manueller Smoke-Test:
    • Senden Sie einen @openclaw-Ping in der Gruppe und bestätigen Sie eine Antwort, die den Namen des Absenders referenziert.
    • Senden Sie einen zweiten Ping und prüfen Sie, dass der Verlaufsblock enthalten ist und beim nächsten Turn gelöscht wird.
  • Prüfen Sie die Gateway-Logs (mit --verbose ausführen), um Einträge vom Typ inbound web message zu sehen, die from: <groupJid> und das Suffix [from: …] anzeigen.

Bekannte Hinweise

  • Heartbeats werden für Gruppen absichtlich übersprungen, um störende Broadcasts zu vermeiden.
  • Echo-Unterdrückung verwendet den kombinierten Batch-String; wenn Sie zweimal identischen Text ohne Erwähnungen senden, erhält nur die erste Nachricht eine Antwort.
  • Einträge im Sitzungsspeicher erscheinen als agent:<agentId>:whatsapp:group:<jid> im Sitzungsspeicher (standardmäßig ~/.openclaw/agents/<agentId>/sessions/sessions.json); ein fehlender Eintrag bedeutet lediglich, dass die Gruppe noch keinen Lauf ausgelöst hat.
  • Tippindikatoren in Gruppen folgen agents.defaults.typingMode. Wenn sichtbare Antworten den Standardmodus nur über das Nachrichten-Tool verwenden, beginnt das Tippen standardmäßig sofort, sodass Gruppenmitglieder sehen können, dass der Agent arbeitet, selbst wenn keine automatische finale Antwort gepostet wird. Eine explizite Tippmodus-Konfiguration hat weiterhin Vorrang.

Verwandt