Telegram

• deaktivieren Sie den Datenschutzmodus über /setprivacy, oder
• machen Sie den Bot zum Gruppenadministrator.

• /setjoingroups, um das Hinzufügen zu Gruppen zuzulassen/zu verweigern
• /setprivacy für das Verhalten der Gruppensichtbarkeit

• Direktchats: Vorschaunachricht + editMessageText
• Gruppen/Themen: Vorschaunachricht + editMessageText

• channels.telegram.streaming ist off | partial | block | progress (Standard: partial)
• progress behält einen bearbeitbaren Statusentwurf für Tool-Fortschritt bei, löscht ihn nach Abschluss und sendet die finale Antwort als normale Nachricht
• streaming.preview.toolProgress steuert, ob Tool-/Fortschrittsaktualisierungen dieselbe bearbeitete Vorschau-Nachricht wiederverwenden (Standard: true, wenn Vorschau-Streaming aktiv ist)
• streaming.preview.commandText steuert Befehls-/Ausführungsdetails in diesen Tool-Fortschrittszeilen: raw (Standard, bewahrt das veröffentlichte Verhalten) oder status (nur Tool-Bezeichnung)
• veraltete Werte für channels.telegram.streamMode und boolesche streaming-Werte werden erkannt; führen Sie openclaw doctor --fix aus, um sie nach channels.telegram.streaming.mode zu migrieren

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

• kurze DM-/Gruppen-/Themenvorschauen: OpenClaw behält dieselbe Vorschau-Nachricht bei und führt die finale Bearbeitung direkt daran aus
• lange finale Texte, die in mehrere Telegram-Nachrichten aufgeteilt werden, verwenden die vorhandene Vorschau nach Möglichkeit als ersten finalen Abschnitt wieder und senden danach nur die verbleibenden Abschnitte
• Finale Antworten im Fortschrittsmodus löschen den Statusentwurf und verwenden normale finale Zustellung, statt den Entwurf zur Antwort umzubearbeiten
• wenn die finale Bearbeitung fehlschlägt, bevor der vollständige Text bestätigt ist, verwendet OpenClaw normale finale Zustellung und bereinigt die veraltete Vorschau

• /reasoning stream sendet Reasoning während der Generierung an die Live-Vorschau
• die Reasoning-Vorschau wird nach der finalen Zustellung gelöscht; verwenden Sie /reasoning on, wenn Reasoning sichtbar bleiben soll
• die finale Antwort wird ohne Reasoning-Text gesendet

• Markdown-ähnlicher Text wird in Telegram-sicheres HTML gerendert.
• Unterstützte Telegram-HTML-Tags bleiben erhalten; nicht unterstütztes HTML wird escaped.
• Wenn Telegram geparstes HTML ablehnt, versucht OpenClaw es erneut als Klartext.

• commands.native: "auto" aktiviert native Befehle für Telegram

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

• Namen werden normalisiert (führendes / entfernen, Kleinschreibung)
• gültiges Muster: a-z, 0-9, _, Länge 1..32
• benutzerdefinierte Befehle können native Befehle nicht überschreiben
• Konflikte/Duplikate werden übersprungen und protokolliert

• benutzerdefinierte Befehle sind nur Menüeinträge; sie implementieren kein Verhalten automatisch
• Plugin-/Skill-Befehle können weiterhin funktionieren, wenn sie eingegeben werden, auch wenn sie nicht im Telegram-Menü angezeigt werden

• setMyCommands failed mit BOT_COMMANDS_TOO_MUCH bedeutet, dass das Telegram-Menü auch nach dem Kürzen noch überlaufen ist; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie channels.telegram.commands.native.
• Wenn deleteWebhook, deleteMyCommands oder setMyCommands mit 404: Not Found fehlschlägt, während direkte Bot-API-curl-Befehle funktionieren, kann das bedeuten, dass channels.telegram.apiRoot auf den vollständigen /bot<TOKEN>-Endpunkt gesetzt wurde. apiRoot darf nur die Bot-API-Wurzel sein, und openclaw doctor --fix entfernt ein versehentlich angehängtes /bot<TOKEN>.
• getMe returned 401 bedeutet, dass Telegram das konfigurierte Bot-Token abgelehnt hat. Aktualisieren Sie botToken, tokenFile oder TELEGRAM_BOT_TOKEN mit dem aktuellen BotFather-Token; OpenClaw stoppt vor dem Polling, sodass dies nicht als Fehler bei der Webhook-Bereinigung gemeldet wird.
• setMyCommands failed mit Netzwerk-/Fetch-Fehlern bedeutet üblicherweise, dass ausgehendes DNS/HTTPS zu api.telegram.org blockiert ist.

​

Befehle zur Gerätekopplung (device-pair-Plugin)

1. /pair generiert Einrichtungscode
2. Code in die iOS-App einfügen
3. /pair pending listet ausstehende Anfragen auf (einschließlich Rolle/Scopes)
4. die Anfrage genehmigen:
   • /pair approve <requestId> für explizite Genehmigung
   • /pair approve, wenn es nur eine ausstehende Anfrage gibt
   • /pair approve latest für die neueste

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

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

• off
• dm
• group
• all
• allowlist (Standard)

{
  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" }],
  ],
}

• sendMessage (to, content, optional mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, optional iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (Standard: deaktiviert)

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

• off (Standard)
• first
• all

• Themen-Sitzungsschlüssel hängen :topic:<threadId> an
• Antworten und Tippaktionen richten sich an den Themen-Thread
• Themenkonfigurationspfad: channels.telegram.groups.<chatId>.topics.<threadId>

• Nachrichtensendungen lassen message_thread_id weg (Telegram lehnt sendMessage(...thread_id=1) ab)
• Tippaktionen enthalten weiterhin message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

Audionachrichten

• Standard: Verhalten für Audiodateien
• Tag [[audio_as_voice]] in der Agent-Antwort, um das Senden als Sprachnachricht zu erzwingen
• Eingehende Transkripte von Sprachnachrichten werden im Agent-Kontext als maschinell erzeugter, nicht vertrauenswürdiger Text gekennzeichnet; die Erwähnungserkennung verwendet weiterhin das rohe Transkript, sodass erwähnungsgesteuerte Sprachnachrichten weiter funktionieren.

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

​

Videonachrichten

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

​

Sticker

• statisches WEBP: heruntergeladen und verarbeitet (Platzhalter <media:sticker>)
• animiertes TGS: übersprungen
• Video-WEBM: übersprungen

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

• channels.telegram.reactionNotifications: off | own | all (Standard: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (Standard: minimal)

• own bedeutet nur Benutzerreaktionen auf vom Bot gesendete Nachrichten (Best Effort über den Cache gesendeter Nachrichten).
• Reaktionsereignisse respektieren weiterhin Telegram-Zugriffskontrollen (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); nicht autorisierte Absender werden verworfen.
• Telegram stellt in Reaktions-Updates keine Thread-IDs bereit.
  • Nicht-Forum-Gruppen werden zur Gruppenchat-Sitzung geleitet
  • Forum-Gruppen werden zur allgemeinen Topic-Sitzung der Gruppe (:topic:1) geleitet, nicht zum exakten ursprünglichen Topic

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• Fallback auf Emoji der Agent-Identität (agents.list[].identity.emoji, sonst ”👀”)

• Telegram erwartet Unicode-Emoji (zum Beispiel ”👀”).
• Verwenden Sie "", um die Reaktion für einen Kanal oder ein Konto zu deaktivieren.

• Gruppenmigrationsereignisse (migrate_to_chat_id) zum Aktualisieren von channels.telegram.groups
• /config set und /config unset (erfordert aktivierte Befehle)

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

• channels.telegram.textChunkLimit ist standardmäßig 4000.
• channels.telegram.chunkMode="newline" bevorzugt Absatzgrenzen (Leerzeilen), bevor nach Länge aufgeteilt wird.
• channels.telegram.mediaMaxMb (Standard 100) begrenzt die Größe eingehender und ausgehender Telegram-Medien.
• channels.telegram.mediaGroupFlushMs (Standard 500) steuert, wie lange Telegram-Alben/Mediengruppen gepuffert werden, bevor OpenClaw sie als eine eingehende Nachricht dispatcht. Erhöhen Sie den Wert, wenn Albumteile spät ankommen; verringern Sie ihn, um die Antwortlatenz bei Alben zu reduzieren.
• channels.telegram.timeoutSeconds überschreibt das Timeout des Telegram-API-Clients (wenn nicht gesetzt, gilt der grammY-Standard). Bot-Clients begrenzen konfigurierte Werte unterhalb des 60-sekündigen Request-Guards für ausgehende Text-/Typing-Anfragen, damit grammY die sichtbare Antwortzustellung nicht abbricht, bevor OpenClaws Transport-Guard und Fallback ausgeführt werden können. Long Polling verwendet weiterhin einen 45-sekündigen getUpdates-Request-Guard, damit inaktive Polls nicht unbegrenzt offen bleiben.
• channels.telegram.pollingStallThresholdMs ist standardmäßig 120000; justieren Sie den Wert nur bei falsch positiven Polling-Stall-Neustarts zwischen 30000 und 600000.
• Gruppen-Kontexthistorie verwendet channels.telegram.historyLimit oder messages.groupChat.historyLimit (Standard 50); 0 deaktiviert sie.
• Ergänzender Kontext für Antworten/Zitate/Weiterleitungen wird in ein ausgewähltes Konversationskontextfenster normalisiert, wenn der Gateway die übergeordneten Nachrichten beobachtet hat; der Cache beobachteter Nachrichten wird neben dem Sitzungsspeicher persistiert. Telegram enthält in Updates nur ein flaches reply_to_message, daher sind Ketten, die älter als der Cache sind, auf Telegrams aktuelle Update-Payload begrenzt.
• Telegram-Allowlists steuern primär, wer den Agent auslösen kann, nicht eine vollständige Redaktionsgrenze für ergänzenden Kontext.
• DM-Historiensteuerungen:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• Die Konfiguration channels.telegram.retry gilt für Telegram-Sendehelfer (CLI/Tools/Aktionen) bei behebbaren ausgehenden API-Fehlern. Die Zustellung der endgültigen eingehenden Antwort verwendet ebenfalls eine begrenzte Safe-Send-Wiederholung für Telegram-Pre-Connect-Fehler, wiederholt aber keine mehrdeutigen Post-Send-Netzwerkumschläge, die sichtbare Nachrichten duplizieren könnten.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id für Forum-Topics (oder verwenden Sie ein :topic:-Ziel)

• --presentation mit buttons-Blöcken für Inline-Keyboards, wenn channels.telegram.capabilities.inlineButtons dies erlaubt
• --pin oder --delivery '{"pin":true}', um angeheftete Zustellung anzufordern, wenn der Bot in diesem Chat anheften kann
• --force-document, um ausgehende Bilder, GIFs und Videos als Dokumente statt als komprimierte Foto-, animierte Medien- oder Video-Uploads zu senden

• channels.telegram.actions.sendMessage=false deaktiviert ausgehende Telegram-Nachrichten, einschließlich Polls
• channels.telegram.actions.poll=false deaktiviert das Erstellen von Telegram-Polls, während reguläres Senden aktiviert bleibt

• channels.telegram.execApprovals.enabled (aktiviert sich automatisch, wenn mindestens ein Genehmiger auflösbar ist)
• channels.telegram.execApprovals.approvers (fällt auf numerische Owner-IDs aus commands.ownerAllowFrom zurück)
• channels.telegram.execApprovals.target: dm (Standard) | channel | both
• agentFilter, sessionFilter

• Wenn requireMention=false ist, muss der Telegram-Datenschutzmodus vollständige Sichtbarkeit erlauben.
  • BotFather: /setprivacy -> Deaktivieren
  • entfernen Sie den Bot anschließend aus der Gruppe und fügen Sie ihn erneut hinzu
• openclaw channels status warnt, wenn die Konfiguration nicht erwähnte Gruppennachrichten erwartet.
• openclaw channels status --probe kann explizite numerische Gruppen-IDs prüfen; wildcard "*" kann nicht per Mitgliedschaft geprüft werden.
• schneller Sitzungstest: /activation always.

• wenn channels.telegram.groups vorhanden ist, muss die Gruppe aufgeführt sein (oder "*" enthalten)
• prüfen Sie die Bot-Mitgliedschaft in der Gruppe
• prüfen Sie die Logs: openclaw logs --follow für Gründe zum Überspringen

• autorisieren Sie Ihre Absenderidentität (Pairing und/oder numerisches allowFrom)
• die Befehlsautorisierung gilt weiterhin, auch wenn die Gruppenrichtlinie open ist
• setMyCommands failed mit BOT_COMMANDS_TOO_MUCH bedeutet, dass das native Menü zu viele Einträge hat; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie native Menüs
• deleteMyCommands- / setMyCommands-Startaufrufe und sendChatAction-Tippindikator-Aufrufe sind begrenzt und werden bei Request-Timeout einmal über Telegrams Transport-Fallback erneut versucht. Dauerhafte Netzwerk-/Fetch-Fehler weisen in der Regel auf DNS-/HTTPS-Erreichbarkeitsprobleme zu api.telegram.org hin

• getMe returned 401 ist ein Telegram-Authentifizierungsfehler für das konfigurierte Bot-Token.
• Kopieren Sie das Bot-Token in BotFather erneut oder generieren Sie es neu, und aktualisieren Sie dann channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken oder TELEGRAM_BOT_TOKEN für das Standardkonto.
• deleteWebhook 401 Unauthorized während des Starts ist ebenfalls ein Authentifizierungsfehler; dies als „kein Webhook vorhanden“ zu behandeln, würde denselben Fehler durch ein ungültiges Token nur auf spätere API-Aufrufe verschieben.

• Node 22+ + benutzerdefiniertes Fetch/Proxy können sofortiges Abbruchverhalten auslösen, wenn AbortSignal-Typen nicht übereinstimmen.
• Manche Hosts lösen api.telegram.org zuerst zu IPv6 auf; defekter IPv6-Egress kann zeitweise Telegram-API-Fehler verursachen.
• Wenn Logs TypeError: fetch failed oder Network request for 'getUpdates' failed! enthalten, versucht OpenClaw diese nun als behebbare Netzwerkfehler erneut.
• Während des Polling-Starts verwendet OpenClaw den erfolgreichen Start-getMe-Probe für grammY wieder, sodass der Runner kein zweites getMe vor dem ersten getUpdates benötigt.
• Wenn deleteWebhook während des Polling-Starts mit einem transienten Netzwerkfehler fehlschlägt, fährt OpenClaw mit Long Polling fort, statt einen weiteren Control-Plane-Aufruf vor dem Polling auszuführen. Ein noch aktiver Webhook erscheint als getUpdates-Konflikt; OpenClaw baut dann den Telegram-Transport neu auf und versucht die Webhook-Bereinigung erneut.
• Wenn Telegram-Sockets in einem kurzen festen Takt erneuert werden, prüfen Sie auf einen niedrigen Wert für channels.telegram.timeoutSeconds; Bot-Clients begrenzen konfigurierte Werte unterhalb der Schutzwerte für ausgehende Requests und getUpdates, ältere Releases konnten jedoch jedes Polling oder jede Antwort abbrechen, wenn dies unter diesen Schutzwerten gesetzt war.
• Wenn Logs Polling stall detected enthalten, startet OpenClaw das Polling neu und baut den Telegram-Transport nach standardmäßig 120 Sekunden ohne abgeschlossene Long-Poll-Liveness neu auf.
• openclaw channels status --probe und openclaw doctor warnen, wenn ein laufendes Polling-Konto getUpdates nach der Startnachfrist nicht abgeschlossen hat, wenn ein laufendes Webhook-Konto setWebhook nach der Startnachfrist nicht abgeschlossen hat oder wenn die letzte erfolgreiche Polling-Transportaktivität veraltet ist.
• Erhöhen Sie channels.telegram.pollingStallThresholdMs nur, wenn lang laufende getUpdates-Aufrufe fehlerfrei sind, Ihr Host aber weiterhin falsche Polling-Stall-Neustarts meldet. Dauerhafte Stalls deuten in der Regel auf Proxy-, DNS-, IPv6- oder TLS-Egress-Probleme zwischen Host und api.telegram.org hin.
• Telegram berücksichtigt außerdem Prozess-Proxy-Umgebungsvariablen für den Bot-API-Transport, einschließlich HTTP_PROXY, HTTPS_PROXY, ALL_PROXY und deren Varianten in Kleinschreibung. NO_PROXY / no_proxy kann api.telegram.org weiterhin umgehen.
• Wenn der von OpenClaw verwaltete Proxy über OPENCLAW_PROXY_URL für eine Dienstumgebung konfiguriert ist und keine standardmäßige Proxy-Umgebungsvariable vorhanden ist, verwendet Telegram diese URL ebenfalls für den Bot-API-Transport.
• Leiten Sie Telegram-API-Aufrufe auf VPS-Hosts mit instabilem direktem Egress/TLS über channels.telegram.proxy:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ verwendet standardmäßig autoSelectFamily=true (außer WSL2). Die Reihenfolge der Telegram-DNS-Ergebnisse berücksichtigt OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, dann channels.telegram.network.dnsResultOrder, dann den Prozessstandard wie NODE_OPTIONS=--dns-result-order=ipv4first; wenn nichts davon zutrifft, fällt Node 22+ auf ipv4first zurück.
• Wenn Ihr Host WSL2 ist oder ausdrücklich besser mit reinem IPv4-Verhalten funktioniert, erzwingen Sie die Familienauswahl:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Antworten aus dem RFC-2544-Benchmark-Bereich (198.18.0.0/15) sind für Telegram-Mediendownloads standardmäßig bereits erlaubt. Wenn ein vertrauenswürdiger Fake-IP- oder transparenter Proxy api.telegram.org während Mediendownloads auf eine andere private/interne/Special-Use-Adresse umschreibt, können Sie den nur für Telegram geltenden Bypass aktivieren:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• Dieselbe Opt-in-Option ist pro Konto unter channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork verfügbar.
• Wenn Ihr Proxy Telegram-Medienhosts in 198.18.x.x auflöst, lassen Sie das gefährliche Flag zunächst deaktiviert. Telegram-Medien erlauben den RFC-2544-Benchmark-Bereich bereits standardmäßig.

• Umgebungsüberschreibungen (temporär):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• DNS-Antworten validieren:

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