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. Nach Installation und Modellkonfiguration bindet dieser Teil OpenClaw an Telegram und WhatsApp an. Telegram läuft über einen Bot, WhatsApp in privaten Setups typischerweise über eine gekoppelte Web-Session per QR-Code.

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

Voraussetzungen

• Ein laufender OpenClaw Gateway 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
• Optional, aber empfohlen: jq für JSON-Ausgaben im Terminal

Vor Änderungen solltest du prüfen, welche Config-Datei OpenClaw tatsächlich verwendet:

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 ablegen

Ö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.

Lege das Token nicht direkt in openclaw.json ab. Für lokale Setups ist eine Umgebungsvariable der einfachste Einstieg:

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

Persistenter ist es, den Wert über OpenClaws Secret-Reference-Mechanismus an die Config zu binden. Die OpenClaw-CLI dokumentiert diesen Stil für Channel-Tokens; für Telegram wird derselbe Ansatz verwendet:

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

Falls deine installierte OpenClaw-Version laut Schema statt channels.telegram.token einen anderen Telegram-Token-Pfad verwendet, nimm den vom Schema ausgegebenen Pfad. Prüfe das im Zweifel mit:

openclaw config schema | grep -n "telegram" -A 40

Pairing aktivieren

Für private Installationen ist Pairing der bessere Startpunkt als eine offene Direktfreigabe. Unbekannte Absender werden nicht sofort zugelassen, sondern müssen zuerst freigegeben werden.

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

Starte anschließend den Gateway mit der Methode neu, mit der du ihn installiert hast. Wenn deine Installation den Gateway-CLI-Befehl bereitstellt, reicht beispielsweise:

openclaw gateway restart

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 statt Pairing eine 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 dann in die OpenClaw-Konfiguration ein:

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 kann WhatsApp für private Setups über eine gekoppelte Web-Session nutzen. Der Account erscheint dabei wie ein verlinktes Gerät in der WhatsApp-App. Diese Methode ist praktisch, aber sensibler als eine offizielle Business-Integration: Änderungen am WhatsApp-Web-Protokoll können temporär zu Ausfällen führen.

Restriktive Basiskonfiguration

Starte mit einer direkten Allowlist für deine eigene Nummer. Verwende das E.164-Format ohne Leerzeichen, zum Beispiel +491701234567.

cat > ./whatsapp-channel.json5 <<'EOF'
{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",
      allowFrom: ["+491701234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: [],
    },
  },
}
EOF

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

Die leere Gruppen-Allowlist ist Absicht: Schalte WhatsApp-Gruppen erst frei, wenn du die von OpenClaw erwarteten Gruppen-IDs bzw. Channel-Locations sicher aus den Logs oder der Channel-Doku ermittelt hast. Telefonnummern sind nicht automatisch gültige Gruppenkennungen.

QR-Code-Kopplung starten

Für die Kopplung stellt OpenClaw je nach Version einen Channel-Login-Flow oder den interaktiven Channel-Konfigurator bereit. Versuche zuerst:

openclaw channels login --channel whatsapp

Der Befehl sollte einen QR-Code im Terminal anzeigen. Öffne auf dem Smartphone WhatsApp, gehe zu Verlinkte Geräte und scanne den Code.

Falls deine Version diesen Befehl nicht kennt, nutze den dokumentierten Konfigurationsassistenten und wähle dort den WhatsApp-Channel:

openclaw configure --section channels

Starte danach den Gateway neu und prüfe ausstehende Pairing-Anfragen:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Sende anschließend eine kurze Testnachricht an die gekoppelte Nummer.

Offizielle WhatsApp Business API

Für produktive Unternehmens-Setups ist die offizielle WhatsApp Business API der sauberere Weg. Sie erfordert unter anderem Meta Business Manager, WhatsApp-Business-Freigaben, verifizierte Webhooks und passende Tokens.

Richte diese Variante nicht anhand eines generischen Beispiel-Webhooks ein. Prüfe zuerst die aktuelle OpenClaw-WhatsApp-Doku und die Meta-Dokumentation für deine konkrete OpenClaw-Version. Erst wenn OpenClaw den Business-API-Provider in deiner Version ausdrücklich unterstützt und das Config-Schema die benötigten Felder zeigt, solltest du Tokens und Webhook-URLs konfigurieren.

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?
• 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:

• 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 die Channel-Abhängigkeiten 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 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.