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 im Alltag erst dann wirklich nützlich, wenn du ihn dort erreichst, wo deine Nachrichten ohnehin landen. Telegram bindet OpenClaw über einen Bot ein. WhatsApp läuft über eine gekoppelte WhatsApp-Web-Session und das externe OpenClaw-Plugin @openclaw/whatsapp, das Baileys verwendet.¹²

Messenger sind gleichzeitig direkte Zugriffspunkte auf deinen Agenten. Starte deshalb mit Pairing oder einer expliziten Allowlist. Gruppen solltest du erst einzeln freigeben, nachdem Direktnachrichten zuverlässig und sicher funktionieren.³

Wenn du Telegram bereits beim Onboarding eingerichtet hast, musst du den Channel nicht neu anlegen. Prüfe dann nur Token, Zugriffsregeln und Verbindung.

Was du vorab brauchst

• Eine startbare OpenClaw-Gateway-Installation
• Zugriff auf die OpenClaw-CLI des Hosts mit der aktiven Config
• Einen Telegram-Account und bei einer Neueinrichtung Zugriff auf @BotFather
• Einen aktiven WhatsApp-Account auf einem Smartphone
• Für WhatsApp einen freien Platz unter Verlinkte Geräte
• Optional jq, um JSON-Ausgaben im Terminal besser zu lesen

Prüfe zuerst den Pfad der tatsächlich verwendeten Config und lege eine lokale Sicherung an:⁴

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

Nach jeder Änderung gilt:

openclaw config validate

Ein Vordergrundtest mit openclaw gateway ist nur sinnvoll, wenn noch kein Gateway-Prozess läuft. Für eine dauerhaft laufende Installation startest du den bestehenden Dienst mit der bei deiner Installation vorgesehenen Methode neu.

Telegram anbinden

Bot erstellen und Token hinterlegen

Öffne in Telegram den verifizierten Bot @BotFather und starte /newbot. Vergib einen Anzeigenamen und einen eindeutigen Benutzernamen, der auf bot endet. Anschließend zeigt BotFather das Bot-Token an.⁵

Behandle dieses Token wie ein Passwort. Poste es nicht in Chats, Screenshots oder Git-Repositories.

Für einen lokalen Test kannst du es als Umgebungsvariable bereitstellen:

export TELEGRAM_BOT_TOKEN="<YOUR_TELEGRAM_BOT_TOKEN>"

Der Env-Fallback gilt laut aktueller OpenClaw-Dokumentation für den Telegram-Standard-Account. Die Variable muss außerdem in der Umgebung des Gateway-Prozesses existieren. Ein export in deinem Terminal erreicht keinen bereits laufenden Systemdienst.¹

Dauerhafter und kontrollierter ist eine Secret-Reference:

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

Aktiviere anschließend Telegram mit Pairing für Direktnachrichten:

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.dmPolicy pairing
openclaw config validate
openclaw config get channels.telegram --json

Starte danach den Gateway-Dienst mit der für deine Installation vorgesehenen Methode neu. Für einen interaktiven Test ohne bereits laufenden Gateway-Prozess kannst du ihn im Vordergrund starten:

openclaw gateway

Telegram-Absender pairen

Schreibe dem Bot in Telegram eine Direktnachricht, beispielsweise /start. Unbekannte Absender erhalten bei dmPolicy: "pairing" einen kurzen Code. Die ursprüngliche Nachricht wird noch nicht verarbeitet. Pairing-Anfragen laufen nach einer Stunde ab.³

Liste die offene Anfrage auf und genehmige den angezeigten Code:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Mit --notify kann OpenClaw dem Absender die Freigabe im selben Channel bestätigen:

openclaw pairing approve telegram <CODE> --notify

Sende danach eine zweite Testnachricht. Prüfe bei Problemen Status und Logs:

openclaw channels status
openclaw logs --follow

Alternative: feste Telegram-Allowlist

Für einen Bot mit genau einem Betreiber ist eine feste Allowlist noch eindeutiger. Sie benötigt deine numerische Telegram-User-ID.

Sende dem Bot zuerst eine Nachricht. Wenn kein anderer Prozess das Bot-Token gleichzeitig per Long Polling verwendet, kannst du die letzten Bot-API-Updates auslesen:

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

Beende dafür gegebenenfalls kurz den Gateway: Telegram erlaubt nicht, dass zwei Poller dasselbe Bot-Token parallel mit getUpdates verwenden.

Trage anschließend ausschließlich deine numerische User-ID ein:

openclaw config set channels.telegram.dmPolicy allowlist
openclaw config set channels.telegram.allowFrom '["<YOUR_TELEGRAM_USER_ID>"]' --strict-json
openclaw config validate
openclaw config get channels.telegram --json

Telegram-Gruppen bewusst freigeben

DM-Pairing autorisiert keinen Absender automatisch für Gruppen. Telegram-Gruppen haben getrennte Regeln: channels.telegram.groups bestimmt, welche Gruppen zugelassen sind; groupPolicy und groupAllowFrom bestimmen, welche Absender dort schreiben dürfen.¹³

Ermittle die Gruppen-ID über openclaw logs --follow, Bot-API-Updates oder /whoami@<bot_username>, sobald der Bot in der Gruppe zugelassen ist. Supergroup-IDs beginnen typischerweise mit -100.

Lege in einem temporären, nicht versionierten Verzeichnis eine Datei namens telegram-group.json5 mit diesem Inhalt an:

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["<YOUR_TELEGRAM_USER_ID>"],
      groups: {
        "<YOUR_TELEGRAM_GROUP_ID>": {
          requireMention: true,
        },
      },
    },
  },
}

Prüfe und übernehme den Patch anschließend:

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

Setze hier keine Gruppen-ID in groupAllowFrom: Dort gehören User-IDs hinein. Die negative Gruppen-ID ist der Schlüssel unter groups.

Mit requireMention: true reagiert der Bot nur bei einer ausdrücklichen Erwähnung. Wenn du später requireMention: false verwendest, muss BotFathers Privacy Mode den Empfang normaler Gruppennachrichten erlauben. Nach einer Änderung der Privacy-Einstellung kann es nötig sein, den Bot aus der Gruppe zu entfernen und neu hinzuzufügen.¹⁵

WhatsApp integrieren

OpenClaw koppelt WhatsApp als verlinktes Gerät über WhatsApp Web. Es gibt in diesem Channel keine separate Twilio-Integration. Der Gateway verwaltet die verknüpfte Baileys-Session.²

WhatsApp-Plugin installieren

openclaw onboard, openclaw channels add --channel whatsapp und der Login-Flow können die Plugin-Installation anbieten. Der dokumentierte manuelle Weg lautet:

openclaw plugins install clawhub:@openclaw/whatsapp

Danach kannst du den Channel hinzufügen und die Config prüfen:

openclaw channels add --channel whatsapp
openclaw config validate
openclaw config get channels.whatsapp --json

Wenn der Channel bereits beim Onboarding angelegt wurde, genügt die Prüfung des vorhandenen Blocks.

Dedizierte WhatsApp-Nummer mit Pairing

Bei einer separaten Nummer für OpenClaw ist Pairing ein sinnvoller Start:

openclaw config set channels.whatsapp.enabled true
openclaw config set channels.whatsapp.dmPolicy pairing
openclaw config set channels.whatsapp.groupPolicy allowlist
openclaw config validate

groupPolicy: "allowlist" allein gibt noch keine Gruppe frei. Konfiguriere Gruppen und erlaubte Absender erst später explizit.

Persönliche WhatsApp-Nummer

Wenn du deinen persönlichen Account koppelst und dem Agenten über den Chat mit dir selbst schreibst, empfiehlt die aktuelle Dokumentation eine Self-Chat-Baseline. Rufnummern in allowFrom werden im internationalen E.164-Format angegeben, zum Beispiel +491701234567:²

openclaw config set channels.whatsapp.enabled true
openclaw config set channels.whatsapp.dmPolicy allowlist
openclaw config set channels.whatsapp.allowFrom '["+49XXXXXXXXXX"]' --strict-json
openclaw config set channels.whatsapp.selfChatMode true
openclaw config set channels.whatsapp.groupPolicy allowlist
openclaw config validate
openclaw config get channels.whatsapp --json

Verwende keine erfundene oder verkürzte Nummer.

QR-Code scannen

Starte den dokumentierten Login-Flow:

openclaw channels login --channel whatsapp

Öffne auf dem Smartphone WhatsApp und gehe zu Verlinkte Geräte. Scanne den QR-Code aus dem Terminal. QR-Codes laufen ab; auf einem entfernten oder headless betriebenen Host brauchst du daher eine direkte, zeitnahe Möglichkeit, den aktuellen Code zu sehen.²

Prüfe anschließend den Channel:

openclaw channels status
openclaw logs --follow

Bei einer dedizierten Nummer mit Pairing sendest du nun von deinem persönlichen Account eine Nachricht an die gekoppelte Nummer. Genehmige den erzeugten Code:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE> --notify

Starte danach den bestehenden Gateway-Dienst neu und sende eine weitere Testnachricht.

WhatsApp-Gruppen erst später freigeben

Auch bei WhatsApp sind Gruppenzulassung und Absenderautorisierung getrennte Prüfungen. channels.whatsapp.groups bestimmt die zugelassenen Gruppen. groupPolicy und groupAllowFrom kontrollieren die Absender innerhalb dieser Gruppen.²

WhatsApp-Gruppen verwenden Gruppen-JIDs und nicht einfach die Rufnummer eines Mitglieds. Übernimm deshalb nur IDs, die du aus der aktuellen OpenClaw-Dokumentation oder den Gateway-Logs eindeutig ermittelt hast. Eine Wildcard unter groups solltest du für private Installationen vermeiden.

Was ist mit der offiziellen WhatsApp Business API?

Die hier verwendete OpenClaw-Integration basiert auf WhatsApp Web und Baileys. Aus dieser Anleitung lässt sich keine Konfiguration für Metas WhatsApp Business Platform ableiten.²

Nutze einen Business-API-Weg nur, wenn deine konkrete OpenClaw-Version dafür einen ausdrücklich dokumentierten Channel oder ein passendes Plugin bereitstellt. Beliebige Cloud-API-Felder in channels.whatsapp einzutragen wäre keine funktionierende Alternative.

Fehlerbehebung

Wenn Telegram nicht reagiert, prüfe in dieser Reihenfolge:

1. Läuft der Gateway?
2. Meldet openclaw config validate einen Fehler?
3. Ist das Bot-Token für den Gateway-Prozess erreichbar?
4. Zeigt openclaw channels status den Telegram-Account als aktiv?
5. Meldet openclaw logs --follow einen Auth- oder Polling-Fehler?
6. Wartet unter openclaw pairing list telegram eine Anfrage?
7. Ist die Telegram-User-ID korrekt in allowFrom oder groupAllowFrom eingetragen?
8. Ist die Gruppe unter channels.telegram.groups zugelassen?
9. Verlangt requireMention eine ausdrückliche Erwähnung?

Ein HTTP-401-Fehler bei getMe deutet auf ein ungültiges Bot-Token hin. Ein dauerhafter getUpdates-Konflikt mit Status 409 spricht meist für einen zweiten Poller mit demselben Token.¹

Wenn WhatsApp nicht reagiert, prüfe:

1. Ist @openclaw/whatsapp installiert?
2. Zeigt openclaw channels status den Account als verlinkt?
3. Ist das Gerät in WhatsApp weiterhin unter Verlinkte Geräte sichtbar?
4. Hat die verwendete Nummer das korrekte E.164-Format?
5. Wartet unter openclaw pairing list whatsapp eine Anfrage?
6. Blockieren groupPolicy, groupAllowFrom oder groups die Nachricht?
7. Zeigt openclaw logs --follow einen Login- oder Verbindungsfehler?

Falls die Session nicht mehr gültig ist, starte den QR-Login erneut:

openclaw channels login --channel whatsapp

Sicherheitsregeln für beide Messenger

• Speichere Tokens, WhatsApp-Sessions und Auth-Verzeichnisse niemals im Git-Repository.
• Starte mit Pairing oder einer expliziten Allowlist, nicht mit dmPolicy: "open".
• Verwende allowFrom: ["*"] nur für absichtlich öffentliche Bots mit stark eingeschränkten Tools.
• Behandle DM-Pairing und Gruppenautorisierung als getrennte Freigaben.
• Erlaube Gruppen einzeln und aktiviere zunächst requireMention.
• Entferne verlorene oder nicht mehr verwendete verlinkte Geräte.
• Prüfe Logs auf unbekannte Absender, unerwartete Pairing-Anfragen und wiederholte Auth-Fehler.

Der sichere Abschluss

Telegram ist über BotFather, Bot-Token und DM-Pairing schnell eingerichtet. Für einen privaten Ein-Betreiber-Bot ist eine numerische Allowlist langfristig noch eindeutiger. Gruppen benötigen unabhängig davon eigene Gruppen- und Absenderregeln.

WhatsApp wird als verlinktes Gerät über das externe OpenClaw-Plugin gekoppelt. Eine dedizierte Nummer kann mit Pairing starten; für den persönlichen Account ist eine Allowlist mit selfChatMode die passendere Baseline. In beiden Fällen gilt: erst Direktnachrichten absichern und testen, dann einzelne Gruppen zulassen.

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. Telegram-Doku: Bots, https://core.telegram.org/bots ↩ ↩²