OpenClaw
Integrationen10 Min. Lesezeit

Vollstaendige Anleitung zur OpenClaw Telegram-Integration

Erfahren Sie, wie Sie einen Telegram-Bot erstellen und mit OpenClaw verbinden. Vollstaendiges Tutorial zur Bot-Erstellung, Konfiguration, Befehlen und Gruppenchat-Einrichtung.

O

OpenClaw Guides

Tutorial Authors

Ueberblick

Die Telegram-Integration ermoeglicht es Ihnen, ueber einen dedizierten Telegram-Bot mit OpenClaw zu interagieren. OpenClaw verwendet standardmaessig das grammY-Framework fuer Long-Polling, mit optionaler Webhook-Unterstuetzung fuer Produktionsbereitstellungen.

Voraussetzungen

  • OpenClaw installiert und laufend
  • Ein Telegram-Konto

Schritt 1: Telegram-Bot erstellen

Mit BotFather sprechen

  1. Oeffnen Sie Telegram und suchen Sie nach @BotFather
  2. Starten Sie einen Chat und senden Sie /newbot
  3. Folgen Sie den Anweisungen:
You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

Speichern Sie den Bot-Token — Sie benoetigen ihn im naechsten Schritt.

Datenschutzmodus deaktivieren (Empfohlen fuer Gruppen)

Wenn Sie den Bot in Gruppenchats verwenden moechten, deaktivieren Sie den Datenschutzmodus, damit er alle Nachrichten lesen kann:

/setprivacy
@myopenclaw_bot
Disable

Nach dem Aendern des Datenschutzmodus muessen Sie den Bot aus bestehenden Gruppen entfernen und erneut hinzufuegen, damit die Aenderung wirksam wird. Alternativ koennen Sie den Bot zum Gruppenadministrator befoerdern — Admin-Bots erhalten immer alle Nachrichten.

Schritt 2: OpenClaw konfigurieren

Token-Speicherung

Sie koennen den Bot-Token auf zwei Arten speichern. Die Konfiguration hat Vorrang vor der Umgebungsvariable.

Option A — Umgebungsvariable:

bash
# Hinzufuegen zu ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Option B — Direkt in der Konfiguration:

json5
// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Minimale Konfiguration

Bearbeiten Sie ~/.openclaw/openclaw.json:

json5
{
  channels: {
    telegram: {
      // Token aus der Umgebungsvariable TELEGRAM_BOT_TOKEN oder botToken direkt setzen
    }
  }
}

Das ist alles, was Sie benoetigen — OpenClaw startet automatisch Long-Polling, wenn ein Telegram-Kanal konfiguriert ist.

Schritt 3: Ihren Bot testen

  1. Oeffnen Sie Telegram und suchen Sie nach dem Benutzernamen Ihres Bots
  2. Starten Sie einen Chat mit /start
  3. Senden Sie eine beliebige Nachricht zum Testen

Zugriffskontrolle — DM-Richtlinie

Steuern Sie, wer Ihrem Bot in privaten Chats Nachrichten senden kann, ueber dmPolicy:

| Richtlinie | Verhalten | |------------|-----------| | "pairing" (Standard) | Unbekannte Absender erhalten einen ablaufenden Kopplungscode; Sie genehmigen ihn ueber die CLI | | "allowlist" | Nur Benutzer-IDs / @Benutzernamen in allowFrom koennen Nachrichten senden | | "open" | Jeder kann dem Bot Nachrichten senden | | "disabled" | DMs sind vollstaendig deaktiviert |

Kopplungsmodus (Standard)

Wenn ein neuer Benutzer dem Bot eine Nachricht sendet, erhaelt er einen Kopplungscode. Genehmigen Sie ihn mit:

bash
# Ausstehende Kopplungsanfragen auflisten
openclaw pairing list telegram

# Einen bestimmten Code genehmigen
openclaw pairing approve telegram <CODE>

Kopplungscodes laufen nach 1 Stunde ab.

Allowlist-Modus

json5
{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

Offener Modus

json5
{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

Gruppenchat-Unterstuetzung

Gruppenzugriff aktivieren

Fuegen Sie Gruppen-IDs zum groups-Objekt hinzu. Verwenden Sie "*", um alle Gruppen zuzulassen:

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // bestimmte Gruppe mit Standardwerten
        "-1009876543210": {             // bestimmte Gruppe mit Ueberschreibungen
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

Oder alle Gruppen zulassen:

json5
{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

Gruppenrichtlinie

Steuern Sie, wer innerhalb von Gruppen mit dem Bot interagieren kann:

| Einstellung | Beschreibung | |-------------|--------------| | groupPolicy: "open" | Jedes Gruppenmitglied kann dem Bot Nachrichten senden | | groupPolicy: "allowlist" | Nur Absender in groupAllowFrom koennen interagieren | | groupPolicy: "disabled" | Bot ignoriert alle Gruppennachrichten |

json5
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

Erwaehnung erforderlich

Standardmaessig erfordert der Bot eine @Erwaehnung in Gruppen. Sie koennen dies pro Gruppe aendern:

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // Bot antwortet auf alle Nachrichten
        }
      }
    }
  }
}

Oder verwenden Sie den sitzungsspezifischen Befehl /activation always im Gruppenchat.

Pro-Gruppe-Ueberschreibungen

Jeder Gruppeneintrag unterstuetzt diese Felder:

| Feld | Beschreibung | |------|--------------| | groupPolicy | Ueberschreibt die globale Gruppenrichtlinie | | requireMention | Ob eine @Erwaehnung erforderlich ist | | skills | In dieser Gruppe verfuegbare Skills | | allowFrom | Absender-Allowlist fuer diese Gruppe | | systemPrompt | Benutzerdefinierter System-Prompt fuer diese Gruppe | | enabled | Aktivieren/Deaktivieren fuer diese bestimmte Gruppe |

Nachrichtenformat & Aufteilung

HTML-Parse-Modus

OpenClaw sendet Nachrichten im HTML-Parse-Modus von Telegram (nicht Markdown). Markdown vom LLM wird automatisch in HTML-sichere Tags konvertiert. Wenn Telegram das HTML ablehnt, wird die Nachricht als Klartext erneut gesendet.

Textaufteilung

Lange Nachrichten werden in mehrere Telegram-Nachrichten aufgeteilt:

json5
{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // max. Zeichen pro Nachricht (Standard: 4000)
      chunkMode: "newline"     // "length" (Standard) oder "newline"
    }
  }
}
  • "length" — teilt am Zeichenlimit
  • "newline" — teilt an Absatzgrenzen vor Anwendung des Zeichenlimits

Medienverarbeitung

Maximale Mediendateigroesse

json5
{
  channels: {
    telegram: {
      mediaMaxMb: 5    // max. Dateigroesse in MB (Standard: 5)
    }
  }
}

Sticker

  • Statische Sticker (WEBP) werden durch Vision verarbeitet und dem LLM beschrieben
  • Animierte / Video-Sticker werden uebersprungen
  • Sticker-Beschreibungen werden in ~/.openclaw/telegram/sticker-cache.json zwischengespeichert, um redundante Vision-Aufrufe zu vermeiden

Um dem Bot das Senden von Stickern zu ermoeglichen:

json5
{
  channels: {
    telegram: {
      actions: {
        sticker: true    // Standard: false
      }
    }
  }
}

Verlauf & Kontext

json5
{
  channels: {
    telegram: {
      historyLimit: 50,        // Gruppenkontext (Standard: 50)
      dmHistoryLimit: 100      // DM-Kontext
    }
  }
}

Pro-Benutzer-DM-Ueberschreibung:

json5
{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

Setzen Sie den Wert auf 0, um den Verlauf zu deaktivieren.

Streaming

OpenClaw unterstuetzt entwurfsbasiertes Streaming in privaten Chats (mit aktivierten Forenthemen):

| Einstellung | Beschreibung | |-------------|--------------| | streamMode: "off" | Streaming deaktiviert (Standard) | | streamMode: "partial" | Fortlaufende Aktualisierungen einer Entwurfsnachricht | | streamMode: "block" | Blockweise Aktualisierungen einer Entwurfsnachricht |

Block-Modus-Einstellungen:

json5
{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Webhook-Modus (Produktion)

Fuer Produktionsbereitstellungen verwenden Sie Webhooks anstelle von Long-Polling:

json5
{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // lokaler Pfad, Standard: /telegram-webhook
    }
  }
}

Der Webhook-Listener bindet sich an 0.0.0.0:8787. Wenn webhookUrl gesetzt ist, wechselt OpenClaw automatisch vom Polling- in den Webhook-Modus.

Befehle

Native Befehle

OpenClaw registriert diese Befehle beim Start im Bot-Menue von Telegram:

| Befehl | Beschreibung | |--------|--------------| | /start | Willkommensnachricht | | /status | Bot-Status anzeigen | | /reset | Konversation zuruecksetzen | | /model | Modell anzeigen / wechseln |

Benutzerdefinierte Befehle

Fuegen Sie Menueeintraege ueber die Konfiguration hinzu (nur Menue — sie werden nicht ausgefuehrt, es sei denn, sie werden anderswo behandelt):

json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

Befehlsnamen muessen aus Kleinbuchstaben a-z0-9_ bestehen, 1–32 Zeichen. Ein fuehrender / wird automatisch entfernt. Native Befehle koennen nicht ueberschrieben werden.

Inline-Buttons

Steuern Sie die Verfuegbarkeit von Inline-Buttons:

| Einstellung | Geltungsbereich | |-------------|-----------------| | capabilities.inlineButtons: "off" | Deaktiviert | | capabilities.inlineButtons: "dm" | Nur DMs | | capabilities.inlineButtons: "group" | Nur Gruppen | | capabilities.inlineButtons: "all" | Sowohl DMs als auch Gruppen | | capabilities.inlineButtons: "allowlist" | Beides + Absenderfilterung (Standard) |

Netzwerk & Proxy

json5
{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot-API-Anfrage-Timeout (Standard: 500)
      network: {
        autoSelectFamily: false   // Happy Eyeballs deaktivieren (Standard bei Node 22)
      },
      proxy: "socks5://127.0.0.1:1080"   // SOCKS/HTTP-Proxy fuer die Bot-API
    }
  }
}

Fehlerbehebung

Bot antwortet nicht

  1. Ueberpruefen Sie, ob der Token korrekt ist:
bash
curl "https://api.telegram.org/bot<TOKEN>/getMe"
  1. Pruefen Sie die OpenClaw-Logs:
bash
openclaw logs --follow

Nachrichten kommen in Gruppen nicht an

  • Der Datenschutzmodus muss deaktiviert sein (/setprivacy → Disable) oder der Bot muss Administrator sein
  • Testen Sie mit /activation always (nur fuer die Sitzung); dauerhaft ueber requireMention: false in der Konfiguration

IPv6-Routing-Fehler

Der Bot reagiert moeglicherweise stillschweigend nicht mehr, wenn das IPv6-Routing fehlschlaegt. Pruefen Sie DNS fuer api.telegram.org:

bash
dig api.telegram.org AAAA

Beheben Sie das Problem, indem Sie IPv6-Egress aktivieren oder IPv4 erzwingen:

bash
# Hinzufuegen zu /etc/hosts
149.154.167.220  api.telegram.org

Oder verwenden Sie die Netzwerkkonfiguration:

json5
{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

Long-Polling-Abbrueche (Node 22+)

Node 22 ist strenger mit AbortSignal-Instanzen. Aktualisieren Sie OpenClaw auf die neueste Version oder wechseln Sie zu Node 20 zurueck.

setMyCommands-Fehler

Ausgehende HTTPS/DNS-Verbindungen zu api.telegram.org koennten blockiert sein. Ueberpruefen Sie Ihre Firewall-Regeln.

Best Practices fuer die Sicherheit

  1. Teilen Sie niemals Ihren Bot-Token — widerrufen Sie ihn sofort ueber BotFather, falls er kompromittiert wurde
  2. Verwenden Sie Kopplung oder Allowlist fuer die DM-Zugriffskontrolle
  3. Legen Sie Gruppenrichtlinien fest, um zu steuern, wer in Gruppen interagieren kann
  4. Finden Sie Benutzer-IDs sicher ueber openclaw logs --follow oder den Bot-API-Endpunkt getUpdates — vermeiden Sie Drittanbieter-ID-Bots
  5. Verwenden Sie Webhooks mit einem Secret fuer Produktionsbereitstellungen

Naechste Schritte