OpenClaw Telegram Kanal
Messaging
Einfach
Verbinden Sie OpenClaw mit Telegram über das grammY Bot API-Framework. Erstellen Sie einen Telegram-Bot über @BotFather, holen Sie sich den Token, und Ihr KI-Assistent ist in wenigen Minuten auf Telegram aktiv. Verwendet standardmäßig Long-Polling mit optionalem Webhook-Modus. Einer der am einfachsten einzurichtenden Kanäle mit umfangreichen Funktionen wie Inline-Buttons, Sticker, Reaktionen und Gruppenunterstützung.
Kurzinfo
SchwierigkeitsgradEinfach
KategorieMessaging
Unterstützte Funktionen6 / 6
Telegram Unterstützte Funktionen
Textnachrichten
Unterstützt
Medien & Dateien
Unterstützt
Reaktionen
Unterstützt
Threads
Unterstützt
Sprachnachrichten
Unterstützt
Gruppenchat
Unterstützt
Telegram Voraussetzungen
- Ein Telegram-Konto
- Ein Bot-Token von @BotFather (senden Sie /newbot an @BotFather)
- OpenClaw Gateway läuft und ist konfiguriert
- Node.js 18+ auf Ihrem Server installiert
Telegram Schnelleinrichtung
1
Bot mit @BotFather erstellen
Öffnen Sie Telegram, suchen Sie nach @BotFather und senden Sie /newbot. Folgen Sie den Anweisungen, um Ihren Bot zu benennen und den API-Token zu erhalten. Bewahren Sie diesen Token sicher auf — Sie benötigen ihn für die Konfiguration.
2
Telegram-Kanalkonfiguration hinzufügen
Fügen Sie die Telegram-Kanalkonfiguration in ~/.openclaw/openclaw.json hinzu. Fügen Sie den Bot-Token von @BotFather in das botToken-Feld ein. Setzen Sie die dmPolicy (pairing, allowlist oder open), um zu steuern, wer mit Ihrem Assistenten kommunizieren kann.
3
Gateway starten und testen
Starten Sie den Gateway-Prozess. Suchen Sie Ihren Bot auf Telegram und senden Sie ihm eine Nachricht. Bei Verwendung der Standard-Pairing-Richtlinie genehmigen Sie den Absender mit 'openclaw pairing approve telegram <code>'. OpenClaw sollte über den KI-Assistenten antworten.
Telegram Konfigurationsbeispiel
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram Detaillierte Dokumentation
Architekturübersicht
OpenClaw verbindet sich über das grammY-Framework mit Telegram — eine moderne, TypeScript-first Telegram Bot API-Bibliothek. Der Bot verwendet standardmäßig Long-Polling und fragt regelmäßig die Telegram-Server nach neuen Updates ab. Dies funktioniert sofort ohne zusätzliche Konfiguration.
Alternativ können Sie für Produktionsbereitstellungen in den Webhook-Modus wechseln. Im Webhook-Modus sendet Telegram Updates direkt an Ihren Server-Endpunkt — effizienter und mit geringerer Latenz.
Long-Polling funktioniert hinter NATs und Firewalls ohne Konfiguration. Der Webhook-Modus erfordert einen öffentlich zugänglichen HTTPS-Endpunkt.
Speichern Sie Ihren Bot-Token über die Umgebungsvariable TELEGRAM_BOT_TOKEN oder in Ihrer Konfiguration unter channels.telegram.botToken.
Bot mit @BotFather erstellen
BotFather ist das offizielle Telegram-Tool zur Bot-Erstellung und -Verwaltung. Schritte:
1. Telegram öffnen und @BotFather suchen
2. /newbot senden, um den Erstellungsprozess zu starten
3. Anzeigenamen wählen (z.B. "Mein KI-Assistent")
4. Benutzernamen mit 'bot' am Ende wählen (z.B. "mein_ki_assistent_bot")
5. BotFather gibt Ihnen einen API-Token — sicher aufbewahren
Nach der Erstellung können Sie mit BotFather-Befehlen weiter anpassen:
• /setdescription — Profilbeschreibung festlegen
• /setabouttext — "Über"-Text festlegen
• /setuserpic — Profilbild hochladen
• /setprivacy — Datenschutzmodus für Gruppennachrichten umschalten
Halten Sie Ihren Token geheim. Jeder mit dem Token kann Ihren Bot steuern. Bei Kompromittierung verwenden Sie /revoke in BotFather für einen neuen Token.
DM-Richtlinien
DM-Richtlinien (Direktnachrichten) steuern, wer mit Ihrem KI-Assistenten im Privatchat interagieren kann. OpenClaw unterstützt drei Richtlinien:
• pairing (Standard) — Neue Benutzer müssen einen Kopplungsvorgang durchlaufen. Sie senden eine Nachricht, erhalten einen Kopplungscode (1 Stunde gültig) und Sie genehmigen oder lehnen über CLI ab.
• allowlist — Nur numerische Benutzer-IDs in allowFrom können den Bot kontaktieren. Andere werden stillschweigend ignoriert.
• open — Jeder, der dem Bot eine Nachricht sendet, erhält eine Antwort. In Produktion mit Vorsicht verwenden.
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}Um die numerische Telegram-ID eines Benutzers zu finden, verwenden Sie @userinfobot oder überprüfen Sie die Gateway-Logs beim Nachrichteneingang.
Gruppenchat-Verwaltung
OpenClaw unterstützt Telegram-Gruppenchats mit flexibler Zugriffskontrolle über zwei unabhängige Mechanismen:
1. Gruppen-Whitelist — Alle Gruppen oder nur die in channels.telegram.groups gelisteten.
2. Gruppenrichtlinie — Absenderberechtigungen steuern:
• open — Jedes Gruppenmitglied kann den Bot auslösen
• allowlist — Nur genehmigte Absender
• disabled — Gruppennachrichten werden ignoriert
Standardmäßig erfordert der Bot @Erwähnung in Gruppen. Sie können dies ändern:
• /activation always Befehl (nur Sitzung)
• requireMention: false in der Konfiguration für dauerhafte Wirkung
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}Bei Forum-Gruppen (Themen) isoliert OpenClaw jedes Thema per Thread-ID und kann themenspezifische Konfigurationsüberschreibungen anwenden.
Damit der Bot alle Gruppennachrichten ohne Admin-Status sieht, deaktivieren Sie den Datenschutzmodus in BotFather (/setprivacy), entfernen Sie den Bot aus der Gruppe und fügen Sie ihn wieder hinzu.
Nachrichtenformatierung und Streaming
OpenClaw bietet verschiedene Formatierungs- und Zustellungsoptionen:
Formatierung: Ausgehender Text verwendet Telegrams HTML-Parser mit automatischer Markdown-Konvertierung. Bei fehlgeschlagenem HTML-Parsing wird als Klartext wiederholt.
Streaming: Entwurfsblasen unterstützen partielles Antwort-Streaming in DMs. Zwei Modi:
• partial (Standard) — Progressive Updates einer einzelnen Nachricht
• block — Versand in vollständigen Blöcken
Text wird standardmäßig bei 4.000 Zeichen aufgeteilt (Telegram-Limit). chunkMode: "newline" aktiviert Absatzgrenzen-Aufteilung.
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}Inline-Buttons
OpenClaw unterstützt Telegrams interaktive Inline-Keyboard-Buttons. Bei Aktivierung kann die KI Buttons unter Nachrichten anzeigen. Ein Klick sendet Callback-Daten an den Agenten zurück.
Verfügbare Modi:
• off — Buttons deaktiviert (Standard)
• dm — Nur in Privatchats
• group — Nur in Gruppenchats
• all — Überall aktiviert
• allowlist — Nach Absenderautorisierung eingeschränkt
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}Sticker und Medien
OpenClaw verarbeitet Telegram-Sticker und Mediendateien:
Sticker: Statische Sticker werden heruntergeladen und visuell analysiert. Beschreibungen werden zwischengespeichert. Animierte und Video-Sticker werden übersprungen. Der Agent kann Sticker per Datei-ID senden und im Cache suchen.
Medien: Upload-/Download-Limit standardmäßig 5 MB. Der Bot unterstützt Senden und Empfangen von Bildern, Dokumenten, Audio und Video.
Aktivieren Sie die Sticker-Aktion in der Agenten-Konfiguration, um Sticker per Datei-ID oder Cache-Suche zu senden.
Reaktionen
OpenClaw unterstützt Telegrams Reaktionssystem für Empfang und Versand von Emoji-Reaktionen:
Empfangene Reaktionen erzeugen Systemereignisse im Agenten-Kontext:
• off — Keine Benachrichtigungen
• own — Nur Reaktionen auf Bot-Nachrichten
• all — Alle Reaktionen im Chat
Bot-Reaktionsstufe:
• off — Keine Reaktionen
• ack — Bestätigungsreaktion während Verarbeitung (Standard)
• minimal — Grundreaktionen
• extensive — Voller Emoji-Umfang
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}Befehle und Tools
Native Bot-Befehle (/status, /reset usw.) werden automatisch im Telegram-Befehlsmenü registriert. Benutzerdefinierte Befehle können hinzugefügt werden, funktionieren aber nur als Menüeinträge.
Der Agent unterstützt auch Tool-Aktionen:
• Nachrichten an bestimmte Chats senden
• Mit Emojis reagieren
• Nachrichten löschen
• Auf bestimmte Nachrichten antworten mit [[reply_to:<id>]]
Verwenden Sie [[reply_to_current]] in der Agenten-Antwort, um direkt auf die aktuelle Nachricht zu antworten.
Fügen Sie [[audio_as_voice]] in Antworten ein oder setzen Sie asVoice: true für Sprachnotiz-Format.
Webhook-Modus
Für Produktionsbereitstellungen wird der Webhook-Modus statt Long-Polling empfohlen. Telegram sendet Updates direkt an Ihren Server, was Latenz und Ressourcenverbrauch reduziert.
Setzen Sie webhookUrl und webhookSecret in Ihrer Konfiguration. Der lokale Endpunkt bindet standardmäßig an 0.0.0.0:8787.
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}Beim Wechsel von Polling zu Webhook registriert das Gateway automatisch die Webhook-URL bei Telegram beim Start.
Der Webhook-Modus erfordert einen öffentlich zugänglichen HTTPS-Endpunkt. Stellen Sie sicher, dass Ihr Server ein gültiges SSL-Zertifikat hat.
Telegram Konfigurationsreferenz
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Telegram-Kanal aktivieren oder deaktivieren |
| botToken | string | "" | Telegram Bot API Token von @BotFather. Auch TELEGRAM_BOT_TOKEN Umgebungsvariable möglich |
| dmPolicy | string | "pairing" | DM-Zugriffskontrolle. Optionen: pairing, allowlist, open |
| allowFrom | number[] | [] | Erlaubte Telegram-Benutzer-IDs (bei dmPolicy allowlist) |
| groupPolicy | string | "disabled" | Gruppenrichtlinie. Optionen: disabled, open, allowlist |
| groups | string[] | [] | Liste erlaubter Gruppen-IDs |
| requireMention | boolean | true | @Erwähnung in Gruppen erforderlich |
| streamMode | string | "partial" | Streaming-Modus. Optionen: partial, block |
| chunkMode | string | "split" | Aufteilung langer Antworten. Optionen: split, newline |
| webhookUrl | string | "" | HTTPS-URL für Webhook-Modus |
| webhookSecret | string | "" | Geheimer Token für Webhook-Verifizierung |
| reactionNotifications | string | "off" | Reaktionsbenachrichtigungen. Optionen: off, own, all |
| reactionLevel | string | "ack" | Bot-Reaktionsfähigkeit. Optionen: off, ack, minimal, extensive |
| capabilities.inlineButtons | string | "off" | Inline-Button-Modus. Optionen: off, dm, group, all, allowlist |
| configWrites | boolean | true | Auto-Migration von Chat-IDs bei Supergruppen-Upgrade |
enabled
Type: booleanDefault: true
Telegram-Kanal aktivieren oder deaktivieren
botToken
Type: stringDefault: ""
Telegram Bot API Token von @BotFather. Auch TELEGRAM_BOT_TOKEN Umgebungsvariable möglich
dmPolicy
Type: stringDefault: "pairing"
DM-Zugriffskontrolle. Optionen: pairing, allowlist, open
allowFrom
Type: number[]Default: []
Erlaubte Telegram-Benutzer-IDs (bei dmPolicy allowlist)
groupPolicy
Type: stringDefault: "disabled"
Gruppenrichtlinie. Optionen: disabled, open, allowlist
groups
Type: string[]Default: []
Liste erlaubter Gruppen-IDs
requireMention
Type: booleanDefault: true
@Erwähnung in Gruppen erforderlich
streamMode
Type: stringDefault: "partial"
Streaming-Modus. Optionen: partial, block
chunkMode
Type: stringDefault: "split"
Aufteilung langer Antworten. Optionen: split, newline
webhookUrl
Type: stringDefault: ""
HTTPS-URL für Webhook-Modus
webhookSecret
Type: stringDefault: ""
Geheimer Token für Webhook-Verifizierung
reactionNotifications
Type: stringDefault: "off"
Reaktionsbenachrichtigungen. Optionen: off, own, all
reactionLevel
Type: stringDefault: "ack"
Bot-Reaktionsfähigkeit. Optionen: off, ack, minimal, extensive
capabilities.inlineButtons
Type: stringDefault: "off"
Inline-Button-Modus. Optionen: off, dm, group, all, allowlist
configWrites
Type: booleanDefault: true
Auto-Migration von Chat-IDs bei Supergruppen-Upgrade
Telegram Häufig gestellte Fragen
Telegram Fehlerbehebung
Bot ignoriert Nachrichten ohne Erwähnung in Gruppen
Datenschutzmodus ist standardmäßig aktiviert. Der Bot empfängt nur @Erwähnungen und Slash-Befehle.
Deaktivieren Sie den Datenschutzmodus in BotFather (/setprivacy → Disable). Entfernen und fügen Sie den Bot wieder zur Gruppe hinzu. Setzen Sie requireMention: false in der OpenClaw-Konfiguration.
Bot antwortet auf keine Nachrichten
Falscher Token, Gateway nicht gestartet oder Netzwerkproblem.
Token überprüfen: curl https://api.telegram.org/bot<token>/getMe. Gateway-Logs prüfen. Bei IPv6-Problemen IPv4-Auflösung für api.telegram.org erzwingen.
Webhook empfängt keine Updates
Webhook-URL nicht erreichbar, ungültiges SSL-Zertifikat oder Webhook falsch registriert.
URL-Erreichbarkeit prüfen (curl). SSL-Zertifikat validieren. Status prüfen: curl https://api.telegram.org/bot<token>/getWebhookInfo. Gateway neu starten.
Nachrichten werden abgeschnitten oder falsch aufgeteilt
Telegram hat ein 4.096-Zeichen-Limit. Lange KI-Antworten werden automatisch aufgeteilt.
chunkMode auf 'newline' setzen für Absatzgrenzen-Aufteilung statt hartem Zeichenlimit.