Telegram

• wyłącz tryb prywatności przez /setprivacy, albo
• ustaw bota jako administratora grupy.

• /setjoingroups, aby zezwolić na dodawanie do grup lub go zabronić
• /setprivacy dla zachowania widoczności w grupach

• czaty bezpośrednie: wiadomość podglądu + editMessageText
• grupy/tematy: wiadomość podglądu + editMessageText

• channels.telegram.streaming to off | partial | block | progress (domyślnie: partial)
• progress utrzymuje jedną edytowalną wersję roboczą statusu dla postępu narzędzi, czyści ją po zakończeniu i wysyła końcową odpowiedź jako zwykłą wiadomość
• streaming.preview.toolProgress kontroluje, czy aktualizacje narzędzi/postępu ponownie używają tej samej edytowanej wiadomości podglądu (domyślnie: true, gdy aktywne jest strumieniowanie podglądu)
• streaming.preview.commandText kontroluje szczegóły poleceń/wykonania w tych wierszach postępu narzędzi: raw (domyślnie, zachowuje opublikowane zachowanie) albo status (tylko etykieta narzędzia)
• starsze wartości channels.telegram.streamMode oraz logiczne wartości streaming są wykrywane; uruchom openclaw doctor --fix, aby zmigrować je do channels.telegram.streaming.mode

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

• krótkie podglądy DM/grupy/tematu: OpenClaw zachowuje tę samą wiadomość podglądu i wykonuje końcową edycję w miejscu
• długie końcowe teksty dzielone na wiele wiadomości Telegram ponownie używają istniejącego podglądu jako pierwszego końcowego fragmentu, gdy to możliwe, a następnie wysyłają tylko pozostałe fragmenty
• odpowiedzi końcowe w trybie postępu czyszczą wersję roboczą statusu i używają normalnego dostarczania końcowego zamiast edytować wersję roboczą w odpowiedź
• jeśli końcowa edycja nie powiedzie się, zanim ukończony tekst zostanie potwierdzony, OpenClaw używa normalnego dostarczania końcowego i czyści nieaktualny podgląd

• /reasoning stream wysyła rozumowanie do podglądu na żywo podczas generowania
• podgląd rozumowania jest usuwany po dostarczeniu końcowym; użyj /reasoning on, gdy rozumowanie ma pozostać widoczne
• końcowa odpowiedź jest wysyłana bez tekstu rozumowania

• Tekst podobny do Markdown jest renderowany do HTML bezpiecznego dla Telegram.
• Obsługiwane tagi HTML Telegram są zachowywane; nieobsługiwany HTML jest escapowany.
• Jeśli Telegram odrzuci przetworzony HTML, OpenClaw ponawia próbę jako zwykły tekst.

• commands.native: "auto" włącza natywne polecenia dla Telegram

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

• nazwy są normalizowane (usunięcie początkowego /, małe litery)
• prawidłowy wzorzec: a-z, 0-9, _, długość 1..32
• polecenia niestandardowe nie mogą zastępować poleceń natywnych
• konflikty/duplikaty są pomijane i logowane

• polecenia niestandardowe są wyłącznie wpisami menu; nie implementują automatycznie zachowania
• polecenia Plugin/skill nadal mogą działać po wpisaniu, nawet jeśli nie są pokazane w menu Telegram

• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że menu Telegram nadal przepełniło się po przycięciu; zmniejsz liczbę poleceń Plugin/skill/niestandardowych albo wyłącz channels.telegram.commands.native.
• Niepowodzenie deleteWebhook, deleteMyCommands albo setMyCommands z 404: Not Found, gdy bezpośrednie polecenia curl Bot API działają, może oznaczać, że channels.telegram.apiRoot ustawiono na pełny punkt końcowy /bot<TOKEN>. apiRoot musi być tylko korzeniem Bot API, a openclaw doctor --fix usuwa przypadkowy końcowy /bot<TOKEN>.
• getMe returned 401 oznacza, że Telegram odrzucił skonfigurowany token bota. Zaktualizuj botToken, tokenFile albo TELEGRAM_BOT_TOKEN bieżącym tokenem BotFather; OpenClaw zatrzymuje się przed odpytywaniem, więc nie jest to zgłaszane jako niepowodzenie czyszczenia Webhook.
• setMyCommands failed z błędami sieci/fetch zwykle oznacza, że wychodzący DNS/HTTPS do api.telegram.org jest zablokowany.

​

Polecenia parowania urządzenia (Plugin device-pair)

1. /pair generuje kod konfiguracji
2. wklej kod w aplikacji iOS
3. /pair pending wyświetla oczekujące żądania (w tym rolę/zakresy)
4. zatwierdź żądanie:
   • /pair approve <requestId> dla jawnego zatwierdzenia
   • /pair approve, gdy istnieje tylko jedno oczekujące żądanie
   • /pair approve latest dla najnowszego

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

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

• off
• dm
• group
• all
• allowlist (domyślnie)

{
  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, opcjonalnie mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, opcjonalnie iconColor, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (domyślnie: wyłączone)

• [[reply_to_current]] odpowiada na wiadomość wyzwalającą
• [[reply_to:<id>]] odpowiada na konkretny identyfikator wiadomości Telegram

• off (domyślnie)
• first
• all

• klucze sesji tematu dodają :topic:<threadId>
• odpowiedzi i wskaźnik pisania celują w wątek tematu
• ścieżka konfiguracji tematu: channels.telegram.groups.<chatId>.topics.<threadId>

• wysyłki wiadomości pomijają message_thread_id (Telegram odrzuca sendMessage(...thread_id=1))
• akcje pisania nadal zawierają 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
          }
        }
      }
    }
  }
}

​

Wiadomości audio

• domyślnie: zachowanie pliku audio
• znacznik [[audio_as_voice]] w odpowiedzi agenta wymusza wysłanie notatki głosowej
• transkrypcje przychodzących notatek głosowych są ujmowane w kontekście agenta jako tekst wygenerowany maszynowo i niezaufany; wykrywanie wzmianek nadal używa surowej transkrypcji, więc wiadomości głosowe wymagające wzmianki nadal działają.

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

​

Wiadomości wideo

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

​

Naklejki

• statyczny WEBP: pobierany i przetwarzany (placeholder <media:sticker>)
• animowany TGS: pomijany
• wideo WEBM: pomijane

• 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 (domyślnie: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (domyślnie: minimal)

• own oznacza tylko reakcje użytkowników na wiadomości wysłane przez bota (best effort za pomocą pamięci podręcznej wysłanych wiadomości).
• Zdarzenia reakcji nadal respektują kontrole dostępu Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); nieautoryzowani nadawcy są odrzucani.
• Telegram nie udostępnia identyfikatorów wątków w aktualizacjach reakcji.
  • grupy nieforumowe są trasowane do sesji czatu grupowego
  • grupy forumowe są trasowane do sesji ogólnego tematu grupy (:topic:1), a nie do dokładnego tematu źródłowego

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• awaryjnie emoji tożsamości agenta (agents.list[].identity.emoji, w przeciwnym razie ”👀”)

• Telegram oczekuje emoji Unicode (na przykład ”👀”).
• Użyj "", aby wyłączyć reakcję dla kanału lub konta.

• zdarzenia migracji grup (migrate_to_chat_id) aktualizujące channels.telegram.groups
• /config set i /config unset (wymaga włączenia polecenia)

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

• Domyślna wartość channels.telegram.textChunkLimit to 4000.
• channels.telegram.chunkMode="newline" preferuje granice akapitów (puste wiersze) przed dzieleniem według długości.
• channels.telegram.mediaMaxMb (domyślnie 100) ogranicza rozmiar przychodzących i wychodzących multimediów Telegram.
• channels.telegram.mediaGroupFlushMs (domyślnie 500) kontroluje, jak długo albumy/grupy multimediów Telegram są buforowane, zanim OpenClaw przekaże je jako jedną wiadomość przychodzącą. Zwiększ tę wartość, jeśli części albumu przychodzą późno; zmniejsz ją, aby skrócić opóźnienie odpowiedzi na album.
• channels.telegram.timeoutSeconds nadpisuje limit czasu klienta API Telegram (jeśli nie ustawiono, obowiązuje domyślna wartość grammY). Klienci botów ograniczają skonfigurowane wartości poniżej 60-sekundowej osłony żądań tekstu wychodzącego/wpisywania, aby grammY nie przerwał widocznego dostarczenia odpowiedzi, zanim zadziała osłona transportowa i mechanizm awaryjny OpenClaw. Long polling nadal używa 45-sekundowej osłony żądania getUpdates, aby bezczynne sondowania nie były porzucane bezterminowo.
• channels.telegram.pollingStallThresholdMs domyślnie wynosi 120000; dostrajaj w zakresie od 30000 do 600000 tylko przy fałszywie dodatnich restartach z powodu zastoju pollingu.
• historia kontekstu grupy używa channels.telegram.historyLimit albo messages.groupChat.historyLimit (domyślnie 50); 0 wyłącza.
• dodatkowy kontekst odpowiedzi/cytatu/przekazania jest normalizowany do jednego wybranego okna kontekstu rozmowy, gdy Gateway zaobserwował wiadomości nadrzędne; pamięć podręczna zaobserwowanych wiadomości jest utrwalana obok magazynu sesji. Telegram dołącza w aktualizacjach tylko jedno płytkie reply_to_message, więc łańcuchy starsze niż pamięć podręczna są ograniczone do bieżącego ładunku aktualizacji Telegram.
• listy dozwolonych Telegram przede wszystkim ograniczają, kto może wywołać agenta, a nie stanowią pełnej granicy redakcji dodatkowego kontekstu.
• kontrolki historii DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• konfiguracja channels.telegram.retry ma zastosowanie do helperów wysyłania Telegram (CLI/narzędzia/akcje) dla możliwych do odzyskania błędów wychodzącego API. Dostarczanie końcowych odpowiedzi przychodzących również używa ograniczonego ponowienia bezpiecznego wysyłania dla awarii Telegram przed połączeniem, ale nie ponawia niejednoznacznych kopert sieciowych po wysłaniu, które mogłyby zduplikować widoczne wiadomości.

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 dla tematów forum (albo użyj celu :topic:)

• --presentation z blokami buttons dla klawiatur inline, gdy channels.telegram.capabilities.inlineButtons na to pozwala
• --pin albo --delivery '{"pin":true}', aby zażądać przypiętego dostarczenia, gdy bot może przypinać w tym czacie
• --force-document, aby wysyłać wychodzące obrazy, GIF-y i filmy jako dokumenty zamiast skompresowanych zdjęć, animowanych multimediów lub przesyłanych filmów

• channels.telegram.actions.sendMessage=false wyłącza wychodzące wiadomości Telegram, w tym pollingi
• channels.telegram.actions.poll=false wyłącza tworzenie pollingów Telegram, pozostawiając zwykłe wysyłanie włączone

• channels.telegram.execApprovals.enabled (włącza się automatycznie, gdy można rozpoznać co najmniej jednego zatwierdzającego)
• channels.telegram.execApprovals.approvers (wraca do numerycznych ID właścicieli z commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (domyślnie) | channel | both
• agentFilter, sessionFilter

• Jeśli requireMention=false, tryb prywatności Telegram musi zezwalać na pełną widoczność.
  • BotFather: /setprivacy -> Wyłącz
  • następnie usuń bota z grupy i dodaj go ponownie
• openclaw channels status ostrzega, gdy konfiguracja oczekuje wiadomości grupowych bez wzmianki.
• openclaw channels status --probe może sprawdzać jawne numeryczne identyfikatory grup; wildcard "*" nie może zostać sprawdzony pod kątem członkostwa.
• szybki test sesji: /activation always.

• gdy istnieje channels.telegram.groups, grupa musi być wymieniona (albo zawierać "*")
• zweryfikuj członkostwo bota w grupie
• przejrzyj logi: openclaw logs --follow, aby znaleźć przyczyny pominięcia

• autoryzuj swoją tożsamość nadawcy (parowanie i/lub numeryczne allowFrom)
• autoryzacja poleceń nadal obowiązuje nawet wtedy, gdy polityka grupy to open
• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że natywne menu ma zbyt wiele pozycji; ogranicz polecenia plugin/skill/niestandardowe albo wyłącz natywne menu
• wywołania startowe deleteMyCommands / setMyCommands oraz wywołania pisania sendChatAction są ograniczone czasowo i ponawiane raz przez zapasowy transport Telegram przy przekroczeniu limitu czasu żądania. Trwałe błędy sieciowe/fetch zwykle wskazują na problemy z dostępnością DNS/HTTPS do api.telegram.org

• getMe returned 401 to błąd uwierzytelniania Telegram dla skonfigurowanego tokena bota.
• Skopiuj ponownie albo wygeneruj ponownie token bota w BotFather, a następnie zaktualizuj channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken albo TELEGRAM_BOT_TOKEN dla konta domyślnego.
• deleteWebhook 401 Unauthorized podczas uruchamiania również jest błędem uwierzytelniania; potraktowanie go jako „brak istniejącego webhooka” tylko odroczyłoby ten sam błąd złego tokena do późniejszych wywołań API.

• Node 22+ i niestandardowy fetch/proxy mogą wywołać natychmiastowe przerwanie, jeśli typy AbortSignal się nie zgadzają.
• Niektóre hosty najpierw rozwiązują api.telegram.org do IPv6; uszkodzony ruch wychodzący IPv6 może powodować przerywane awarie API Telegram.
• Jeśli logi zawierają TypeError: fetch failed albo Network request for 'getUpdates' failed!, OpenClaw ponawia je teraz jako możliwe do odzyskania błędy sieciowe.
• Podczas uruchamiania odpytywania OpenClaw ponownie używa udanego startowego sprawdzenia getMe dla grammY, aby runner nie potrzebował drugiego getMe przed pierwszym getUpdates.
• Jeśli deleteWebhook zakończy się przejściowym błędem sieciowym podczas uruchamiania odpytywania, OpenClaw przechodzi do długiego odpytywania zamiast wykonywać kolejne przedodpytywające wywołanie control-plane. Nadal aktywny webhook ujawnia się jako konflikt getUpdates; OpenClaw przebudowuje wtedy transport Telegram i ponawia czyszczenie webhooka.
• Jeśli gniazda Telegram są odtwarzane w krótkim stałym cyklu, sprawdź, czy channels.telegram.timeoutSeconds nie jest niskie; klienci botów ograniczają skonfigurowane wartości poniżej zabezpieczeń żądań wychodzących i getUpdates, ale starsze wydania mogły przerywać każde odpytywanie lub odpowiedź, gdy ustawiono to poniżej tych zabezpieczeń.
• Jeśli logi zawierają Polling stall detected, OpenClaw domyślnie restartuje odpytywanie i przebudowuje transport Telegram po 120 sekundach bez zakończonej żywotności długiego odpytywania.
• openclaw channels status --probe i openclaw doctor ostrzegają, gdy działające konto odpytywania nie zakończyło getUpdates po okresie rozruchowym, gdy działające konto webhooka nie zakończyło setWebhook po okresie rozruchowym albo gdy ostatnia udana aktywność transportu odpytywania jest przestarzała.
• Zwiększ channels.telegram.pollingStallThresholdMs tylko wtedy, gdy długotrwałe wywołania getUpdates są zdrowe, ale host nadal zgłasza fałszywe restarty z powodu zastoju odpytywania. Trwałe zastoje zwykle wskazują na problemy z proxy, DNS, IPv6 albo ruchem wychodzącym TLS między hostem a api.telegram.org.
• Telegram honoruje też zmienne środowiskowe proxy procesu dla transportu Bot API, w tym HTTP_PROXY, HTTPS_PROXY, ALL_PROXY oraz ich warianty pisane małymi literami. NO_PROXY / no_proxy nadal mogą omijać api.telegram.org.
• Jeśli zarządzane proxy OpenClaw jest skonfigurowane przez OPENCLAW_PROXY_URL dla środowiska usługi i nie ma standardowej zmiennej środowiskowej proxy, Telegram używa tego URL również dla transportu Bot API.
• Na hostach VPS z niestabilnym bezpośrednim ruchem wychodzącym/TLS kieruj wywołania API Telegram przez channels.telegram.proxy:

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

• Node 22+ domyślnie ustawia autoSelectFamily=true (z wyjątkiem WSL2). Kolejność wyników DNS Telegram honoruje OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, następnie channels.telegram.network.dnsResultOrder, a następnie domyślne ustawienie procesu, takie jak NODE_OPTIONS=--dns-result-order=ipv4first; jeśli żadne nie ma zastosowania, Node 22+ wraca do ipv4first.
• Jeśli Twój host to WSL2 albo wyraźnie działa lepiej z zachowaniem tylko IPv4, wymuś wybór rodziny:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Odpowiedzi z zakresu benchmarkowego RFC 2544 (198.18.0.0/15) są już domyślnie dozwolone dla pobierania multimediów Telegram. Jeśli zaufane fake-IP albo transparentne proxy przepisuje api.telegram.org na inny adres prywatny/wewnętrzny/specjalnego użycia podczas pobierania multimediów, możesz włączyć obejście tylko dla Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• To samo włączenie jest dostępne dla każdego konta pod channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Jeśli Twoje proxy rozwiązuje hosty multimediów Telegram do 198.18.x.x, najpierw pozostaw niebezpieczną flagę wyłączoną. Multimedia Telegram już domyślnie dopuszczają zakres benchmarkowy RFC 2544.

• Nadpisania środowiskowe (tymczasowe):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Zweryfikuj odpowiedzi DNS:

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