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

• /setjoingroups, um Gruppenbeitritte zu erlauben/verbieten
• /setprivacy für das Sichtbarkeitsverhalten in Gruppen

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

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

• DM: OpenClaw behält dieselbe Vorschaunachricht und führt zum Abschluss eine finale Bearbeitung an Ort und Stelle aus (keine zweite Nachricht)
• Gruppe/Topic: OpenClaw behält dieselbe Vorschaunachricht und führt zum Abschluss eine finale Bearbeitung an Ort und Stelle aus (keine zweite Nachricht)

• /reasoning stream sendet Reasoning während der Generierung an die Live-Vorschau
• die endgültige Antwort wird ohne Reasoning-Text gesendet

• Markdown-artiger 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.

• 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, kleinschreiben)
• 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 Verhalten nicht automatisch
• Plugin-/Skills-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 überläuft; reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie channels.telegram.commands.native.
• setMyCommands failed mit Netzwerk-/Fetch-Fehlern bedeutet gewöhnlich, dass ausgehendes DNS/HTTPS zu api.telegram.org blockiert ist.

​

Geräte-Pairing-Befehle (device-pair-Plugin)

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

{
  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

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

• Nachrichtensendungen lassen message_thread_id weg (Telegram lehnt sendMessage(...thread_id=1) ab)
• Typing-Aktionen 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
          }
        }
      }
    }
  }
}

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

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

• /acp spawn <agent> --thread here|auto kann das aktuelle Telegram-Topic an eine neue ACP-Sitzung binden.
• Nachfolgende Topic-Nachrichten werden direkt an die gebundene ACP-Sitzung weitergeleitet (kein /acp steer erforderlich).
• OpenClaw pinnt die Spawn-Bestätigungsnachricht nach erfolgreicher Bindung im Topic.
• Erfordert channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• private Chats mit message_thread_id behalten DM-Routing bei, verwenden aber threadbewusste Sitzungsschlüssel/Antwortziele.

​

Audionachrichten

• Standard: Verhalten von Audiodateien
• Tag [[audio_as_voice]] in der Agentenantwort, um das Senden als Sprachnachricht zu erzwingen

{
  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 beachten weiterhin die 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 Gruppenchatsitzung geroutet
  • Forum-Gruppen werden zur General-Topic-Sitzung der Gruppe (:topic:1) geroutet, nicht zum genauen Ursprungsthema

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• Fallback auf Agent-Identity-Emoji (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,
    },
  },
}

• setzen Sie channels.telegram.webhookUrl
• setzen Sie channels.telegram.webhookSecret (erforderlich, wenn eine Webhook-URL gesetzt ist)
• optional channels.telegram.webhookPath (Standard /telegram-webhook)
• optional channels.telegram.webhookHost (Standard 127.0.0.1)
• optional channels.telegram.webhookPort (Standard 8787)

• Standard für channels.telegram.textChunkLimit ist 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.timeoutSeconds überschreibt das Timeout des Telegram-API-Clients (wenn nicht gesetzt, gilt der grammY-Standard).
• Der Gruppenkontextverlauf verwendet channels.telegram.historyLimit oder messages.groupChat.historyLimit (Standard 50); 0 deaktiviert ihn.
• zusätzlicher Kontext für Antwort/Zitat/Weiterleitung wird derzeit unverändert weitergegeben.
• Telegram-Allowlists steuern in erster Linie, wer den Agenten auslösen kann, nicht eine vollständige Redaktionsgrenze für zusätzlichen Kontext.
• DM-Verlaufssteuerungen:
  • 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.

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

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)

• --buttons für Inline-Tastaturen, wenn channels.telegram.capabilities.inlineButtons dies für die Zieloberfläche erlaubt
• --force-document, um ausgehende Bilder und GIFs als Dokumente statt als komprimierte Fotos oder Uploads animierter Medien zu senden

• channels.telegram.actions.sendMessage=false deaktiviert ausgehende Telegram-Nachrichten, einschließlich Umfragen
• channels.telegram.actions.poll=false deaktiviert die Erstellung von Telegram-Umfragen, während normale Sendungen aktiviert bleiben

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (optional; verwendet, wenn möglich, numerische Eigentümer-IDs als Fallback, die aus allowFrom und direktem defaultTo abgeleitet werden)
• channels.telegram.execApprovals.target (dm | channel | both, Standard: dm)
• agentFilter, sessionFilter

• target: "dm" sendet Genehmigungsaufforderungen nur an aufgelöste Approver-DMs
• target: "channel" sendet die Aufforderung zurück in den auslösenden Telegram-Chat/das Topic
• target: "both" sendet an Approver-DMs und den auslösenden Chat/das Topic

• IDs mit Präfix plugin: werden immer über Plugin-Genehmigungen aufgelöst.
• Andere Genehmigungs-IDs versuchen zuerst exec.approval.resolve.
• Wenn Telegram auch für Plugin-Genehmigungen autorisiert ist und das Gateway meldet, dass die Exec-Genehmigung unbekannt/abgelaufen ist, versucht Telegram es einmal erneut über plugin.approval.resolve.
• Echte Ablehnungen/Fehler bei Exec-Genehmigungen fallen nicht stillschweigend auf die Plugin-Genehmigungsauflösung zurück.

• Wenn requireMention=false, muss der Telegram-Datenschutzmodus volle Sichtbarkeit erlauben.
  • BotFather: /setprivacy -> Deaktivieren
  • dann Bot aus der Gruppe entfernen und erneut hinzufügen
• 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 auf Mitgliedschaft geprüft werden.
• schneller Sitzungstest: /activation always.

• wenn channels.telegram.groups existiert, muss die Gruppe aufgeführt sein (oder "*" enthalten)
• Bot-Mitgliedschaft in der Gruppe prüfen
• Protokolle prüfen: openclaw logs --follow nach Gründen für das Überspringen

• autorisieren Sie Ihre Absenderidentitä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
• setMyCommands failed mit Netzwerk-/Fetch-Fehlern weist normalerweise auf DNS-/HTTPS-Erreichbarkeitsprobleme zu api.telegram.org hin

• Node 22+ + benutzerdefiniertes Fetch/Proxy kann sofortiges Abort-Verhalten auslösen, wenn AbortSignal-Typen nicht übereinstimmen.
• Einige Hosts lösen api.telegram.org zuerst zu IPv6 auf; fehlerhafter IPv6-Egress kann intermittierende Telegram-API-Fehler verursachen.
• Wenn Protokolle TypeError: fetch failed oder Network request for 'getUpdates' failed! enthalten, versucht OpenClaw diese nun als behebbare Netzwerkfehler erneut.
• Auf VPS-Hosts mit instabilem direktem Egress/TLS leiten Sie Telegram-API-Aufrufe über channels.telegram.proxy:

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

• Node 22+ verwendet standardmäßig autoSelectFamily=true (außer WSL2) und dnsResultOrder=ipv4first.
• Wenn Ihr Host WSL2 ist oder explizit besser mit IPv4-only-Verhalten funktioniert, erzwingen Sie die Familienauswahl:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Antworten aus dem RFC-2544-Benchmark-Bereich (198.18.0.0/15) sind bereits standardmäßig für Telegram-Mediendownloads erlaubt. Wenn ein vertrauenswürdiges Fake-IP- oder transparenter Proxy api.telegram.org bei 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 Aktivierung ist pro Konto verfügbar unter channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Wenn Ihr Proxy Telegram-Media-Hosts zu 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