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 entfaltet seinen vollen Nutzen erst, wenn er dort erreichbar ist, wo du ohnehin kommunizierst. Laut aktueller OpenClaw-Dokumentation bindest du Telegram über einen Bot ein. WhatsApp läuft in OpenClaw über eine gekoppelte WhatsApp-Web-Session mit dem externen WhatsApp-Plugin auf Basis von Baileys.¹²

Wichtig: Messenger-Channels sind direkte Zugriffspunkte auf deinen Agenten. Starte deshalb restriktiv, nutze Pairing oder eine explizite Allowlist und prüfe jede Konfigurationsänderung mit der OpenClaw-Config-Validierung.

Voraussetzungen

• Eine laufende oder startbare Gateway-Installation aus Teil 2¹
• Zugriff auf die OpenClaw-CLI auf dem Host, auf dem die aktive Config liegt
• Ein eigener Telegram-Account, um über @BotFather einen Bot anzulegen
• Ein aktiver WhatsApp-Account auf einem Smartphone
• Für WhatsApp: die Möglichkeit, den WhatsApp-Channel bzw. das externe WhatsApp-Plugin zu installieren²
• Optional, aber praktisch: jq für JSON-Ausgaben im Terminal

Vor Änderungen solltest du prüfen, welche Config-Datei OpenClaw tatsächlich verwendet. Die dafür vorgesehenen 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)"

Nach jeder Änderung ist eine Validierung Pflicht:

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 nutzt für Telegram laut Doku das Config-Feld channels.telegram.botToken. Alternativ kann für den Standard-Account die Umgebungsvariable TELEGRAM_BOT_TOKEN verwendet werden.¹

Für lokale Tests ist die Umgebungsvariable der einfachste Start:

export TELEGRAM_BOT_TOKEN="123456:ABC-..."

Wichtig: Diese Variable muss in der Umgebung des Gateway-Prozesses gesetzt sein. Wenn dein Gateway über systemd, Docker oder einen anderen Service-Manager läuft, reicht ein export in deiner aktuellen Shell nicht automatisch aus.

Wenn du das Token nicht als Klartext in openclaw.json speichern willst, kannst du es als Secret-Reference auf die Umgebungsvariable zeigen lassen. Verwende dabei den dokumentierten Telegram-Pfad channels.telegram.botToken:

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

Prüfe bei Versionsabweichungen zuerst das installierte Schema:

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

Pairing aktivieren

Für private Installationen ist Pairing der bessere Startpunkt als eine offene Direktfreigabe. Unbekannte Absender werden nicht sofort zugelassen, sondern erhalten einen kurzen Code. Erst nach Freigabe verarbeitet OpenClaw ihre Nachrichten. Laut Pairing-Dokumentation laufen DM-Pairing-Codes nach 1 Stunde ab.⁶

Erstelle eine kleine Patch-Datei:

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

Wende sie 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 verwendet keinen openclaw channels login telegram-Flow. Das Token muss in Config oder Umgebung stehen; danach startest du den Gateway.¹

Für einen Vordergrund-Test ist der dokumentierte Startbefehl:

openclaw gateway

Wenn dein Gateway bereits als Dienst läuft, starte ihn mit deinem eigenen Service-Manager neu, zum Beispiel über deine systemd-, Docker- oder Supervisor-Konfiguration.

Schreibe dem Bot danach in Telegram eine Testnachricht, zum Beispiel /start. Wenn Pairing aktiv ist, sollte OpenClaw eine ausstehende Anfrage anzeigen. Die Freigabe erfolgt über die Pairing-CLI:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Alternative: feste Telegram-Allowlist

Wenn nur einzelne Personen zugreifen dürfen, kannst du nach dem ersten Funktionstest 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}'

Trage die eigene ID anschließend in die OpenClaw-Konfiguration ein. Prüfe vor produktiver Nutzung mit openclaw config schema, ob deine installierte Version die Policy- und Allowlist-Felder exakt so erwartet:

cat > ./telegram-allowlist.json5 <<'EOF'
{
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],
      groups: {
        "*": {
          requireMention: true,
        },
      },
    },
  },
}
EOF

openclaw config patch --file ./telegram-allowlist.json5 --dry-run
openclaw config patch --file ./telegram-allowlist.json5
openclaw config validate

requireMention: true verhindert, dass der Bot in Gruppen 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 produktionsbereit über WhatsApp Web mit Baileys. Der Gateway besitzt dabei die gekoppelte Session. Der Account erscheint in der WhatsApp-App wie ein verlinktes Gerät.²

Diese Methode ist praktisch, aber sensibler als eine offiziell durch Meta bereitgestellte Business-API-Integration: Änderungen am WhatsApp-Web-Protokoll können temporär zu Ausfällen führen.

WhatsApp-Plugin installieren

Die WhatsApp-Laufzeit wird laut Doku außerhalb des OpenClaw-Core-Pakets verteilt. Onboarding, openclaw channels add --channel whatsapp und openclaw channels login --channel whatsapp können die Installation je nach Version anstoßen. Der dokumentierte manuelle Installationsweg bleibt:

openclaw plugins install clawhub:@openclaw/whatsapp

Validiere danach die Config:

openclaw config validate

Restriktive Basiskonfiguration

Starte mit Pairing. Dadurch werden unbekannte Direktnachrichten nicht sofort verarbeitet, sondern müssen explizit freigegeben werden.⁶²

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

Veröffentliche keine pauschalen WhatsApp-Gruppenfreigaben. WhatsApp-Gruppen und Channel-Locations solltest du erst konfigurieren, wenn du die von deiner OpenClaw-Version erwarteten IDs sicher aus der offiziellen Channel-Doku, der Config-Schema-Ausgabe oder den Gateway-Logs ermittelt hast. Telefonnummern sind nicht automatisch gültige Gruppenkennungen.

QR-Code-Kopplung starten

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

openclaw channels login --channel whatsapp

Der Befehl sollte einen QR-Code im Terminal anzeigen und kann laut Doku 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 Vordergrund-Test so:

openclaw gateway

Prüfe anschließend ausstehende Pairing-Anfragen:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Sende danach eine kurze Testnachricht an die gekoppelte Nummer.

Offizielle WhatsApp Business API

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

Für produktive Unternehmens-Setups kann eine offizielle WhatsApp-Business-API-Integration organisatorisch und rechtlich sauberer sein. Sie erfordert unter anderem Meta Business Manager, WhatsApp-Business-Freigaben, verifizierte Webhooks und passende Tokens. Richte diese Variante aber nur ein, wenn deine konkrete OpenClaw-Version sie ausdrücklich unterstützt und das Config-Schema die benötigten Felder 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-Fallback nutzt?
• Ist bei Config-Ablage das Feld channels.telegram.botToken gesetzt oder korrekt als Secret-Reference hinterlegt?
• Zeigt openclaw config validate Fehler?
• Gibt es ausstehende Pairing-Anfragen?
• 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?
• Smartphone online und WhatsApp aktiv?
• Gerät in WhatsApp weiterhin unter Verlinkte Geräte sichtbar?
• QR-Code-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/Sessions.
• Prüfe Logs regelmäßig auf unbekannte Absender und unerwartete Prompts.

Footnotes

1. https://docs.openclaw.ai/channels/telegram ↩ ↩² ↩³ ↩⁴

2. https://docs.openclaw.ai/channels/whatsapp ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

3. https://docs.openclaw.ai/cli/config ↩

4. https://docs.openclaw.ai/cli/configure ↩

5. https://core.telegram.org/bots ↩

6. https://docs.openclaw.ai/channels/pairing ↩ ↩²