Telegram

Telegram-Bots verwenden standardmäßig den Privacy Mode, der begrenzt, welche Gruppennachrichten sie empfangen.

Wenn der Bot alle Gruppennachrichten sehen muss, entweder:

• deaktivieren Sie den Privacy Mode über /setprivacy, oder
• machen Sie den Bot zum Gruppenadmin.

Wenn Sie den Privacy Mode umschalten, entfernen Sie den Bot in jeder Gruppe und fügen Sie ihn erneut hinzu, damit Telegram die Änderung anwendet.

Der Admin-Status wird in den Telegram-Gruppeneinstellungen gesteuert.

Admin-Bots empfangen alle Gruppennachrichten, was für dauerhaft aktives Gruppenverhalten nützlich ist.

• /setjoingroups, um das Hinzufügen zu Gruppen zu erlauben/zu verweigern
• /setprivacy für das Sichtbarkeitsverhalten in Gruppen

OpenClaw kann Teilantworten in Echtzeit streamen:

• direkte Chats: Vorschaunachricht + editMessageText
• Gruppen/Themen: Vorschaunachricht + editMessageText

Voraussetzung:

• channels.telegram.streaming ist off | partial | block | progress (Standard: partial)
• progress hält einen bearbeitbaren Statusentwurf für Tool-Fortschritt, löscht ihn beim Abschluss und sendet die finale Antwort als normale Nachricht
• streaming.preview.toolProgress steuert, ob Tool-/Fortschrittsupdates dieselbe bearbeitete Vorschaunachricht wiederverwenden (Standard: true, wenn Vorschau-Streaming aktiv ist)
• streaming.preview.commandText steuert Befehls-/Exec-Details innerhalb dieser Tool-Fortschrittszeilen: raw (Standard, bewahrt veröffentlichtes Verhalten) oder status (nur Tool-Label)
• Legacy-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

Tool-Fortschrittsvorschau-Updates sind die kurzen Statuszeilen, die angezeigt werden, während Tools laufen, zum Beispiel Befehlsausführung, Dateilesevorgänge, Planungsupdates oder Patch-Zusammenfassungen. Telegram lässt diese standardmäßig aktiviert, um dem veröffentlichten OpenClaw-Verhalten ab v2026.4.22 und später zu entsprechen. Um die bearbeitete Vorschau für Antworttext beizubehalten, aber Tool-Fortschrittszeilen auszublenden, setzen Sie:

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

Um Tool-Fortschritt sichtbar zu halten, aber Befehls-/Exec-Text auszublenden, setzen Sie:

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

Verwenden Sie den Modus progress, wenn sichtbarer Tool-Fortschritt angezeigt werden soll, ohne die finale Antwort in dieselbe Nachricht hineinzubearbeiten. Legen Sie die Richtlinie für Befehlstext unter streaming.progress ab:

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

Verwenden Sie streaming.mode: "off" nur, wenn Sie ausschließlich finale Zustellung wünschen: Telegram-Vorschauänderungen sind deaktiviert, und generisches Tool-/Fortschrittsgeplauder wird unterdrückt, statt als eigenständige Statusmeldungen gesendet zu werden. Genehmigungsaufforderungen, Medien-Payloads und Fehler werden weiterhin über die normale finale Zustellung geleitet. Verwenden Sie streaming.preview.toolProgress: false, wenn Sie nur Antwortvorschau-Änderungen beibehalten möchten, während die Tool-Fortschrittsstatuszeilen ausgeblendet werden.

Für reine Textantworten:

• kurze Vorschauen in DMs/Gruppen/Themen: OpenClaw behält dieselbe Vorschaunachricht bei und führt die finale Bearbeitung direkt daran aus
• lange finale Textantworten, die in mehrere Telegram-Nachrichten aufgeteilt werden, verwenden die vorhandene Vorschau nach Möglichkeit als ersten finalen Chunk wieder und senden danach nur die verbleibenden Chunks
• Finale Antworten im Fortschrittsmodus löschen den Statusentwurf und verwenden die normale finale Zustellung, statt den Entwurf in die Antwort umzuwandeln
• wenn die finale Bearbeitung fehlschlägt, bevor der vollständige Text bestätigt wurde, verwendet OpenClaw die normale finale Zustellung und bereinigt die veraltete Vorschau

Bei komplexen Antworten (zum Beispiel Medien-Payloads) fällt OpenClaw auf die normale finale Zustellung zurück und bereinigt anschließend die Vorschaunachricht.

Vorschau-Streaming ist von Block-Streaming getrennt. Wenn Block-Streaming für Telegram ausdrücklich aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden.

Reiner Telegram-Reasoning-Stream:

• /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

Ausgehender Text verwendet Telegram parse_mode: "HTML".

• Markdown-ähnlicher Text wird in Telegram-sicheres HTML gerendert.
• Rohes Modell-HTML wird escaped, um Telegram-Parse-Fehler zu reduzieren.
• Wenn Telegram geparstes HTML ablehnt, versucht OpenClaw es erneut als Klartext.

Linkvorschauen sind standardmäßig aktiviert und können mit channels.telegram.linkPreview: false deaktiviert werden.

Die Registrierung des Telegram-Befehlsmenüs wird beim Start mit setMyCommands verarbeitet.

Standardwerte für native Befehle:

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

Benutzerdefinierte Befehlsmenüeinträge hinzufügen:

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

Regeln:

• Namen werden normalisiert (führendes / entfernen, Kleinbuchstaben)
• 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

Hinweise:

• 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 im Telegram-Menü nicht angezeigt werden

Wenn native Befehle deaktiviert sind, werden integrierte Befehle entfernt. Benutzerdefinierte/Plugin-Befehle können sich weiterhin registrieren, wenn sie konfiguriert sind.

Häufige Einrichtungsfehler:

• setMyCommands failed mit BOT_COMMANDS_TOO_MUCH bedeutet, dass das Telegram-Menü auch nach dem Kürzen noch übergelaufen ist; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie channels.telegram.commands.native.
• Wenn deleteWebhook, deleteMyCommands oder setMyCommands mit 404: Not Found fehlschlagen, 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 versehentliches abschließendes /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, daher wird dies nicht als Webhook-Bereinigungsfehler gemeldet.
• setMyCommands failed mit Netzwerk-/Fetch-Fehlern bedeutet in der Regel, dass ausgehendes DNS/HTTPS zu api.telegram.org blockiert ist.

# Gerätekopplungsbefehle (device-pair-Plugin)

Wenn das device-pair-Plugin installiert ist:

1. /pair erzeugt Einrichtungscode
2. Code in der 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 nur eine ausstehende Anfrage vorhanden ist
   • /pair approve latest für die neueste

Der Einrichtungscode enthält ein kurzlebiges Bootstrap-Token. Die integrierte Bootstrap-Übergabe hält das primäre Node-Token bei scopes: []; jedes übergebene Operator-Token bleibt auf operator.approvals, operator.read, operator.talk.secrets und operator.write begrenzt. Bootstrap-Scope-Prüfungen sind rollenpräfigiert, daher erfüllt diese Operator-Allowlist nur Operator-Anfragen; Nicht-Operator-Rollen benötigen weiterhin Scopes unter ihrem eigenen Rollenpräfix.

Wenn ein Gerät es mit geänderten Authentifizierungsdetails erneut versucht (zum Beispiel Rolle/Scopes/öffentlicher Schlüssel), wird die vorherige ausstehende Anfrage ersetzt, und die neue Anfrage verwendet eine andere requestId. Führen Sie /pair pending erneut aus, bevor Sie genehmigen.

Weitere Details: Kopplung.

Inline-Keyboard-Scope konfigurieren:

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

Überschreibung pro Konto:

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

Scopes:

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

Veraltetes capabilities: ["inlineButtons"] wird auf inlineButtons: "all" abgebildet.

Beispiel für Nachrichtenaktion:

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

Callback-Klicks werden als Text an den Agenten übergeben: callback_data: <value>

Telegram-Tool-Aktionen umfassen:

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

Kanalnachrichtenaktionen stellen ergonomische Aliasse bereit (send, react, delete, edit, sticker, sticker-search, topic-create).

Steuerungen für Gates:

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

Hinweis: edit und topic-create sind derzeit standardmäßig aktiviert und haben keine separaten channels.telegram.actions.*-Schalter. Laufzeitsendungen verwenden den aktiven Konfigurations-/Secrets-Snapshot (Start/Reload), daher führen Aktionspfade keine Ad-hoc-SecretRef-Neuauflösung pro Sendung aus.

Semantik zum Entfernen von Reaktionen: /tools/reactions

Telegram unterstützt explizite Reply-Threading-Tags in generierter Ausgabe:

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

channels.telegram.replyToMode steuert die Verarbeitung:

• off (Standard)
• first
• all

Wenn Reply-Threading aktiviert ist und der ursprüngliche Telegram-Text oder die Bildunterschrift verfügbar ist, fügt OpenClaw automatisch einen nativen Telegram-Zitatauszug ein. Telegram begrenzt nativen Zitattext auf 1024 UTF-16-Codeeinheiten, daher werden längere Nachrichten vom Anfang an zitiert und fallen auf eine einfache Antwort zurück, wenn Telegram das Zitat ablehnt.

Hinweis: off deaktiviert implizites Reply-Threading. Explizite [[reply_to_*]]-Tags werden weiterhin berücksichtigt.

Forum-Supergruppen:

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

Sonderfall Allgemeines Thema (threadId=1):

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

Themenvererbung: Themeneinträge erben Gruppeneinstellungen, sofern sie nicht überschrieben werden (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId ist nur themenspezifisch und wird nicht aus Gruppenvorgaben geerbt.

Agent-Routing pro Thema: Jedes Thema kann an einen anderen Agenten weiterleiten, indem agentId in der Themenkonfiguration gesetzt wird. Dadurch erhält jedes Thema seinen eigenen isolierten Arbeitsbereich, Speicher und seine eigene Sitzung. Beispiel:

{
  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
          }
        }
      }
    }
  }
}

Jedes Thema hat dann seinen eigenen Sitzungsschlüssel: agent:zu:telegram:group:-1001234567890:topic:3

Persistente ACP-Themenbindung: Forumsthemen können ACP-Harness-Sitzungen über typisierte ACP-Bindungen auf oberster Ebene anheften (bindings[] mit type: "acp" und match.channel: "telegram", peer.kind: "group" sowie einer themenqualifizierten ID wie -1001234567890:topic:42). Derzeit auf Forumsthemen in Gruppen/Supergruppen beschränkt. Siehe ACP Agents.

Thread-gebundener ACP-Spawn aus dem Chat: /acp spawn <agent> --thread here|auto bindet das aktuelle Thema an eine neue ACP-Sitzung; Folgeanfragen werden direkt dorthin geleitet. OpenClaw pinnt die Spawn-Bestätigung im Thema an. Erfordert, dass channels.telegram.threadBindings.spawnSessions aktiviert bleibt (Standard: true).

Der Template-Kontext stellt MessageThreadId und IsForum bereit. DM-Chats mit message_thread_id behalten standardmäßig DM-Routing und Antwortmetadaten in flachen Sessions bei; thread-bewusste Session-Schlüssel werden nur verwendet, wenn threadReplies: "inbound", threadReplies: "always", requireTopic: true oder eine passende Topic-Konfiguration konfiguriert ist. Verwenden Sie channels.telegram.dm.threadReplies auf oberster Ebene für die Konto-Standardeinstellung oder direct.<chatId>.threadReplies für eine DM.

# Audionachrichten

Telegram unterscheidet Sprachnotizen von Audiodateien.

• Standard: Verhalten wie Audiodatei
• Tag [[audio_as_voice]] in der Agent-Antwort, um das Senden als Sprachnotiz zu erzwingen
• Eingehende Transkripte von Sprachnotizen werden im Agent-Kontext als maschinell generierter, nicht vertrauenswürdiger Text gerahmt; die Erwähnungserkennung verwendet weiterhin das rohe Transkript, sodass durch Erwähnungen gesteuerte Sprachnachrichten weiter funktionieren.

Beispiel für eine Nachrichtenaktion:

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

# Videonachrichten

Telegram unterscheidet Videodateien von Videonotizen.

Beispiel für eine Nachrichtenaktion:

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

Videonotizen unterstützen keine Bildunterschriften; bereitgestellter Nachrichtentext wird separat gesendet.

# Sticker

Verarbeitung eingehender Sticker:

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

Sticker-Kontextfelder:

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

Sticker-Cache-Datei:

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

Sticker werden einmal beschrieben (wenn möglich) und zwischengespeichert, um wiederholte Vision-Aufrufe zu reduzieren.

Sticker-Aktionen aktivieren:

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

Sticker-Aktion senden:

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

Zwischengespeicherte Sticker suchen:

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

Telegram-Reaktionen kommen als message_reaction-Updates an (getrennt von Nachrichten-Payloads).

Wenn aktiviert, stellt OpenClaw Systemereignisse wie diese in die Warteschlange:

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

Konfiguration:

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

Hinweise:

• own bedeutet nur Benutzerreaktionen auf vom Bot gesendete Nachrichten (Best Effort über 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-Session geroutet
  • Forum-Gruppen werden zur allgemeinen Topic-Session der Gruppe (:topic:1) geroutet, nicht zum genauen ursprünglichen Topic

allowed_updates für Polling/Webhook enthält automatisch message_reaction.

ackReaction sendet ein Bestätigungs-Emoji, während OpenClaw eine eingehende Nachricht verarbeitet.

Auflösungsreihenfolge:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• Agent-Identitäts-Emoji als Fallback (agents.list[].identity.emoji, andernfalls "👀")

Hinweise:

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

Channel-Konfigurationsschreibvorgänge sind standardmäßig aktiviert (configWrites !== false).

Durch Telegram ausgelöste Schreibvorgänge umfassen:

• Gruppenmigrationsereignisse (migrate_to_chat_id) zum Aktualisieren von channels.telegram.groups
• /config set und /config unset (erfordert Aktivierung des Befehls)

Deaktivieren:

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

Standard ist Long Polling. Setzen Sie für den Webhook-Modus channels.telegram.webhookUrl und channels.telegram.webhookSecret; optional webhookPath, webhookHost, webhookPort (Standardwerte /telegram-webhook, 127.0.0.1, 8787).

Im Long-Polling-Modus persistiert OpenClaw seine Neustart-Wasserlinie erst, nachdem ein Update erfolgreich dispatcht wurde. Wenn ein Handler fehlschlägt, bleibt dieses Update im selben Prozess erneut versuchbar und wird für die Neustart-Deduplizierung nicht als abgeschlossen geschrieben.

Der lokale Listener bindet an 127.0.0.1:8787. Für öffentlichen Ingress setzen Sie entweder einen Reverse Proxy vor den lokalen Port oder setzen webhookHost: "0.0.0.0" bewusst.

Der Webhook-Modus validiert Request-Guards, das geheime Telegram-Token und den JSON-Body, bevor 200 an Telegram zurückgegeben wird. OpenClaw verarbeitet das Update dann asynchron über dieselben Bot-Lanes pro Chat/pro Topic, die auch Long Polling verwendet, sodass langsame Agent-Durchläufe den Zustellungs-ACK von Telegram nicht blockieren.

• 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 Albenteile verspätet eintreffen; verringern Sie ihn, um die Antwortlatenz für Alben zu reduzieren.
• channels.telegram.timeoutSeconds überschreibt das Timeout des Telegram-API-Clients (falls 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 laufen können. Long Polling verwendet weiterhin einen 45-sekündigen getUpdates-Request-Guard, damit inaktive Polls nicht unbegrenzt aufgegeben werden.
• channels.telegram.pollingStallThresholdMs ist standardmäßig 120000; passen Sie den Wert nur bei falsch-positiven Neustarts wegen Polling-Stalls zwischen 30000 und 600000 an.
• Gruppen-Kontextverlauf verwendet channels.telegram.historyLimit oder messages.groupChat.historyLimit (Standard 50); 0 deaktiviert ihn.
• Ergänzender Kontext für Antworten/Zitate/Weiterleitungen wird derzeit unverändert weitergegeben.
• Telegram-Allowlists steuern primär, wer den Agent auslösen kann, und sind keine vollständige Redaktionsgrenze für ergänzenden Kontext.
• DM-Verlaufssteuerung:
  • 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 finalen eingehenden Antwort verwendet ebenfalls eine begrenzte Safe-Send-Wiederholung für Telegram-Pre-Connect-Fehler, wiederholt jedoch keine mehrdeutigen Netzwerkumschläge nach dem Senden, die sichtbare Nachrichten duplizieren könnten.

CLI- und Message-Tool-Sendeziele können numerische Chat-ID, Benutzername oder ein Forum-Topic-Ziel sein:

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"

Telegram-Polls verwenden openclaw message poll und unterstützen Forum-Topics:

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

Nur für Telegram geltende Poll-Flags:

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

Telegram-Senden unterstützt außerdem:

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

Aktions-Gating:

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

Telegram unterstützt Exec-Genehmigungen in Genehmiger-DMs und kann Prompts optional im ursprünglichen Chat oder Topic posten. Genehmiger müssen numerische Telegram-Benutzer-IDs sein.

Konfigurationspfad:

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

channels.telegram.allowFrom, groupAllowFrom und defaultTo steuern, wer mit dem Bot sprechen kann und wohin er normale Antworten sendet. Sie machen niemanden zu einem Exec-Genehmiger. Die erste genehmigte DM-Kopplung bootstrapped commands.ownerAllowFrom, wenn noch kein Befehlsbesitzer existiert, sodass die Einrichtung mit einem Besitzer weiterhin funktioniert, ohne IDs unter execApprovals.approvers zu duplizieren.

Channel-Zustellung zeigt den Befehlstext im Chat an; aktivieren Sie channel oder both nur in vertrauenswürdigen Gruppen/Topics. Wenn der Prompt in einem Forum-Topic landet, bewahrt OpenClaw das Topic für den Genehmigungs-Prompt und die Folgeantwort. Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab.

Inline-Genehmigungsbuttons erfordern außerdem, dass channels.telegram.capabilities.inlineButtons die Zieloberfläche (dm, group oder all) erlaubt. Genehmigungs-IDs mit dem Präfix plugin: werden über Plugin-Genehmigungen aufgelöst; andere werden zuerst über Exec-Genehmigungen aufgelöst.

Siehe Exec-Genehmigungen.

• Wenn requireMention=false ist, muss der Telegram-Privatsphäremodus 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; die Wildcard "*" kann nicht per Mitgliedschaftsprobe 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 Protokolle: openclaw logs --follow für Gründe für das Überspringen.

• Autorisieren Sie Ihre Senderidentität (Pairing und/oder numerisches allowFrom).
• 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-Tippaufrufe sind begrenzt und werden bei Anfrage-Timeout einmal über Telegrams Transport-Fallback wiederholt. Dauerhafte Netzwerk-/Fetch-Fehler deuten normalerweise auf DNS-/HTTPS-Erreichbarkeitsprobleme zu api.telegram.org hin.

• getMe returned 401 ist ein Telegram-Authentifizierungsfehler für das konfigurierte Bot-Token.
• Kopieren oder regenerieren Sie das Bot-Token in BotFather erneut, 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; es als „kein Webhook vorhanden“ zu behandeln, würde denselben Fehler durch ein ungültiges Token nur auf spätere API-Aufrufe verschieben.

• Node 22+ und benutzerdefiniertes Fetch/Proxy können sofortiges Abbruchverhalten auslösen, wenn AbortSignal-Typen nicht übereinstimmen.
• Einige Hosts lösen api.telegram.org zuerst zu IPv6 auf; defekter IPv6-Egress kann sporadische Telegram-API-Fehler verursachen.
• Wenn Protokolle TypeError: fetch failed oder Network request for 'getUpdates' failed! enthalten, wiederholt OpenClaw diese jetzt als wiederherstellbare Netzwerkfehler.
• Während des Polling-Starts verwendet OpenClaw die erfolgreiche getMe-Startprobe 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 vorübergehenden Netzwerkfehler fehlschlägt, fährt OpenClaw mit Long Polling fort, statt einen weiteren Control-Plane-Aufruf vor dem Polling auszuführen. Ein weiterhin aktiver Webhook erscheint als getUpdates-Konflikt; OpenClaw baut dann den Telegram-Transport neu auf und wiederholt die Webhook-Bereinigung.
• Wenn Telegram-Sockets in einem kurzen festen Intervall recycelt werden, prüfen Sie auf ein niedriges channels.telegram.timeoutSeconds; Bot-Clients begrenzen konfigurierte Werte unterhalb der ausgehenden und getUpdates-Request-Guards, aber ältere Versionen konnten jeden Poll oder jede Antwort abbrechen, wenn dies unterhalb dieser Guards gesetzt war.
• Wenn Protokolle Polling stall detected enthalten, startet OpenClaw das Polling neu und baut den Telegram-Transport standardmäßig nach 120 Sekunden ohne abgeschlossene Long-Poll-Liveness neu auf.
• openclaw channels status --probe und openclaw doctor warnen, wenn ein laufendes Polling-Konto nach der Start-Gnadenfrist getUpdates nicht abgeschlossen hat, wenn ein laufendes Webhook-Konto nach der Start-Gnadenfrist setWebhook 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 gesund sind, Ihr Host aber weiterhin fälschliche Polling-Stall-Neustarts meldet. Dauerhafte Stalls deuten normalerweise auf Proxy-, DNS-, IPv6- oder TLS-Egress-Probleme zwischen Host und api.telegram.org hin.
• Telegram berücksichtigt außerdem Prozess-Proxy-Env für den Bot-API-Transport, einschließlich HTTP_PROXY, HTTPS_PROXY, ALL_PROXY und ihrer kleingeschriebenen Varianten. NO_PROXY / no_proxy kann api.telegram.org weiterhin umgehen.
• Wenn der von OpenClaw verwaltete Proxy über OPENCLAW_PROXY_URL für eine Service-Umgebung konfiguriert ist und keine Standard-Proxy-Env 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 Ergebnisreihenfolge von Telegram-DNS 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 gilt, 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 Family-Auswahl:

channels:
telegram:
network:
  autoSelectFamily: false

• Antworten aus dem RFC-2544-Benchmark-Bereich (198.18.0.0/15) sind standardmäßig bereits für Telegram-Mediendownloads 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 sich für die nur für Telegram geltende Umgehung entscheiden:

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