Telegram Bot API Integration einrichten

Bots in bestehende Workflows zu integrieren, kann nerven. Oft hängst du ewig an der Webhook-Konfiguration oder wunderst dich, warum Nachrichten im Gateway einfach nicht ankommen. Du willst eine Lösung, die ohne kompliziertes Setup direkt funktioniert.

Wenn du keine Lust auf ständiges Debugging von Verbindungsfehlern hast, ist der Long-Polling-Modus von grammY ideal. Er ist der Standard und spart dir das Hantieren mit Zertifikaten für Webhooks, solange du noch in der Entwicklung bist oder eine einfache Lösung suchst.

Voraussetzungen

Telegram Account mit Zugriff auf @BotFather
Eine laufende Instanz deines Gateways (openclaw)

Schnellstart

In weniger als fünf Minuten ist dein Bot einsatzbereit. Folge diesen Schritten:

1. Bot-Token erstellen

Öffne Telegram und starte einen Chat mit @BotFather. Achte darauf, dass der Handle exakt @BotFather lautet. Sende den Befehl /newbot, folge den Anweisungen und speichere das Token sicher ab.

2. Konfiguration anpassen

Trage dein Token und die DM-Policy in deine Konfiguration ein. Du kannst das Token auch als Environment Variable TELEGRAM_BOT_TOKEN hinterlegen (gilt nur für den Default-Account).

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

3. Gateway starten und Pairing durchführen

Starte das Gateway und autorisiere die erste DM. Pairing-Codes sind für 1 Stunde gültig.

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

4. Gruppen konfigurieren

Füge den Bot zu deiner Gruppe hinzu. Passe danach channels.telegram.groups und die groupPolicy in deiner Config an, damit sie zu deinem Zugriffsmodell passen.

Hinweis zur Token-Auflösung: Die Konfigurationswerte haben Vorrang vor den Env-Fallbacks. TELEGRAM_BOT_TOKEN wird nur für den Standard-Account genutzt.

Fehlerbehebung

Falls dein Bot keine Nachrichten empfängt oder in Gruppen nicht reagiert, liegen meistens die Telegram-internen Privatsphäre-Einstellungen vor.

Privacy Mode: Standardmäßig ist der Privacy Mode aktiv. Der Bot sieht dann nicht alle Nachrichten in Gruppen. Nutze /setprivacy beim @BotFather, um das zu ändern, oder mache den Bot zum Gruppen-Admin.
Aktualisierung erzwingen: Wenn du den Privacy Mode änderst, musst du den Bot aus der Gruppe entfernen und neu hinzufügen, damit Telegram die Änderungen übernimmt.
Admin-Status: Admin-Bots erhalten immer alle Nachrichten. Das ist die beste Wahl für Bots, die permanent im Hintergrund aktiv sein sollen.
BotFather Toggles: Nutze /setjoingroups, um zu steuern, ob dein Bot überhaupt zu Gruppen hinzugefügt werden darf.

Hast du spezifische Fragen zu deinem Setup? Nutze den AI Setup Assistant für direkte Hilfe.

Nächste Schritte

---
title: "Access control und Aktivierung"
description: "So konfigurierst du den Zugriff auf deinen Telegram Bot und steuerst das Antwortverhalten in Gruppen."
---

Es ist immer das Gleiche: Kaum ist dein Bot online, klopfen die ersten unerwünschten Nutzer an. Ohne die richtige Absicherung wird dein Log schnell unübersichtlich und dein Bot antwortet Accounts, die er eigentlich ignorieren sollte. Eine solide Zugriffskontrolle ist kein Luxus, sondern die Basis für jedes stabile Projekt.

Wenn du die Kontrolle behalten willst, wer deine API-Ressourcen verbraucht, musst du die Policies deines Gateways präzise definieren. Hier erfährst du, wie du DMs und Gruppen-Interaktionen für Telegram richtig konfigurierst.

## Voraussetzungen

- Einen Telegram Bot und den zugehörigen Token.
- Eine laufende Instanz mit Zugriff auf die `openclaw` CLI.
- Deine Konfigurationsdatei (JSON5).

## Schnellstart

In fünf Minuten zu einem sicheren Setup:

1.  **DM Policy festlegen**: Setze `channels.telegram.dmPolicy` auf `pairing` (Standard), um nur autorisierte Chats zuzulassen.
2.  **ID herausfinden**: Sende deinem Bot eine Nachricht und führe `openclaw logs --follow` aus. Kopiere die `from.id`.
3.  **Allowlist füllen**: Trage deine ID in `channels.telegram.allowFrom` ein.
4.  **Gruppen-Zugriff**: Definiere in `channels.telegram.groups` explizit die IDs der erlaubten Gruppen.

## Access Control für DMs

Die Option `channels.telegram.dmPolicy` steuert den Zugriff auf Direct Messages. Du hast folgende Möglichkeiten:

- `pairing` (Standard): Erfordert einen Pairing-Prozess.
- `allowlist`: Nur IDs in der Liste dürfen kommunizieren.
- `open`: Jeder kann schreiben (erfordert `allowFrom: ["*"]`).
- `disabled`: DMs sind komplett deaktiviert.

Für `channels.telegram.allowFrom` kannst du numerische IDs oder Usernames nutzen. Präfixe wie `telegram:` oder `tg:` werden akzeptiert und automatisch normalisiert.

### Deine Telegram User ID finden

Ich empfehle die sicherere Methode über die eigenen Logs, statt Third-Party-Bots zu nutzen:

1. Schicke deinem Bot eine DM.
2. Starte den Log-Stream: `openclaw logs --follow`.
3. Suche nach dem Wert `from.id`.

Alternativ nutzt du die offizielle Bot API:

```bash
curl "https://api.telegram.org/bot\<bot_token\>/getUpdates"

Falls dir Privatsphäre weniger wichtig ist, helfen Bots wie @userinfobot oder @getidsbot.

Group Policy und Allowlists

Bei Gruppen gibt es zwei unabhängige Steuerungselemente:

Erlaubte Gruppen (channels.telegram.groups): Wenn nichts konfiguriert ist, sind alle Gruppen erlaubt. Sobald du IDs oder "*" einträgst, fungiert dies als Allowlist.
Erlaubte Absender (channels.telegram.groupPolicy): Hier wählst du zwischen open, allowlist (Standard) oder disabled.

Falls groupAllowFrom nicht gesetzt ist, nutzt Telegram automatisch allowFrom als Fallback.

Hier ist ein Beispiel, wie du jedes Mitglied in einer spezifischen Gruppe zulässt:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Mention Behavior

Standardmäßig reagiert der Bot in Gruppen nur, wenn er explizit erwähnt wird. Das kann über ein natives @botusername Mention geschehen oder über definierte Patterns in:

agents.list[].groupChat.mentionPatterns
messages.groupChat.mentionPatterns

Du kannst das Verhalten zur Laufzeit mit Session-Commands umschalten:

/activation always
/activation mention

Diese Befehle ändern nur den aktuellen Session-State. Für eine dauerhafte Änderung musst du die Konfiguration anpassen:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

Die Group Chat ID findest du ebenfalls über openclaw logs --follow (suche nach chat.id), via getUpdates oder indem du eine Nachricht aus der Gruppe an @userinfobot weiterleitest.

Fehlerbehebung

Bot antwortet in der Gruppe nicht? Prüfe, ob requireMention auf true steht. Falls ja, musst du den Bot mit seinem Namen triggern oder das Flag in der Konfiguration auf false setzen.

Zugriff verweigert trotz Eintrag in der Liste? Stelle sicher, dass die IDs korrekt sind. Nutze openclaw logs --follow, um die eingehenden IDs in Echtzeit zu sehen und mit deiner Config abzugleichen.

AI Setup Assistant

Nächste Schritte

Bot-Routing und State-Management können sich oft wie ein Ratespiel anfühlen. Nachrichten landen im falschen Thread oder der Kontext geht verloren, wenn man nicht genau weiß, wie die Runtime unter der Haube arbeitet.

Wenn du verstehen willst, wie Nachrichten fließen und wie die Isolation von Gruppen und Themen funktioniert, bist du hier richtig. Ich empfehle dir, dieses Verhalten als Grundlage für deine Architektur zu nehmen, damit dein Bot stabil skaliert.

## Voraussetzungen

Basierend auf der Dokumentation benötigst du:
- Einen aktiven Gateway process
- Eine konfigurierte Telegram Bot API Integration
- Zugriff auf die `agents.defaults.maxConcurrent` Einstellungen

## Schnellstart

Hier ist der Ablauf, wie die Runtime Nachrichten verarbeitet und isoliert. Das System folgt einem klaren Pfad, damit keine Nachrichten verloren gehen.

### 1. Ownership und Routing
Der Gateway process besitzt Telegram vollständig. Das Routing ist dabei strikt deterministisch: Wenn eine Nachricht über Telegram reinkommt, geht die Antwort automatisch an Telegram zurück. Das Modell wählt keine Kanäle selbstständig aus, was für Vorhersehbarkeit sorgt.

### 2. Normalisierung von Nachrichten
Eingehende Nachrichten werden in einen shared channel envelope umgewandelt. Dabei werden zwei wichtige Dinge sichergestellt:
- Reply metadata bleiben erhalten.
- Medien werden durch media placeholders ersetzt.

### 3. Isolation von Sessions
Damit sich Gespräche nicht vermischen, nutzt das System eine klare Trennung:
- **Group sessions**: Diese sind durch die group ID isoliert.
- **Forum topics**: Hier wird `:topic:<threadId>` angehängt, um Themen sauber getrennt zu halten.

### 4. DMs und Concurrency
Bei DMs können Nachrichten eine `message_thread_id` enthalten. OpenClaw nutzt dafür thread-aware session keys und behält die ID für Antworten bei. Das Long polling wird über den grammY runner abgewickelt, wobei das Sequencing pro Chat oder Thread erfolgt. Die Concurrency steuerst du global über `agents.defaults.maxConcurrent`.

## Fehlerbehebung

### Read-Receipts funktionieren nicht
Falls du versuchst, Lesebestätigungen zu senden: Die Telegram Bot API unterstützt keine read-receipts. Der Parameter `sendReadReceipts` wird einfach ignoriert und hat keine Auswirkung.

### Nachrichten landen im falschen Kontext
Prüfe, ob die `message_thread_id` korrekt übergeben wird. OpenClaw verlässt sich darauf, um die thread-aware session keys korrekt zuzuweisen. Ohne diese ID kann die Isolation für Forum topics oder spezifische Threads nicht garantiert werden.

---

Du hast spezifische Fragen zu deiner Konfiguration? Frag den [AI Setup Assistant](/docs/).

## Nächste Schritte

- [Gateway Configuration Reference](/docs/gateway/)
- [Message Envelope Schema](/docs/)
- [Agent Concurrency Settings](/docs/)
- [Telegram Bot API Limits](/docs/)

Kennst du das? Du baust einen Bot und die Interaktion fühlt sich einfach hölzern an. Der User schickt eine Nachricht, und dann passiert erst mal gar nichts, bis Sekunden später ein riesiger Textblock erscheint. Oder du versuchst, spezielle Features wie Forum-Topics oder Sticker zu nutzen, und merkst, dass die meisten Frameworks dich hier im Regen stehen lassen.

OpenClaw ist anders. Wir haben Telegram-native Features direkt eingebaut, damit sich dein Bot wie ein echter Power-User verhält. In diesem Guide zeige ich dir, wie du die API richtig nutzt und das Beste aus deinem Gateway herusholst.

## Voraussetzungen

Bevor du loslegst, stelle sicher, dass deine Umgebung bereit ist. Laut Dokumentation brauchst du:

- Eine aktive OpenClaw-Instanz.
- Für **Draft Streaming**: `channels.telegram.streamMode` darf nicht auf `"off"` stehen (Standard ist `"partial"`).
- Für **Forum-Features**: Deine Bot-Topics müssen aktiviert sein (`getMe().has_topics_enabled`).
- Für **Webhooks**: Einen öffentlichen Endpoint und eine `webhookSecret`.
- Für **Device Pairing**: Das installierte `device-pair` Plugin.

## Schnellstart

In 5 Minuten zum funktionsfähigen Telegram-Setup. So startest du am schnellsten:

1. **Commands registrieren**: Füge deine eigenen Befehle in der Config hinzu, damit sie im Telegram-Menü erscheinen.

```json
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

Nachricht senden: Nutze das CLI, um sofort zu testen, ob die Verbindung steht.

openclaw message send --channel telegram --target @dein_nutzername --message "hi"

Feature Deep Dive

Draft Streaming (Echtzeit-Gefühl)

Niemand wartet gerne. Mit sendMessageDraft zeigt OpenClaw dem Nutzer schon während der Generierung, dass der Bot arbeitet. Das funktioniert aktuell nur in DMs (Private Chats).

Es gibt drei Modi für channels.telegram.streamMode:

off: Kein Streaming.
partial: Häufige Updates, während der Text generiert wird.
block: Updates in Chunks (konfigurierbar über draftChunk).

Wenn du lieber echte Nachrichten statt Draft-Updates willst, setze channels.telegram.blockStreaming: true. Ein cooles Detail: Mit /reasoning stream wird der Denkprozess im Draft-Bereich angezeigt, aber die finale Antwort enthält nur das Ergebnis.

Formatting und HTML

OpenClaw nutzt standardmäßig parse_mode: "HTML". Markdown-ähnlicher Text wird automatisch in sicheres HTML umgewandelt. Falls Telegram das HTML ablehnt, gibt es einen Fallback auf Plain Text – so geht keine Nachricht verloren. Link-Previews sind standardmäßig an, können aber über channels.telegram.linkPreview: false abgeschaltet werden.

Inline Buttons und Interaktionen

Buttons machen die Bedienung intuitiver. Du kannst den Scope für Inline-Keyboards genau festlegen (off, dm, group, all oder allowlist).

So sieht eine Action mit Buttons aus:

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Wähle eine Option:",
  buttons: [
    [
      { text: "Ja", callback_data: "yes" },
      { text: "Nein", callback_data: "no" },
    ],
    [{ text: "Abbrechen", callback_data: "cancel" }],
  ],
}

Klicks auf diese Buttons kommen beim Agent einfach als Text an: callback_data: <value>.

Forum Topics und Gruppen

In Forum-Supergroups nutzt OpenClaw intelligente Session-Keys, die die Topic-ID beinhalten (:topic:<threadId>). Antworten landen so immer im richtigen Thread.

Wichtig: Das “General”-Topic (ID 1) ist ein Sonderfall. Telegram erlaubt hier kein explizites Mitsenden der message_thread_id bei Nachrichten, aber OpenClaw regelt das im Hintergrund für dich.

Audio, Video und Sticker

OpenClaw unterscheidet zwischen Dateien und nativen Formaten:

Audio: Nutze [[audio_as_voice]] im Text, um eine Sprachnachricht statt einer Audiodatei zu senden.
Video: Video-Notes werden unterstützt, erlauben aber keine Captions.
Sticker: Eingehende statische WEBP-Sticker werden verarbeitet. Animierte (TGS) oder Video-Sticker (WEBM) werden übersprungen.

Aktivierung von Sticker-Actions:

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

Webhook vs. Long Polling

Standardmäßig nutzt OpenClaw Long Polling. Für produktive Umgebungen empfehle ich den Webhook-Modus. Setze dafür channels.telegram.webhookUrl und channels.telegram.webhookSecret. Der lokale Listener bindet sich standardmäßig an 0.0.0.0:8787.

Fehlerbehebung

Hier sind Lösungen für Probleme, die in der Dokumentation beschrieben werden:

setMyCommands failed: Das bedeutet meistens, dass die Verbindung zu api.telegram.org blockiert ist. Prüfe dein DNS und deine HTTPS-Ausgangsregeln.
Fehlende Topic-Antworten: Telegram lehnt sendMessage ab, wenn thread_id=1 explizit gesetzt ist. OpenClaw versucht dies zu umgehen, aber prüfe im Zweifel deine Topic-Konfiguration.
Sticker werden nicht angezeigt: Denke daran, dass TGS und WEBM Formate aktuell übersprungen werden. Nur statische WEBP-Sticker landen im Cache unter ~/.openclaw/telegram/sticker-cache.json.
Reaktionen in Foren: Telegram liefert keine Thread-IDs bei Reaktionen mit. Diese werden daher immer in das General-Topic (:topic:1) geroutet.

AI Setup Assistant

Nächste Schritte

Erfahre mehr über das Pairing von Geräten.
Details zu Reaktionen findest du unter /tools/reactions.

Du hast alles nach Anleitung konfiguriert, aber dein Bot reagiert einfach nicht? Es ist frustrierend, wenn die API-Verbindung steht, aber die Nachrichten im Gruppenchat im Nichts verschwinden. Oft liegt es an einer versteckten Einstellung im BotFather oder einer fehlenden Berechtigung in der Config.

Meistens sind es Kleinigkeiten wie der Telegram Privacy Mode oder DNS-Probleme, die den Workflow unterbrechen. In diesem Guide zeige ich dir, wie du die Ursache schnell findest und behebst, damit dein Gateway stabil läuft.

Voraussetzungen

Um die Fehlerbehebung durchzuführen, benötigst du Zugriff auf folgende Ressourcen:

Zugriff auf deinen Telegram Bot über den BotFather
Die installierte CLI von Openclaw
Zugriff auf deine Konfigurationsdatei (z. B. config.yaml)

Quick Start (5-Minuten-Check)

Wenn es schnell gehen muss, folge diesen Schritten, um die häufigsten Fehlerquellen auszuschließen:

Logs prüfen: Starte den Live-Log-Stream mit openclaw logs --follow, um zu sehen, ob Nachrichten ignoriert werden.
Status abfragen: Nutze openclaw channels status, um zu sehen, ob die Konfiguration unvorgesehene Lücken bei Gruppen-Nachrichten aufweist.
Session testen: Sende den Befehl /activation always direkt an den Bot, um zu prüfen, ob die Session-Logik aktiv ist.

Fehlerbehebung

Hier findest du Lösungen für spezifische Probleme, die bei der Integration von Telegram auftreten können.

Bot antwortet nicht auf Nachrichten ohne Erwähnung (Mentions)

Wenn dein Bot nur reagiert, wenn er direkt mit @botname angesprochen wird, liegt das meist am Privacy Mode von Telegram.

Falls requireMention=false eingestellt ist, muss der Telegram Privacy Mode deaktiviert sein.
- Gehe zum BotFather: /setprivacy -> Auf Disable setzen.
- Entferne den Bot aus der Gruppe und füge ihn neu hinzu.
openclaw channels status gibt eine Warnung aus, wenn die Config Nachrichten ohne Erwähnung erwartet, der Bot aber eingeschränkt ist.
Nutze openclaw channels status --probe, um explizite numerische Group-IDs zu prüfen. Beachte: Wildcards ("*") können nicht per Probe geprüft werden.

Bot sieht überhaupt keine Gruppen-Nachrichten

Falls der Bot komplett stumm bleibt, obwohl er Mitglied der Gruppe ist:

Wenn channels.telegram.groups definiert ist, muss die Gruppe in der Liste stehen oder ein "*" enthalten sein.
Verifiziere, dass der Bot tatsächlich Mitglied der Gruppe ist.
Prüfe die Logs mit openclaw logs --follow, um nach “skip reasons” (Gründen für das Überspringen) zu suchen.

Commands funktionieren nur teilweise oder gar nicht

Befehle unterliegen speziellen Autorisierungsregeln:

Autorisiere deine Identität als Absender (Pairing oder via allowFrom).
Die Autorisierung für Commands gilt auch dann, wenn die groupPolicy auf open steht.
Falls setMyCommands failed im Log erscheint, deutet dies meist auf DNS- oder HTTPS-Erreichbarkeitsprobleme zu api.telegram.org hin.

Polling oder Netzwerk-Instabilität

Netzwerkfehler können verschiedene Ursachen im Stack haben:

Node 22+: Die Verwendung von Node 22 oder höher in Kombination mit Custom Fetch/Proxy-Setups kann zu sofortigen Abbrüchen führen, wenn AbortSignal-Typen nicht übereinstimmen.
IPv6-Probleme: Manche Hosts lösen api.telegram.org zuerst via IPv6 auf. Wenn dein Server kein funktionierendes IPv6-Egress hat, kommt es zu sporadischen Fehlern.
Validiere deine DNS-Antworten mit diesen Befehlen:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

Weitere Hilfe findest du unter: Channel troubleshooting.

Telegram config reference pointers

Nutze diese Felder in deiner Konfiguration, um das Verhalten deines Gateways präzise zu steuern.

Haupt-Referenz:

Configuration reference - Telegram

Wichtige Konfigurationsfelder:

Startup/Auth: enabled, botToken, tokenFile, accounts.*
Access Control: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*
Command/Menu: commands.native, customCommands
Threading/Replies: replyToMode
Streaming: streamMode, draftChunk, blockStreaming
Formatting/Delivery: textChunkLimit, chunkMode, linkPreview, responsePrefix
Media/Network: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
Webhook: webhookUrl, webhookSecret, webhookPath
Actions/Capabilities: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
Reactions: reactionNotifications, reactionLevel
Writes/History: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

Du suchst nach einer spezifischen Lösung für dein Setup? Frag den AI Setup Assistant.

Nächste Schritte

Pairing – So verbindest du deine Accounts.
Channel routing – Nachrichtenflüsse definieren.
Troubleshooting – Allgemeine Fehlerbehebung.

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.