OpenClaw installieren – Teil 4: Telegram & WhatsApp verbinden

📚 Serie: OpenClaw installieren & einrichten — Teil 4 von 8
← Teil 3: Modelle konfigurieren | Teil 5: Skills & Tools erweitern →

Ein KI-Agent wird erst dann im Alltag nützlich, wenn du ihn dort erreichst, wo deine Nachrichten ohnehin landen. Laut aktueller OpenClaw-Dokumentation bindest du Telegram über einen Bot ein. WhatsApp läuft in OpenClaw über eine gekoppelte WhatsApp-Web-Session mit einem externen WhatsApp-Plugin auf Basis von Baileys.¹²

Wichtig ist dabei nicht nur, dass die Verbindung technisch funktioniert. Messenger-Channels sind direkte Zugriffspunkte auf deinen Agenten. Starte deshalb restriktiv, nutze Pairing oder eine explizite Allowlist und validiere jede Änderung an der Config, bevor du den Gateway wieder produktiv laufen lässt.³⁴

Wenn du im QuickStart aus Teil 2 Telegram bereits ausgewählt und ein Bot-Token hinterlegt hast, musst du hier nicht alles neu aufsetzen. Dann reicht es, den aktuellen Stand zu prüfen, Pairing oder Allowlist sauber festzuziehen, eine Testnachricht zu schicken und erst danach WhatsApp dazuzunehmen.

Was du vorab brauchst

• Eine laufende oder startbare Gateway-Installation aus Teil 2
• Zugriff auf die OpenClaw-CLI auf dem Host, auf dem die aktive Config liegt
• Einen eigenen Telegram-Account, um über @BotFather einen Bot anzulegen, falls der QuickStart das noch nicht erledigt hat
• Einen aktiven WhatsApp-Account auf einem Smartphone
• Für WhatsApp: die Möglichkeit, den WhatsApp-Channel beziehungsweise das externe WhatsApp-Plugin zu installieren²
• Optional, aber praktisch: jq für JSON-Ausgaben im Terminal

Bevor du etwas änderst, prüfe zuerst, welche Config-Datei OpenClaw tatsächlich verwendet. Die passenden CLI-Befehle stehen in der OpenClaw-Config-Dokumentation.⁴⁵

openclaw config file
cp "$(openclaw config file)" "$(openclaw config file).bak.$(date +%Y%m%d-%H%M%S)"

Wenn Telegram schon im Onboarding eingerichtet wurde, lies danach den vorhandenen Stand aus:

openclaw config get channels.telegram --json
openclaw config validate

Nach jeder Änderung gilt dieselbe Routine:

openclaw config validate

Telegram anbinden

Bot erstellen und Token sicher bereitstellen

Öffne Telegram, schreibe @BotFather an und erstelle mit /newbot einen neuen Bot. BotFather fragt einen Anzeigenamen und einen eindeutigen Benutzernamen ab, der auf bot enden muss. Danach erhältst du ein Bot-Token.⁶

OpenClaw verwendet für Telegram laut Doku das Config-Feld channels.telegram.botToken.¹ Für lokale Tests im Vordergrund ist eine Umgebungsvariable oft der schnellste Weg:

export TELEGRAM_BOT_TOKEN="<YOUR_TELEGRAM_BOT_TOKEN>"

Wichtig: Diese Variable muss in der Umgebung des Gateway-Prozesses verfügbar sein. Ein export in deiner aktuellen Shell reicht nur dann, wenn du den Gateway auch genau aus dieser Shell startest.

Wenn du das Token nicht als Klartext in openclaw.json speichern willst, kannst du stattdessen eine Secret-Reference auf die Umgebungsvariable setzen:

openclaw config set channels.telegram.botToken \
  --ref-provider default \
  --ref-source env \
  --ref-id TELEGRAM_BOT_TOKEN

Prüfe danach, ob deine installierte Version das Feld so erwartet:

openclaw config schema | grep -n "telegram" -A 40
openclaw config get channels.telegram --json
openclaw config validate

Restriktiv starten: Pairing zuerst

Für private Installationen ist Pairing meist der sauberste Startpunkt. Wenn ein Channel mit dmPolicy: "pairing" arbeitet, verarbeitet OpenClaw Nachrichten unbekannter Absender nicht sofort. Stattdessen wird ein kurzer Code erzeugt, der erst explizit freigegeben werden muss. Laut offizieller Pairing-Doku laufen DM-Pairing-Codes nach einer Stunde ab.³

Prüfe zuerst deine aktuelle Telegram-Konfiguration:

openclaw config get channels.telegram --json

Wenn dort dmPolicy bereits auf pairing steht, musst du nichts weiter patchen. Schreibe dem Bot dann eine Testnachricht, zum Beispiel /start, und prüfe anschließend mit der Pairing-CLI deiner installierten Version, ob eine Anfrage offen ist:

openclaw pairing --help

Die exakten Unterbefehle für Listen und Freigaben solltest du immer über die Hilfe deiner installierten Version prüfen, statt hier blind alte Syntax zu übernehmen.

Nur wenn Telegram noch nicht auf Pairing steht, kannst du die Channel-Config per Patch nachziehen:

cat > ./telegram-channel.json5 <<'EOF'
{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing",
      groups: {
        "*": {
          requireMention: true,
        },
      },
    },
  },
}
EOF

Wende den Patch zuerst als Trockenlauf an und validiere danach:

openclaw config patch --file ./telegram-channel.json5 --dry-run
openclaw config patch --file ./telegram-channel.json5
openclaw config validate
openclaw config get channels.telegram --json

Telegram arbeitet laut OpenClaw-Doku mit Bot-Token in Config oder Umgebung. Einen separaten QR- oder Session-Login wie bei WhatsApp gibt es hier nicht.¹

Für einen Test im Vordergrund kannst du den Gateway direkt starten:

openclaw gateway

Wenn dein Gateway bereits über einen Dienstmanager läuft, starte ihn mit der für dein Setup vorgesehenen Methode neu.

Alternative: feste Telegram-Allowlist

Wenn nur einzelne Personen zugreifen dürfen, kannst du statt Pairing eine feste Allowlist verwenden. Dafür brauchst du die numerische Telegram-User-ID.

Eine nachvollziehbare Methode ist die Telegram Bot API. Sende zuerst eine Nachricht an deinen Bot und lies dann die letzten Updates aus:

curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates" \
  | jq '.result[].message.from | {id, username, first_name}'

Danach prüfst du mit openclaw config schema, welche Allowlist-Felder deine installierte OpenClaw-Version für Telegram tatsächlich erwartet. Genau an dieser Stelle unterscheiden sich Builds und Doku-Stände schneller als bei den Grundbefehlen. Wichtig ist: erst Schema prüfen, dann patchen, dann validieren.

requireMention: true ist in Gruppen meist eine sinnvolle Voreinstellung, damit der Bot nicht auf jede Nachricht reagiert. Zusätzlich solltest du in BotFather prüfen, ob die Privacy-Einstellungen deines Bots zu deinem gewünschten Gruppenverhalten passen.⁶

WhatsApp integrieren

OpenClaw unterstützt WhatsApp laut aktueller Dokumentation über WhatsApp Web mit Baileys. Der Gateway hält dabei die gekoppelte Session. Dein WhatsApp-Account sieht OpenClaw in der App also wie ein verlinktes Gerät.²

Das ist praktisch, aber technisch empfindlicher als eine offiziell von Meta bereitgestellte Business-API-Integration. Wenn WhatsApp Web sein Verhalten ändert, können Login oder Laufzeit temporär brechen.

WhatsApp-Plugin installieren

Die WhatsApp-Laufzeit wird laut Doku außerhalb des OpenClaw-Core-Pakets verteilt. Beim Onboarding, bei openclaw channels add --channel whatsapp oder beim Login kann OpenClaw die Installation je nach Version automatisch anbieten. Der dokumentierte manuelle Weg bleibt:

openclaw plugins install clawhub:@openclaw/whatsapp

Alternativ kannst du den Channel auch direkt hinzufügen:

openclaw channels add --channel whatsapp

Validiere danach die Config:

openclaw config validate

Restriktive Basiskonfiguration

Wenn du mit einer dedizierten WhatsApp-Nummer arbeitest, ist Pairing auch hier ein guter restriktiver Start: Unbekannte Direktnachrichten werden dann nicht sofort verarbeitet, sondern erst nach Freigabe.³²

cat > ./whatsapp-channel.json5 <<'EOF'
{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
EOF

openclaw config patch --file ./whatsapp-channel.json5 --dry-run
openclaw config patch --file ./whatsapp-channel.json5
openclaw config validate
openclaw config get channels.whatsapp --json

Wenn du keine dedizierte Nummer verwendest, sondern deinen persönlichen WhatsApp-Account koppelst, prüfe besonders sorgfältig mit openclaw config schema und der aktuellen WhatsApp-Doku, welche Freigabefelder deine Version wirklich unterstützt. Verlasse dich hier nicht auf alte Blogposts, fremde Snippets oder pauschale Copy-and-paste-Beispiele.

Veröffentliche keine pauschalen WhatsApp-Gruppenfreigaben. Gruppen- und Channel-IDs solltest du erst konfigurieren, wenn deine Version diese IDs eindeutig aus Doku, Schema oder Laufzeitinformationen ableitbar macht. Telefonnummern sind nicht automatisch gültige Gruppenkennungen.²

QR-Code-Kopplung starten

Für die Kopplung stellt OpenClaw den dokumentierten Login-Flow bereit:

openclaw channels login --channel whatsapp

Der Befehl sollte einen QR-Code im Terminal anzeigen und kann bei fehlendem Plugin auch den Installationsflow anbieten.² Öffne auf dem Smartphone WhatsApp, gehe zu Verlinkte Geräte und scanne den Code.

Falls deine Version den Flow nicht automatisch anbietet, installiere das Plugin manuell und starte den Login erneut:

openclaw plugins install clawhub:@openclaw/whatsapp
openclaw channels login --channel whatsapp

Starte danach den Gateway mit deiner üblichen Methode oder für einen Test im Vordergrund so:

openclaw gateway

Wenn WhatsApp auf Pairing steht, prüfst du die Freigabe anschließend wieder mit der Pairing-CLI deiner installierten Version:

openclaw pairing --help

Sende danach eine kurze Testnachricht an die gekoppelte Nummer.

Offizielle WhatsApp Business API

Die in diesem Artikel referenzierte OpenClaw-Dokumentation beschreibt WhatsApp aktuell über WhatsApp Web und Baileys. Eine generische Business-API-Konfiguration solltest du daraus nicht ableiten.²

Für produktive Unternehmens-Setups kann eine offizielle WhatsApp-Business-API organisatorisch und rechtlich sauberer sein. Richte diesen Weg aber nur ein, wenn deine konkrete OpenClaw-Version ihn ausdrücklich unterstützt und das Config-Schema die nötigen Felder auch wirklich zeigt.

Fehlerbehebung und Sicherheit

Wenn Telegram nicht reagiert, prüfe zuerst diese Punkte:

• Läuft der Gateway wirklich?
• Ist TELEGRAM_BOT_TOKEN in der Umgebung des Gateway-Prozesses gesetzt, falls du den Env-Weg nutzt?
• Ist channels.telegram.botToken gesetzt oder korrekt als Secret-Reference hinterlegt?
• Zeigt openclaw config validate Fehler?
• Gibt es eine offene Pairing-Anfrage?
• Reagiert der Bot in Gruppen nur nicht, weil requireMention aktiv ist oder BotFather-Privacy-Einstellungen greifen?

Bei WhatsApp-Problemen helfen meist diese Checks:

• Ist das WhatsApp-Plugin installiert?
• Ist das Smartphone online und WhatsApp aktiv?
• Ist das Gerät in WhatsApp weiterhin unter Verlinkte Geräte sichtbar?
• Den QR-Login erneut ausführen, wenn die Session ungültig wurde
• Gateway-Logs während des Logins verfolgen
• OpenClaw und das WhatsApp-Plugin aktualisieren, wenn WhatsApp Web sich geändert hat

Für beide Messenger gilt:

• Tokens und Session-Dateien gehören nicht ins Git-Repository.
• Starte mit Pairing oder einer expliziten Allowlist, nie mit offenem Zugriff.
• Erlaube Gruppen erst nach expliziter Prüfung.
• Entferne verlorene oder nicht mehr genutzte Geräte und Sessions.
• Prüfe Logs regelmäßig auf unbekannte Absender und unerwartete Prompts.

Kurz zusammengefasst

Wenn du OpenClaw an Messenger hängst, ist die technische Verbindung nur die halbe Miete. Entscheidend ist, dass du mit restriktiven Defaults startest, jede Änderung validierst und versionsabhängige Details immer erst an deiner installierten Doku und deinem Config-Schema prüfst. Telegram ist meist schnell sauber angebunden, bei WhatsApp solltest du zusätzlich genauer auf Session-Modell, Nummerntyp und Betriebsrisiko schauen.

Footnotes

1. OpenClaw-Doku: Telegram-Channel, https://docs.openclaw.ai/channels/telegram ↩ ↩² ↩³

2. OpenClaw-Doku: WhatsApp-Channel, https://docs.openclaw.ai/channels/whatsapp ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

3. OpenClaw-Doku: Pairing, https://docs.openclaw.ai/channels/pairing ↩ ↩² ↩³

4. OpenClaw-Doku: openclaw config, https://docs.openclaw.ai/cli/config ↩ ↩²

5. OpenClaw-Doku: openclaw configure, https://docs.openclaw.ai/cli/configure ↩

6. Telegram-Doku: Bots, https://core.telegram.org/bots ↩ ↩²