Telegram (Bot API)

Telegram-Bots nutzen standardmäßig den **Privacy-Modus**, der einschränkt, welche Gruppennachrichten sie empfangen.

Soll der Bot alle Gruppennachrichten sehen, gibt es zwei Möglichkeiten:

- Privacy-Modus über `/setprivacy` deaktivieren, oder
- den Bot zum Gruppenadmin machen.

Nach dem Umschalten des Privacy-Modus musst du den Bot in jeder Gruppe entfernen und neu hinzufügen, damit Telegram die Änderung übernimmt.

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

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

- `/setjoingroups` um Gruppen-Einladungen zu erlauben/verweigern
- `/setprivacy` für das Gruppen-Sichtbarkeitsverhalten

OpenClaw kann Teilantworten in Echtzeit streamen:

- Direkt-Chats: Vorschaunachricht + `editMessageText`
- Gruppen/Topics: Vorschaunachricht + `editMessageText`

Voraussetzung:

- `channels.telegram.streaming` ist `off | partial | block | progress` (Standard: `partial`)
- `progress` wird auf Telegram auf `partial` abgebildet (Kompatibilität mit kanalübergreifender Benennung)
- Legacy `channels.telegram.streamMode` und boolesche `streaming`-Werte werden automatisch gemappt

Für reine Textantworten:

- DM: OpenClaw behält dieselbe Vorschaunachricht bei und führt am Ende eine finale Bearbeitung durch (keine zweite Nachricht)
- Gruppe/Topic: OpenClaw behält dieselbe Vorschaunachricht bei und führt am Ende eine finale Bearbeitung durch (keine zweite Nachricht)

Bei komplexen Antworten (z. B. Medien-Payloads) fällt OpenClaw auf normale finale Zustellung zurück und räumt dann die Vorschaunachricht auf.

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

Ist der native Draft-Transport nicht verfügbar/abgelehnt, fällt OpenClaw automatisch auf `sendMessage` + `editMessageText` zurück.

Telegram-exklusiver Reasoning-Stream:

- `/reasoning stream` sendet Reasoning-Ausgabe in die Live-Vorschau während der Generierung
- Die finale Antwort wird ohne Reasoning-Text gesendet

Ausgehender Text nutzt Telegram `parse_mode: "HTML"`.

- Markdown-artiger Text wird zu Telegram-sicherem HTML gerendert.
- Rohes Modell-HTML wird escaped, um Telegram-Parse-Fehler zu reduzieren.
- Lehnt Telegram das geparste HTML ab, versucht OpenClaw es als Plaintext erneut.

Link-Vorschauen sind standardmäßig aktiviert und können mit `channels.telegram.linkPreview: false` deaktiviert werden.

Telegram-Befehlsmenü-Registrierung erfolgt beim Start über `setMyCommands`.

Native Befehlsstandards:

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

Benutzerdefinierte Menüeinträge hinzufügen:

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

Regeln:

- Namen werden normalisiert (führendes `/` wird entfernt, 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 geloggt

Hinweise:

- Benutzerdefinierte Befehle sind nur Menüeinträge; sie implementieren kein automatisches Verhalten
- Plugin-/Skill-Befehle können weiterhin funktionieren, wenn eingetippt, auch wenn sie nicht im Telegram-Menü erscheinen

Werden native Befehle deaktiviert, werden Built-ins entfernt. Benutzerdefinierte/Plugin-Befehle können sich trotzdem registrieren, wenn konfiguriert.

Häufige Einrichtungsfehler:

- `setMyCommands failed` mit `BOT_COMMANDS_TOO_MUCH` bedeutet, das Telegram-Menü ist nach dem Trimmen immer noch überlaufen; reduziere Plugin-/Skill-/benutzerdefinierte Befehle oder deaktiviere `channels.telegram.commands.native`.
- `setMyCommands failed` mit Netzwerk-/Fetch-Fehlern bedeutet meist, dass ausgehende DNS/HTTPS-Verbindungen zu `api.telegram.org` blockiert sind.

### Device-Pairing-Befehle (`device-pair`-Plugin)

Wenn das `device-pair`-Plugin installiert ist:

1. `/pair` generiert einen Setup-Code
2. Code in der iOS-App einfügen
3. `/pair approve` genehmigt die letzte ausstehende Anfrage

Weitere Details: [Pairing](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

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)

Legacy `capabilities: ["inlineButtons"]` wird auf `inlineButtons: "all"` gemappt.

Nachrichtenaktion-Beispiel:

{
  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 weitergegeben:
`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`)

Kanal-Nachrichtenaktionen bieten ergonomische Aliase (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

Gating-Steuerungen:

- `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.
Laufzeit-Sends nutzen den aktiven Config-/Secrets-Snapshot (Startup/Reload), sodass Action-Pfade keine Ad-hoc-SecretRef-Neuauflösung pro Send durchführen.

Semantik zum Entfernen von Reaktionen: [/tools/reactions](/docs/tools/reactions)

Telegram unterstützt explizite Reply-Threading-Tags in der generierten 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`

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

Forum-Supergruppen:

- Topic-Session-Keys hängen `:topic:<threadId>` an
- Antworten und Typing-Indikatoren zielen auf den Topic-Thread
- Topic-Config-Pfad:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

General-Topic (`threadId=1`) Sonderfall:

- Nachrichten-Sends lassen `message_thread_id` weg (Telegram lehnt `sendMessage(...thread_id=1)` ab)
- Typing-Actions enthalten weiterhin `message_thread_id`

Topic-Vererbung: Topic-Einträge erben Gruppeneinstellungen, sofern nicht überschrieben (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` ist topic-spezifisch und erbt nicht von Gruppen-Defaults.

**Per-Topic-Agent-Routing**: Jedes Topic kann über `agentId` in der Topic-Config an einen anderen Agenten geroutet werden. So bekommt jedes Topic seinen eigenen isolierten Workspace, Speicher und Sitzung. Beispiel:

```json5
{
  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 Topic hat dann seinen eigenen Session-Key: `agent:zu:telegram:group:-1001234567890:topic:3`

**Persistente ACP-Topic-Bindung**: Forum-Topics können ACP-Harness-Sitzungen über Top-Level-ACP-Bindings mit Typ pinnen:

- `bindings[]` mit `type: "acp"` und `match.channel: "telegram"`

Beispiel:

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
```

Das ist derzeit auf Forum-Topics in Gruppen und Supergruppen beschränkt.

**Thread-gebundener ACP-Spawn aus dem Chat**:

- `/acp spawn <agent> --thread here|auto` kann das aktuelle Telegram-Topic an eine neue ACP-Sitzung binden.
- Folgenachrichten im Topic werden direkt an die gebundene ACP-Sitzung geroutet (kein `/acp steer` nötig).
- OpenClaw pinnt die Spawn-Bestätigungsnachricht im Topic nach einer erfolgreichen Bindung.
- Erfordert `channels.telegram.threadBindings.spawnAcpSessions=true`.

Template-Kontext enthält:

- `MessageThreadId`
- `IsForum`

DM-Thread-Verhalten:

- Private Chats mit `message_thread_id` behalten DM-Routing bei, verwenden aber thread-aware Session-Keys/Reply-Targets.

### Audionachrichten

Telegram unterscheidet zwischen Sprachnotizen und Audiodateien.

- Standard: Audiodatei-Verhalten
- Tag `[[audio_as_voice]]` in der Agent-Antwort, um den Versand als Sprachnotiz zu erzwingen

Nachrichtenaktion-Beispiel:

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

### Videonachrichten

Telegram unterscheidet zwischen Videodateien und Videonotizen.

Nachrichtenaktion-Beispiel:

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

Videonotizen unterstützen keine Untertitel; mitgegebener Nachrichtentext wird separat gesendet.

### Sticker

Eingehende Sticker-Verarbeitung:

- Statisch WEBP: wird heruntergeladen und verarbeitet (Platzhalter `<media:sticker>`)
- Animiert TGS: wird übersprungen
- Video WEBM: wird ü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 gecacht, um wiederholte Vision-Aufrufe zu reduzieren.

Sticker-Aktionen aktivieren:

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

Sticker senden:

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

Gecachte Sticker durchsuchen:

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

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

Wenn aktiviert, reiht OpenClaw System-Events ein wie:

- `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 Benutzerreaktionen nur auf vom Bot gesendete Nachrichten (Best-Effort via Sent-Message-Cache).
- Reaktions-Events respektieren weiterhin die Telegram-Zugriffskontrolle (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); nicht autorisierte Absender werden verworfen.
- Telegram liefert keine Thread-IDs in Reaktions-Updates.
  - Nicht-Forum-Gruppen routen zur Gruppen-Chat-Sitzung
  - Forum-Gruppen routen zur General-Topic-Sitzung (`:topic:1`), nicht zum exakten Ursprungs-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-Identity-Emoji-Fallback (`agents.list[].identity.emoji`, sonst "👀")

Hinweise:

- Telegram erwartet Unicode-Emoji (z. B. "👀").
- Verwende `""`, um die Reaktion für einen Kanal oder ein Konto zu deaktivieren.

Kanal-Config-Schreibvorgänge sind standardmäßig aktiviert (`configWrites !== false`).

Von Telegram ausgelöste Schreibvorgänge umfassen:

- Gruppen-Migrationsereignisse (`migrate_to_chat_id`) zum Aktualisieren von `channels.telegram.groups`
- `/config set` und `/config unset` (erfordert Befehlsaktivierung)

Deaktivieren:

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

Standard: Long Polling.

Webhook-Modus:

- setze `channels.telegram.webhookUrl`
- setze `channels.telegram.webhookSecret` (erforderlich wenn Webhook-URL gesetzt)
- optional `channels.telegram.webhookPath` (Standard `/telegram-webhook`)
- optional `channels.telegram.webhookHost` (Standard `127.0.0.1`)
- optional `channels.telegram.webhookPort` (Standard `8787`)

Der Standard-lokale Listener für den Webhook-Modus bindet an `127.0.0.1:8787`.

Weicht dein öffentlicher Endpunkt ab, stelle einen Reverse-Proxy davor und richte `webhookUrl` auf die öffentliche URL.
Setze `webhookHost` (z. B. `0.0.0.0`), wenn du bewusst externen Zugriff brauchst.

- `channels.telegram.textChunkLimit` Standard ist 4000.
- `channels.telegram.chunkMode="newline"` bevorzugt Absatzgrenzen (Leerzeilen) vor der Längenteilung.
- `channels.telegram.mediaMaxMb` (Standard 100) begrenzt ein-/ausgehende Telegram-Mediengrößen.
- `channels.telegram.timeoutSeconds` überschreibt das Telegram-API-Client-Timeout (nicht gesetzt: grammY-Standard).
- Gruppenkontextverlauf nutzt `channels.telegram.historyLimit` oder `messages.groupChat.historyLimit` (Standard 50); `0` deaktiviert.
- DM-Verlaufssteuerung:
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry`-Config gilt für Telegram-Send-Helfer (CLI/Tools/Aktionen) bei behebbaren ausgehenden API-Fehlern.

CLI-Sendeziel kann numerische Chat-ID oder Username sein:

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Telegram-Umfragen nutzen `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

Telegram-spezifische Poll-Flags:

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

Action-Gating:

- `channels.telegram.actions.sendMessage=false` deaktiviert ausgehende Telegram-Nachrichten, einschließlich Polls
- `channels.telegram.actions.poll=false` deaktiviert die Telegram-Poll-Erstellung, lässt aber reguläre Sends aktiviert

Telegram unterstützt Exec-Genehmigungen in den DMs der Genehmiger und kann optional Genehmigungsaufforderungen im Ursprungs-Chat oder -Topic anzeigen.

Config-Pfad:

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`)
- `agentFilter`, `sessionFilter`

Genehmiger müssen numerische Telegram-User-IDs sein. Ist `enabled` false oder `approvers` leer, agiert Telegram nicht als Exec-Approval-Client. Genehmigungsanfragen fallen auf andere konfigurierte Genehmigungswege oder die Exec-Approval-Fallback-Richtlinie zurück.

Zustellungsregeln:

- `target: "dm"` sendet Genehmigungsaufforderungen nur an konfigurierte Genehmiger-DMs
- `target: "channel"` sendet die Aufforderung zurück in den Ursprungs-Chat/das Ursprungs-Topic
- `target: "both"` sendet an Genehmiger-DMs und den Ursprungs-Chat/das Ursprungs-Topic

Nur konfigurierte Genehmiger können genehmigen oder ablehnen. Nicht-Genehmiger können `/approve` nicht nutzen und auch keine Telegram-Genehmigungsbuttons verwenden.

Kanal-Zustellung zeigt den Befehlstext im Chat, aktiviere `channel` oder `both` daher nur in vertrauenswürdigen Gruppen/Topics. Landet die Aufforderung in einem Forum-Topic, bewahrt OpenClaw das Topic sowohl für die Genehmigungsaufforderung als auch das Follow-up nach Genehmigung.

Inline-Genehmigungsbuttons hängen zudem von `channels.telegram.capabilities.inlineButtons` ab, das die Zieloberfläche erlauben muss (`dm`, `group` oder `all`).

Verwandte Docs: [Exec-Genehmigungen](/docs/tools/exec-approvals)

- Wenn `requireMention=false`, muss der Telegram-Privacy-Modus volle Sichtbarkeit erlauben.
  - BotFather: `/setprivacy` -> Disable
  - dann Bot aus der Gruppe entfernen und neu hinzufügen
- `openclaw channels status` warnt, wenn die Config unerwähnte Gruppennachrichten erwartet.
- `openclaw channels status --probe` kann explizite numerische Gruppen-IDs prüfen; Wildcard `"*"` kann nicht per Mitgliedschaft geprobt werden.
- Schneller Sitzungstest: `/activation always`.

- Wenn `channels.telegram.groups` existiert, muss die Gruppe aufgelistet sein (oder `"*"` enthalten)
- Prüfe die Bot-Mitgliedschaft in der Gruppe
- Prüfe Logs: `openclaw logs --follow` für Skip-Gründe

- Autorisiere deine Absenderidentität (Pairing und/oder numerische `allowFrom`)
- Befehlsautorisierung greift auch bei `groupPolicy: "open"`
- `setMyCommands failed` mit `BOT_COMMANDS_TOO_MUCH` bedeutet, das native Menü hat zu viele Einträge; reduziere Plugin-/Skill-/benutzerdefinierte Befehle oder deaktiviere native Menüs
- `setMyCommands failed` mit Netzwerk-/Fetch-Fehlern deutet meist auf DNS-/HTTPS-Erreichbarkeitsprobleme zu `api.telegram.org` hin

- Node 22+ + custom fetch/proxy kann bei AbortSignal-Typ-Diskrepanzen sofortiges Abbruchverhalten auslösen.
- Manche Hosts lösen `api.telegram.org` zuerst auf IPv6 auf; defekter IPv6-Egress kann zu intermittierenden Telegram-API-Fehlern führen.
- Enthalten die Logs `TypeError: fetch failed` oder `Network request for 'getUpdates' failed!`, behandelt OpenClaw diese jetzt als behebbare Netzwerkfehler mit Retry.
- Auf VPS-Hosts mit instabilem direktem Egress/TLS leite Telegram-API-Aufrufe über `channels.telegram.proxy`:

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

- Node 22+ setzt standardmäßig `autoSelectFamily=true` (außer WSL2) und `dnsResultOrder=ipv4first`.
- Funktioniert dein Host mit WSL2 oder explizit besser mit IPv4-only, erzwinge die Familienauswahl:

channels:
  telegram:
    network:
      autoSelectFamily: false

- Umgebungs-Overrides (temporär):
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- DNS-Antworten prüfen:

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