Telegram (Bot API)

Telegram-Bot einrichten: Token von @BotFather holen und eintragen. Status: produktionsbereit für Bot-DMs und Gruppen über grammY. Standardmäßig Long-Polling; Webhook optional.

Schnelleinrichtung (Anfänger)

1. Bot bei @BotFather erstellen und Token kopieren.
2. Token setzen:
   • Umgebung: TELEGRAM_BOT_TOKEN=...
   • Oder Konfig: channels.telegram.botToken: "...".
   • Wenn beide gesetzt sind, hat Konfiguration Vorrang (Umgebungs-Fallback nur Standardkonto).
3. Gateway starten.
4. DM-Zugang ist standardmäßig Pairing; Kopplungscode beim ersten Kontakt freigeben.

Minimale Konfiguration:

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

Ziele

• Ein Telegram-Bot-API-Kanal, der dem Gateway gehört.
• Deterministisches Routing: Antworten gehen zurück zu Telegram; das Modell wählt nie Kanäle.
• DMs teilen die Hauptsitzung des Agenten; Gruppen bleiben isoliert (agent:<agentId>:telegram:group:<chatId>).

Einrichtung (schneller Weg)

1) Bot-Token erstellen (BotFather)

1. Telegram öffnen und mit @BotFather chatten.
2. /newbot ausführen, dann den Aufforderungen folgen (Name + Benutzername endend auf bot).
3. Token kopieren und sicher aufbewahren.

Optionale BotFather-Einstellungen:

• /setjoingroups — Bot zu Gruppen hinzufügen erlauben/verweigern.
• /setprivacy — steuern, ob der Bot alle Gruppennachrichten sieht.

2) Token konfigurieren (Umgebung oder Konfiguration)

Beispiel:

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

Umgebungsoption: TELEGRAM_BOT_TOKEN=... (gilt für das Standardkonto). Wenn sowohl Umgebung als auch Konfiguration gesetzt sind, hat Konfiguration Vorrang. Mehrkonten-Unterstützung: nutzen Sie channels.telegram.accounts mit Token pro Konto und optionalem name. Siehe gateway/configuration für das gemeinsame Muster.

3. Gateway starten. Telegram startet, wenn ein Token aufgelöst ist (zuerst Konfiguration, dann Umgebung).
4. DM-Zugang standardmäßig Pairing. Code freigeben, wenn der Bot erstmals kontaktiert wird.
5. Für Gruppen: Bot hinzufügen, Privacy-/Admin-Verhalten festlegen (siehe unten), dann channels.telegram.groups setzen, um Erwähnungs-Steuerung und Zulassen-Listen zu konfigurieren.

Token + Privacy + Berechtigungen (Telegram-Seite)

Token-Erstellung (BotFather)

• /newbot erstellt den Bot und gibt den Token zurück (geheim halten).
• Bei geleaktem Token: über @BotFather widerrufen/neu erzeugen und Konfiguration aktualisieren.

Gruppennachrichten-Sichtbarkeit (Privacy Mode)

Telegram-Bots sind standardmäßig im Privacy Mode, der einschränkt, welche Gruppennachrichten sie erhalten. Wenn Ihr Bot alle Gruppennachrichten sehen muss, haben Sie zwei Optionen:

• Privacy Mode mit /setprivacy deaktivieren oder
• Den Bot als Gruppen-Admin hinzufügen (Admin-Bots erhalten alle Nachrichten).

Hinweis: Beim Umschalten des Privacy Mode verlangt Telegram, den Bot aus jeder Gruppe zu entfernen und wieder hinzuzufügen, damit die Änderung wirkt.

Gruppenberechtigungen (Admin-Rechte)

Admin-Status wird in der Gruppe (Telegram-UI) gesetzt. Admin-Bots erhalten immer alle Gruppennachrichten; nutzen Sie Admin, wenn Sie volle Sichtbarkeit brauchen.

Wie es funktioniert (Verhalten)

• Eingehende Nachrichten werden in das gemeinsame Kanal-Envelope mit Antwortkontext und Medien-Platzhaltern normalisiert.
• Gruppenantworten erfordern standardmäßig eine Erwähnung (native @Erwähnung oder agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns).
• Multi-Agent-Override: pro Agent Muster auf agents.list[].groupChat.mentionPatterns setzen.
• Antworten werden immer an denselben Telegram-Chat zurückgeleitet.
• Long-Polling nutzt grammY-Runner mit Sequenzierung pro Chat; Gesamt-Concurrency ist durch agents.defaults.maxConcurrent begrenzt.
• Die Telegram Bot API unterstützt keine Lesebestätigungen; es gibt keine Option sendReadReceipts.

Formatierung (Telegram HTML)

• Ausgehender Telegram-Text nutzt parse_mode: "HTML" (Telegrams unterstützte Tag-Teilmenge).
• Markdown-ähnliche Eingabe wird in Telegram-sicheres HTML (fett/kursiv/durchgestrichen/Code/Links) gerendert; Blockelemente werden zu Text mit Zeilenumbrüchen/Aufzählungen abgeflacht.
• Rohes HTML von Modellen wird escaped, um Telegram-Parse-Fehler zu vermeiden.
• Wenn Telegram das HTML-Payload ablehnt, versucht OpenClaw dieselbe Nachricht als Klartext erneut.

Befehle (native + benutzerdefiniert)

OpenClaw registriert native Befehle (z. B. /status, /reset, /model) im Telegram-Bot-Menü beim Start. Sie können benutzerdefinierte Befehle über die Konfiguration zum Menü hinzufügen:

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

Fehlerbehebung

• setMyCommands failed in den Logs bedeutet meist, dass ausgehendes HTTPS/DNS zu api.telegram.org blockiert ist.
• Bei sendMessage- oder sendChatAction-Fehlern IPv6-Routing und DNS prüfen.

Weitere Hilfe: Kanal-Fehlerbehebung. Hinweise:

• Benutzerdefinierte Befehle sind nur Menüeinträge; OpenClaw implementiert sie nicht, außer Sie behandeln sie anderswo.
• Befehlsnamen werden normalisiert (führendes / entfernt, kleingeschrieben) und müssen a-z, 0-9, _ (1–32 Zeichen) entsprechen.
• Benutzerdefinierte Befehle können native Befehle nicht überschreiben. Konflikte werden ignoriert und protokolliert.
• Wenn commands.native deaktiviert ist, werden nur benutzerdefinierte Befehle registriert (oder gelöscht, wenn keine).

Limits

• Ausgehender Text wird auf channels.telegram.textChunkLimit (Standard 4000) gechunkt.
• Optionale Zeilenumbruch-Chunking: channels.telegram.chunkMode="newline" setzen, um vor Längen-Chunking an Leerzeilen (Absatzgrenzen) zu teilen.
• Medien-Downloads/-Uploads sind durch channels.telegram.mediaMaxMb (Standard 5) begrenzt.
• Telegram-Bot-API-Anfragen laufen nach channels.telegram.timeoutSeconds (Standard 500 über grammY) ab. Niedriger setzen, um lange Hänger zu vermeiden.
• Gruppen-Kontexthistorie nutzt channels.telegram.historyLimit (oder channels.telegram.accounts.*.historyLimit), Fallback auf messages.groupChat.historyLimit. Setzen Sie 0 zum Deaktivieren (Standard 50).
• DM-Historie kann mit channels.telegram.dmHistoryLimit (Benutzer-Turns) begrenzt werden. Pro-Benutzer-Overrides: channels.telegram.dms["<user_id>"].historyLimit.

Gruppenaktivierungsmodi

Standardmäßig antwortet der Bot nur auf Erwähnungen in Gruppen (@botname oder Muster in agents.list[].groupChat.mentionPatterns). Zum Ändern:

Über Konfiguration (empfohlen)

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }  // always respond in this group
      }
    }
  }
}

Wichtig: Das Setzen von channels.telegram.groups erstellt eine Zulassen-Liste – nur gelistete Gruppen oder "*" werden akzeptiert. Forum-Themen erben die Konfiguration der übergeordneten Gruppe (allowFrom, requireMention, skills, prompts), außer Sie fügen Pro-Thema-Overrides unter channels.telegram.groups.<groupId>.topics.<topicId> hinzu. Um alle Gruppen mit „immer antworten“ zuzulassen:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }  // all groups, always respond
      }
    }
  }
}

Um für alle Gruppen nur bei Erwähnung zu antworten (Standardverhalten):

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }  // or omit groups entirely
      }
    }
  }
}

Über Befehl (Sitzungsebene)

In der Gruppe senden:

• /activation always - auf alle Nachrichten antworten
• /activation mention - Erwähnungen erforderlich (Standard)

Hinweis: Befehle aktualisieren nur den Sitzungszustand. Für dauerhaftes Verhalten über Neustarts hinweg Konfiguration nutzen.

Gruppen-Chat-ID ermitteln

Eine Nachricht aus der Gruppe an @userinfobot oder @getidsbot auf Telegram weiterleiten, um die Chat-ID zu sehen (negative Zahl wie -1001234567890). Tipp: Für Ihre eigene Benutzer-ID dem Bot eine DM schicken – er antwortet mit Ihrer Benutzer-ID (Pairing-Nachricht) – oder /whoami nutzen, sobald Befehle aktiviert sind. Privacy-Hinweis: @userinfobot ist ein Drittanbieter-Bot. Wenn Sie es bevorzugen: Bot zur Gruppe hinzufügen, Nachricht senden und openclaw logs --follow nutzen, um chat.id zu lesen, oder die Bot-API getUpdates nutzen.

Konfig schreibt

Standardmäßig darf Telegram Konfigurationsaktualisierungen schreiben, die durch Kanal-Events oder /config set|unset ausgelöst werden. Das passiert, wenn:

• Eine Gruppe zu einer Supergruppe hochgestuft wird und Telegram migrate_to_chat_id sendet (Chat-ID ändert sich). OpenClaw kann channels.telegram.groups automatisch migrieren.
• Sie /config set oder /config unset in einem Telegram-Chat ausführen (erfordert commands.config: true).

Deaktivieren mit:

{
  channels: { telegram: { configWrites: false } }
}

Themen (Forum-Supergruppen)

Telegram-Forum-Themen enthalten pro Nachricht eine message_thread_id. OpenClaw:

• Hängt :topic:<threadId> an den Telegram-Gruppen-Sitzungsschlüssel an, sodass jedes Thema isoliert ist.
• Sendet Tipp-Indikatoren und antwortet mit message_thread_id, damit Antworten im Thema bleiben.
• Allgemeines Thema (Thread-ID 1) ist speziell: Nachrichtensendungen lassen message_thread_id weg (Telegram lehnt es ab), Tipp-Indikatoren enthalten es aber weiterhin.
• Stellt MessageThreadId + IsForum im Template-Kontext für Routing/Templating bereit.
• Themen-spezifische Konfiguration ist unter channels.telegram.groups.<chatId>.topics.<threadId> verfügbar (skills, allowlists, auto-reply, system prompts, disable).
• Themen-Konfigs erben Gruppeneinstellungen (requireMention, allowlists, skills, prompts, enabled), sofern nicht pro Thema überschrieben.

Private Chats können in einigen Randfällen message_thread_id enthalten. OpenClaw lässt den DM-Sitzungsschlüssel unverändert, nutzt die Thread-ID aber weiterhin für Antworten/Draft-Streaming, wenn vorhanden.

Inline-Buttons

Telegram unterstützt Inline-Tastaturen mit Callback-Buttons.

{
  "channels": {
    "telegram": {
      "capabilities": {
        "inlineButtons": "allowlist"
      }
    }
  }
}

Für Pro-Konto-Konfiguration:

{
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "capabilities": {
            "inlineButtons": "allowlist"
          }
        }
      }
    }
  }
}

Scopes:

• off — Inline-Buttons deaktiviert
• dm — nur DMs (Gruppenziele blockiert)
• group — nur Gruppen (DM-Ziele blockiert)
• all — DMs + Gruppen
• allowlist — DMs + Gruppen, aber nur Absender, die durch allowFrom/groupAllowFrom erlaubt sind (gleiche Regeln wie Steuerungsbefehle)

Standard: allowlist. Legacy: capabilities: ["inlineButtons"] = inlineButtons: "all".

Buttons senden

Message-Tool mit dem Parameter buttons nutzen:

{
  "action": "send",
  "channel": "telegram",
  "to": "123456789",
  "message": "Choose an option:",
  "buttons": [\
    [\
      {"text": "Yes", "callback_data": "yes"},\
      {"text": "No", "callback_data": "no"}\
    ],\
    [\
      {"text": "Cancel", "callback_data": "cancel"}\
    ]\
  ]
}

Wenn ein Benutzer auf einen Button klickt, werden die Callback-Daten als Nachricht im Format callback_data: value an den Agenten zurückgesendet.

Konfigurationsoptionen

Telegram-Funktionen können auf zwei Ebenen konfiguriert werden (Objektform wie oben; Legacy-String-Arrays werden weiter unterstützt):

• channels.telegram.capabilities: Globale Standard-Funktionskonfiguration für alle Telegram-Konten, sofern nicht überschrieben.
• channels.telegram.accounts.<account>.capabilities: Pro-Konto-Funktionen, die die globalen Standardeinstellungen für dieses Konto überschreiben.

Globale Einstellung nutzen, wenn alle Telegram-Bots/Konten gleich agieren sollen. Pro-Konto-Konfiguration nutzen, wenn verschiedene Bots unterschiedliches Verhalten brauchen (z. B. ein Konto nur für DMs, ein anderes in Gruppen erlaubt).

Zugriffskontrolle (DMs + Gruppen)

DM-Zugang

• Standard: channels.telegram.dmPolicy = "pairing". Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie freigegeben sind (Codes laufen nach 1 Stunde ab).
• Freigabe über:
  • openclaw pairing list telegram
  • openclaw pairing approve telegram <CODE>
• Pairing ist der Standard-Token-Austausch für Telegram-DMs. Details: Pairing
• channels.telegram.allowFrom akzeptiert numerische Benutzer-IDs (empfohlen) oder @username-Einträge. Es ist nicht der Bot-Benutzername; nutzen Sie die ID des menschlichen Absenders. Der Assistent akzeptiert @username und löst sie in die numerische ID auf, wenn möglich.

Telegram-Benutzer-ID finden

Sicherer (kein Drittanbieter-Bot):

1. Gateway starten und dem Bot eine DM schicken.
2. openclaw logs --follow ausführen und nach from.id suchen.

Alternative (offizielle Bot-API):

1. Dem Bot eine DM schicken.
2. Updates mit dem Bot-Token abrufen und message.from.id lesen:

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

Drittanbieter (weniger privat):

• @userinfobot oder @getidsbot eine DM schicken und die zurückgegebene Benutzer-ID nutzen.

Gruppenzugang

Zwei unabhängige Steuerungen: 1. Welche Gruppen erlaubt sind (Gruppen-Zulassen-Liste über channels.telegram.groups):

• Keine groups-Konfiguration = alle Gruppen erlaubt
• Mit groups-Konfiguration = nur gelistete Gruppen oder "*" erlaubt
• Beispiel: "groups": { "-1001234567890": {}, "*": {} } erlaubt alle Gruppen

2. Welche Absender erlaubt sind (Absenderfilter über channels.telegram.groupPolicy):

• "open" = alle Absender in erlaubten Gruppen können schreiben
• "allowlist" = nur Absender in channels.telegram.groupAllowFrom können schreiben
• "disabled" = keine Gruppennachrichten akzeptiert Standard ist groupPolicy: "allowlist" (blockiert, außer Sie fügen groupAllowFrom hinzu).

Die meisten Nutzer wollen: groupPolicy: "allowlist" + groupAllowFrom + konkrete Gruppen in channels.telegram.groups gelistet.

Long-Polling vs. Webhook

• Standard: Long-Polling (keine öffentliche URL erforderlich).

• Webhook-Modus: channels.telegram.webhookUrl setzen (optional channels.telegram.webhookSecret + channels.telegram.webhookPath).

  • Der lokale Listener bindet standardmäßig an 0.0.0.0:8787 und bedient POST /telegram-webhook.
  • Bei abweichender öffentlicher URL Reverse-Proxy nutzen und channels.telegram.webhookUrl auf den öffentlichen Endpunkt zeigen.

Antwort-Threading

Telegram unterstützt optionale Thread-Antworten über Tags:

• [[reply_to_current]] — auf die auslösende Nachricht antworten.
• [[reply_to:<id>]] — auf eine bestimmte Nachrichten-ID antworten.

Gesteuert durch channels.telegram.replyToMode:

• first (Standard), all, off.

Sprachnachrichten (Voice vs. Datei)

Telegram unterscheidet Sprachnotizen (runde Blase) von Audiodateien (Metadaten-Karte). OpenClaw nutzt standardmäßig Audiodateien aus Abwärtskompatibilität. Um in Agent-Antworten eine Sprachnotiz-Blase zu erzwingen, dieses Tag irgendwo in der Antwort einfügen:

• [[audio_as_voice]] — Audio als Sprachnotiz statt als Datei senden.

Das Tag wird aus dem ausgelieferten Text entfernt. Andere Kanäle ignorieren dieses Tag. Für Message-Tool-Sendungen asVoice: true mit einer voice-kompatiblen Audio-media-URL setzen (message ist optional, wenn Medien vorhanden):

{
  "action": "send",
  "channel": "telegram",
  "to": "123456789",
  "media": "https://example.com/voice.ogg",
  "asVoice": true
}

Sticker

OpenClaw unterstützt Empfang und Versand von Telegram-Stickern mit intelligenter Zwischenspeicherung.

Sticker empfangen

Wenn ein Benutzer einen Sticker sendet, behandelt OpenClaw ihn je nach Sticker-Typ:

• Statische Sticker (WEBP): Heruntergeladen und per Vision verarbeitet. Der Sticker erscheint als <media:sticker>-Platzhalter im Nachrichteninhalt.
• Animierte Sticker (TGS): Übersprungen (Lottie-Format wird nicht zur Verarbeitung unterstützt).
• Video-Sticker (WEBM): Übersprungen (Videoformat wird nicht zur Verarbeitung unterstützt).

Template-Kontextfeld beim Empfang von Stickern:

• Sticker — Objekt mit:
  • emoji — dem Sticker zugeordnetes Emoji
  • setName — Name des Sticker-Sets
  • fileId — Telegram-Datei-ID (denselben Sticker zurücksenden)
  • fileUniqueId — stabile ID für Cache-Lookup
  • cachedDescription — zwischengespeicherte Vision-Beschreibung, wenn verfügbar

Sticker-Cache

Sticker werden über die KI-Vision-Funktionen verarbeitet, um Beschreibungen zu erzeugen. Da dieselben Sticker oft wiederholt gesendet werden, speichert OpenClaw diese Beschreibungen zwischen, um redundante API-Aufrufe zu vermeiden. Ablauf:

1. Erste Begegnung: Das Sticker-Bild wird zur Vision-Analyse an die KI gesendet. Die KI erzeugt eine Beschreibung (z. B. „Eine Cartoon-Katze winkt enthusiastisch“).
2. Cache-Speicherung: Die Beschreibung wird zusammen mit Sticker-Datei-ID, Emoji und Set-Namen gespeichert.
3. Folge-Begegnungen: Bei erneutem gleichen Sticker wird die gecachte Beschreibung direkt genutzt. Das Bild wird nicht an die KI gesendet.

Cache-Ort: ~/.clawdbot/telegram/sticker-cache.json Cache-Eintragsformat:

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "A cartoon cat waving enthusiastically",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

Vorteile:

• Reduziert API-Kosten durch Vermeidung wiederholter Vision-Aufrufe für denselben Sticker
• Schnellere Antwortzeiten für gecachte Sticker (keine Vision-Verzögerung)
• Ermöglicht Sticker-Suche basierend auf gecachten Beschreibungen

Der Cache wird automatisch beim Empfang von Stickern gefüllt. Keine manuelle Cache-Verwaltung nötig.

Sticker senden

Der Agent kann Sticker mit den Aktionen sticker und sticker-search senden und suchen. Standardmäßig deaktiviert; in der Konfiguration aktivieren:

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

Sticker senden:

{
  "action": "sticker",
  "channel": "telegram",
  "to": "123456789",
  "fileId": "CAACAgIAAxkBAAI..."
}

Parameter:

• fileId (erforderlich) — die Telegram-Datei-ID des Stickers. Von Sticker.fileId beim Empfang oder aus einem sticker-search-Ergebnis.
• replyTo (optional) — Nachrichten-ID für die Antwort.
• threadId (optional) — Nachrichten-Thread-ID für Forum-Themen.

Sticker suchen: Der Agent kann gecachte Sticker nach Beschreibung, Emoji oder Set-Namen durchsuchen:

{
  "action": "sticker-search",
  "channel": "telegram",
  "query": "cat waving",
  "limit": 5
}

Gibt passende Sticker aus dem Cache zurück:

{
  "ok": true,
  "count": 2,
  "stickers": [\
    {\
      "fileId": "CAACAgIAAxkBAAI...",\
      "emoji": "👋",\
      "description": "A cartoon cat waving enthusiastically",\
      "setName": "CoolCats"\
    }\
  ]
}

Die Suche nutzt Fuzzy-Matching über Beschreibungstext, Emoji-Zeichen und Set-Namen. Beispiel mit Threading:

{
  "action": "sticker",
  "channel": "telegram",
  "to": "-1001234567890",
  "fileId": "CAACAgIAAxkBAAI...",
  "replyTo": 42,
  "threadId": 123
}

Streaming (Drafts)

Telegram kann Entwurfs-Blasen streamen, während der Agent eine Antwort erzeugt. OpenClaw nutzt die Bot-API sendMessageDraft (keine echten Nachrichten) und sendet die finale Antwort als normale Nachricht. Anforderungen (Telegram Bot API 9.3+):

• Private Chats mit aktivierten Themen (Forum-Themen-Modus für den Bot).
• Eingehende Nachrichten müssen message_thread_id enthalten (privater Themen-Thread).
• Streaming wird für Gruppen/Supergruppen/Kanäle ignoriert.

Konfiguration:

• channels.telegram.streamMode: "off" | "partial" | "block" (Standard: partial)
  • partial: Entwurfs-Blase mit dem neuesten Streaming-Text aktualisieren.
  • block: Entwurfs-Blase in größeren Blöcken (gechunkt) aktualisieren.
  • off: Draft-Streaming deaktivieren.
• Optional (nur für streamMode: "block"):
  • channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
    • Standard: minChars: 200, maxChars: 800, breakPreference: "paragraph" (begrenzt auf channels.telegram.textChunkLimit).

Hinweis: Draft-Streaming ist getrennt von Block-Streaming (Kanalnachrichten). Block-Streaming ist standardmäßig aus und erfordert channels.telegram.blockStreaming: true, wenn Sie frühe Telegram-Nachrichten statt Draft-Updates wollen. Reasoning-Stream (nur Telegram):

• /reasoning stream streamt Reasoning in die Entwurfs-Blase, während die Antwort erzeugt wird, und sendet dann die finale Antwort ohne Reasoning.
• Wenn channels.telegram.streamMode off ist, ist der Reasoning-Stream deaktiviert. Mehr Kontext: Streaming + Chunking.

Retry-Richtlinie

Ausgehende Telegram-API-Aufrufe werden bei vorübergehenden Netz-/429-Fehlern mit exponentiellem Backoff und Jitter wiederholt. Konfiguration über channels.telegram.retry. Siehe Retry-Richtlinie.

Agent-Tool (Nachrichten + Reaktionen)

• Tool: telegram mit Aktion sendMessage (to, content, optional mediaUrl, replyToMessageId, messageThreadId).
• Tool: telegram mit Aktion react (chatId, messageId, emoji).
• Tool: telegram mit Aktion deleteMessage (chatId, messageId).
• Reaktions-Entfernung: siehe /tools/reactions.
• Tool-Steuerung: channels.telegram.actions.reactions, channels.telegram.actions.sendMessage, channels.telegram.actions.deleteMessage (Standard: aktiviert), channels.telegram.actions.sticker (Standard: deaktiviert).

Reaktions-Benachrichtigungen

Ablauf von Reaktionen: Telegram-Reaktionen kommen als eigene message_reaction-Events, nicht als Eigenschaften in Nachrichten-Payloads. Wenn ein Benutzer eine Reaktion hinzufügt, macht OpenClaw:

1. Empfängt das message_reaction-Update von der Telegram-API
2. Wandelt es in ein System-Event mit Format um: "Telegram reaction added: {emoji} by {user} on msg {id}"
3. Reiht das System-Event mit dem gleichen Sitzungsschlüssel wie normale Nachrichten ein
4. Wenn die nächste Nachricht in dieser Konversation ankommt, werden System-Events abgearbeitet und dem Agenten-Kontext vorangestellt

Der Agent sieht Reaktionen als System-Benachrichtigungen in der Konversationshistorie, nicht als Nachrichten-Metadaten. Konfiguration:

• channels.telegram.reactionNotifications: Steuert, welche Reaktionen Benachrichtigungen auslösen
  • "off" — alle Reaktionen ignorieren
  • "own" — benachrichtigen, wenn Benutzer auf Bot-Nachrichten reagieren (Best-Effort; im Speicher) (Standard)
  • "all" — bei allen Reaktionen benachrichtigen
• channels.telegram.reactionLevel: Steuert die Reaktionsfähigkeit des Agenten
  • "off" — Agent kann nicht auf Nachrichten reagieren
  • "ack" — Bot sendet Bestätigungs-Reaktionen (👀 während der Verarbeitung) (Standard)
  • "minimal" — Agent kann sparsam reagieren (Richtwert: 1 pro 5–10 Austausche)
  • "extensive" — Agent kann bei Bedarf großzügig reagieren

Forum-Gruppen: Reaktionen in Forum-Gruppen enthalten message_thread_id und nutzen Sitzungsschlüssel wie agent:main:telegram:group:{chatId}:topic:{threadId}. So bleiben Reaktionen und Nachrichten im gleichen Thema zusammen. Beispiel-Konfiguration:

{
  channels: {
    telegram: {
      reactionNotifications: "all",  // See all reactions
      reactionLevel: "minimal"        // Agent can react sparingly
    }
  }
}

Anforderungen:

• Telegram-Bots müssen message_reaction explizit in allowed_updates anfordern (wird von OpenClaw automatisch konfiguriert)
• Im Webhook-Modus sind Reaktionen in den Webhook-allowed_updates enthalten
• Im Polling-Modus sind Reaktionen in den getUpdates-allowed_updates enthalten

Zustellziele (CLI/Cron)

• Chat-ID (123456789) oder Benutzername (@name) als Ziel nutzen.
• Beispiel: openclaw message send --channel telegram --target 123456789 --message "hi".

Fehlerbehebung

Bot antwortet nicht auf Nicht-Erwähnungs-Nachrichten in einer Gruppe:

• Wenn Sie channels.telegram.groups.*.requireMention=false setzen, muss der Privacy Mode der Telegram Bot API deaktiviert sein.
  • BotFather: /setprivacy → Disable (dann Bot aus der Gruppe entfernen und wieder hinzufügen)
• openclaw channels status zeigt eine Warnung, wenn die Konfiguration Gruppennachrichten ohne Erwähnung erwartet.
• openclaw channels status --probe kann zusätzlich die Mitgliedschaft für explizite numerische Gruppen-IDs prüfen (Wildcard-"*"-Regeln können nicht geprüft werden).
• Schnelltest: /activation always (nur Sitzung; für Dauerhaftigkeit Konfiguration nutzen)

Bot sieht gar keine Gruppennachrichten:

• Wenn channels.telegram.groups gesetzt ist, muss die Gruppe gelistet sein oder "*" genutzt werden
• Privacy-Einstellungen in @BotFather prüfen → „Group Privacy“ sollte OFF sein
• Sicherstellen, dass der Bot tatsächlich Mitglied ist (nicht nur Admin ohne Leseberechtigung)
• Gateway-Logs prüfen: openclaw logs --follow (nach „skipping group message“ suchen)

Bot antwortet auf Erwähnungen, aber nicht auf /activation always:

• Der Befehl /activation aktualisiert nur den Sitzungszustand und speichert nicht in der Konfiguration
• Für dauerhaftes Verhalten Gruppe zu channels.telegram.groups mit requireMention: false hinzufügen

Befehle wie /status funktionieren nicht:

• Sicherstellen, dass Ihre Telegram-Benutzer-ID autorisiert ist (über Pairing oder channels.telegram.allowFrom)
• Befehle erfordern Autorisierung auch in Gruppen mit groupPolicy: "open"

Long-Polling bricht sofort auf Node 22+ ab (oft mit Proxies/custom fetch):

• Node 22+ ist strenger bei AbortSignal-Instanzen; fremde Signale können fetch-Aufrufe sofort abbrechen.
• Auf eine OpenClaw-Version upgraden, die Abort-Signale normalisiert, oder das Gateway unter Node 20 laufen lassen, bis ein Upgrade möglich ist.

Bot startet, antwortet dann still nicht mehr (oder Logs zeigen HttpError: Network request ... failed):

• Einige Hosts lösen api.telegram.org zuerst auf IPv6 auf. Wenn Ihr Server keinen funktionierenden IPv6-Ausgang hat, kann grammY bei reinen IPv6-Anfragen hängen bleiben.
• Behebung: IPv6-Ausgang aktivieren oder IPv4-Auflösung für api.telegram.org erzwingen (z. B. Eintrag in /etc/hosts mit IPv4-A-Record oder IPv4 in der OS-DNS-Konfiguration bevorzugen), dann Gateway neu starten.
• Schnellprüfung: dig +short api.telegram.org A und dig +short api.telegram.org AAAA, um zu bestätigen, was DNS zurückgibt.

Konfigurationsreferenz (Telegram)

Vollständige Konfiguration: Konfiguration. Provider-Optionen:

• channels.telegram.enabled: Kanalstart aktivieren/deaktivieren.
• channels.telegram.botToken: Bot-Token (BotFather).
• channels.telegram.tokenFile: Token aus Dateipfad lesen.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (Standard: pairing).
• channels.telegram.allowFrom: DM-Zulassen-Liste (IDs/Benutzernamen). open erfordert "*".
• channels.telegram.groupPolicy: open | allowlist | disabled (Standard: allowlist).
• channels.telegram.groupAllowFrom: Gruppen-Absender-Zulassen-Liste (IDs/Benutzernamen).
• channels.telegram.groups: Pro-Gruppen-Standards + Zulassen-Liste ("*" für globale Standards).
  • channels.telegram.groups.<id>.requireMention: Standard für Erwähnungs-Steuerung.
  • channels.telegram.groups.<id>.skills: Skill-Filter (weglassen = alle Skills, leer = keine).
  • channels.telegram.groups.<id>.allowFrom: Pro-Gruppen-Absender-Zulassen-Liste-Override.
  • channels.telegram.groups.<id>.systemPrompt: zusätzlicher System-Prompt für die Gruppe.
  • channels.telegram.groups.<id>.enabled: Gruppe deaktivieren bei false.
  • channels.telegram.groups.<id>.topics.<threadId>.*: Pro-Thema-Overrides (gleiche Felder wie Gruppe).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: Pro-Thema-Erwähnungs-Steuerung.
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (Standard: allowlist).
• channels.telegram.accounts.<account>.capabilities.inlineButtons: Pro-Konto-Override.
• channels.telegram.replyToMode: off | first | all (Standard: first).
• channels.telegram.textChunkLimit: ausgehende Chunk-Größe (Zeichen).
• channels.telegram.chunkMode: length (Standard) oder newline zum Teilen an Leerzeilen (Absatzgrenzen) vor Längen-Chunking.
• channels.telegram.linkPreview: Link-Vorschauen für ausgehende Nachrichten umschalten (Standard: true).
• channels.telegram.streamMode: off | partial | block (Draft-Streaming).
• channels.telegram.mediaMaxMb: eingehendes/ausgehendes Medien-Limit (MB).
• channels.telegram.retry: Retry-Richtlinie für ausgehende Telegram-API-Aufrufe (attempts, minDelayMs, maxDelayMs, jitter).
• channels.telegram.network.autoSelectFamily: Node autoSelectFamily überschreiben (true=aktivieren, false=deaktivieren). Standardmäßig unter Node 22 deaktiviert, um Happy-Eyeballs-Timeouts zu vermeiden.
• channels.telegram.proxy: Proxy-URL für Bot-API-Aufrufe (SOCKS/HTTP).
• channels.telegram.webhookUrl: Webhook-Modus aktivieren.
• channels.telegram.webhookSecret: Webhook-Secret (optional).
• channels.telegram.webhookPath: lokaler Webhook-Pfad (Standard /telegram-webhook).
• channels.telegram.actions.reactions: Telegram-Tool-Reaktionen steuern.
• channels.telegram.actions.sendMessage: Telegram-Tool-Nachrichtenversand steuern.
• channels.telegram.actions.deleteMessage: Telegram-Tool-Nachrichtenlöschung steuern.
• channels.telegram.actions.sticker: Telegram-Sticker-Aktionen steuern — senden und suchen (Standard: false).
• channels.telegram.reactionNotifications: off | own | all — steuert, welche Reaktionen System-Events auslösen (Standard: own wenn nicht gesetzt).
• channels.telegram.reactionLevel: off | ack | minimal | extensive — Reaktionsfähigkeit des Agenten steuern (Standard: minimal wenn nicht gesetzt).

Verwandte globale Optionen:

• agents.list[].groupChat.mentionPatterns (Erwähnungs-Muster).
• messages.groupChat.mentionPatterns (globaler Fallback).
• commands.native (Standard "auto" → an für Telegram/Discord, aus für Slack), commands.text, commands.useAccessGroups (Befehlsverhalten). Überschreiben mit channels.telegram.commands.native.
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope, messages.removeAckAfterReply.