Telegram

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

• /setjoingroups, aby zezwolić na dodawanie do grup lub je zablokować
• /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)
• krótkie początkowe podglądy odpowiedzi są debounce’owane, a następnie materializowane po ograniczonym opóźnieniu, jeśli uruchomienie jest nadal aktywne
• progress utrzymuje jeden edytowalny szkic statusu dla postępu narzędzi, pokazuje stabilną etykietę statusu, gdy aktywność odpowiedzi pojawia się przed postępem narzędzi, czyści go po ukończeniu i wysyła finalną 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 strumieniowanie podglądu jest aktywne)
• streaming.preview.commandText kontroluje szczegóły polecenia/wykonania w tych wierszach postępu narzędzi: raw (domyślnie, zachowuje wydane zachowanie) albo status (tylko etykieta narzędzia)
• streaming.progress.commentary (domyślnie: false) włącza tekst komentarza/preambuły asystenta w tymczasowym szkicu postępu
• starsze channels.telegram.streamMode, boolowskie wartości streaming i wycofane klucze natywnego podglądu szkicu są wykrywane; uruchom openclaw doctor --fix, aby zmigrować je do bieżącej konfiguracji strumieniowania

{
  "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 finalną edycję w miejscu
• długie finalne teksty, które dzielą się na wiele wiadomości Telegram, ponownie używają istniejącego podglądu jako pierwszego finalnego fragmentu, gdy to możliwe, a potem wysyłają tylko pozostałe fragmenty
• finalne odpowiedzi w trybie postępu czyszczą szkic statusu i używają normalnego dostarczania finalnego zamiast edytować szkic w odpowiedź
• jeśli finalna edycja nie powiedzie się przed potwierdzeniem ukończonego tekstu, OpenClaw używa normalnego dostarczania finalnego i czyści przestarzały podgląd

• /reasoning stream używa ścieżki podglądu rozumowania obsługiwanego kanału; w Telegram strumieniuje rozumowanie do podglądu na żywo podczas generowania
• podgląd rozumowania jest usuwany po dostarczeniu finalnym; użyj /reasoning on, gdy rozumowanie ma pozostać widoczne
• finalna odpowiedź jest wysyłana bez tekstu rozumowania

{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}

• Agent otrzymuje informację, że rozszerzone wiadomości Telegram są dostępne dla tego bota/konta.
• Tekst Markdown jest renderowany przez Markdown IR OpenClaw i wysyłany jako rozszerzony HTML Telegram.
• Jawne payloady rozszerzonego HTML zachowują obsługiwane tagi Bot API 10.1, takie jak nagłówki, tabele, szczegóły, rich media i formuły.
• Podpisy multimediów nadal używają podpisów HTML Telegram, ponieważ rozszerzone wiadomości nie zastępują podpisów.

• 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ą nadpisywać poleceń natywnych
• konflikty/duplikaty są pomijane i logowane

• polecenia niestandardowe są tylko wpisami menu; nie implementują automatycznie zachowania
• polecenia pluginów/Skills 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ów/Skills/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 endpoint /bot<TOKEN>. apiRoot musi być tylko korzeniem Bot API, a openclaw doctor --fix usuwa przypadkowe końcowe /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 pollingiem, więc nie jest to zgłaszane jako niepowodzenie czyszczenia webhooka.
• 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 jest 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" }],
  ],
}

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, opcjonalnie mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content lub caption, opcjonalne przyciski inline presentation; edycje samych przycisków aktualizują znaczniki odpowiedzi)
• 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 tematów dodają :topic:<threadId>
• odpowiedzi i sygnalizowanie pisania trafiają do wątku 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
• tag [[audio_as_voice]] w odpowiedzi agenta wymusza wysłanie jako 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 bramkowane wzmiankami 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

• statyczne WEBP: pobierane i przetwarzane (placeholder <media:sticker>)
• animowane TGS: pomijane
• wideo WEBM: pomijane

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

{
  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żytkownika na wiadomości wysłane przez bota (best-effort przez pamięć podręczną wysłanych wiadomości).
• Zdarzenia reakcji nadal respektują kontrolę 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ą kierowane do sesji czatu grupowego
  • grupy forumowe są kierowane 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
• awaryjne 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 grupy (migrate_to_chat_id) aktualizujące channels.telegram.groups
• /config set i /config unset (wymaga włączenia poleceń)

{
  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 multimediów przychodzących i wychodzących 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 docierają z opóźnieniem; zmniejsz ją, aby skrócić opóźnienie odpowiedzi albumu.
• channels.telegram.timeoutSeconds zastępuje 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-sekundowego zabezpieczenia żądań wychodzącego tekstu/wpisywania, aby grammY nie przerwał dostarczenia widocznej odpowiedzi, zanim uruchomi się zabezpieczenie transportu i mechanizm awaryjny OpenClaw. Długie odpytywanie nadal używa 45-sekundowego zabezpieczenia żądania getUpdates, aby bezczynne odpytywania nie były porzucane bez końca.
• channels.telegram.pollingStallThresholdMs ma domyślną wartość 120000; dostrajaj w zakresie od 30000 do 600000 tylko w przypadku fałszywie dodatnich restartów z powodu zastoju odpytywania.
• historia kontekstu grupy używa channels.telegram.historyLimit lub messages.groupChat.historyLimit (domyślnie 50); 0 wyłącza.
• dodatkowy kontekst odpowiedzi/cytatu/przekazania jest normalizowany do jednego wybranego okna kontekstu konwersacji, gdy gateway zaobserwował wiadomości nadrzędne; pamięć podręczna zaobserwowanych wiadomości znajduje się w stanie Plugin SQLite OpenClaw, a openclaw doctor --fix importuje starsze pliki pomocnicze. Telegram obejmuje w aktualizacjach tylko jeden płytki reply_to_message, więc łańcuchy starsze niż pamięć podręczna są ograniczone do bieżącego ładunku aktualizacji Telegram.
• Listy dozwolonych Telegram kontrolują głównie, kto może uruchomić agenta, a nie stanowią pełnej granicy redakcji dodatkowego kontekstu.
• Kontrole historii DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• Konfiguracja channels.telegram.retry dotyczy pomocników wysyłania Telegram (CLI/narzędzia/akcje) dla możliwych do odzyskania błędów wychodzącego API. Dostarczanie końcowej odpowiedzi przychodzącej również używa ograniczonego bezpiecznego ponawiania wysyłki 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 lub --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 przesłanych filmów

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

• channels.telegram.execApprovals.enabled (włącza się automatycznie, gdy da się rozpoznać co najmniej jednego zatwierdzającego)
• channels.telegram.execApprovals.approvers (wraca do numerycznych identyfikatorów 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 pozwalać na pełną widoczność.
  • BotFather: /setprivacy -> Disable
  • następnie usuń i ponownie dodaj bota do grupy
• 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 być sprawdzony pod kątem członkostwa.
• szybki test sesji: /activation always.

• gdy istnieje channels.telegram.groups, grupa musi być wymieniona (albo zawierać "*")
• sprawdź członkostwo bota w grupie
• przejrzyj logi: openclaw logs --follow pod kątem powodów pominięcia

• autoryzuj tożsamość nadawcy (parowanie i/lub numeryczne allowFrom)
• autoryzacja poleceń nadal obowiązuje, nawet gdy polityka grupy to open
• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że menu natywne ma zbyt wiele pozycji; zmniejsz liczbę poleceń pluginów/Skills/niestandardowych albo wyłącz menu natywne
• Wywołania startowe deleteMyCommands / setMyCommands oraz wywołania wpisywania sendChatAction są ograniczone czasowo i ponawiane raz przez awaryjny transport Telegram przy przekroczeniu limitu czasu żądania. Uporczywe błędy sieci/pobierania zwykle wskazują na problemy z osiągalnością DNS/HTTPS do api.telegram.org

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

• Node 22+ i niestandardowe fetch/proxy mogą wywołać natychmiastowe przerwanie, jeśli typy AbortSignal się nie zgadzają.
• Niektóre hosty najpierw rozwiązuje api.telegram.org do IPv6; zepsuty wychodzący IPv6 może powodować okresowe awarie API Telegram.
• Jeśli logi zawierają TypeError: fetch failed lub Network request for 'getUpdates' failed!, OpenClaw ponawia je teraz jako możliwe do odzyskania błędy sieciowe.
• Podczas uruchamiania odpytywania OpenClaw ponownie używa udanej startowej sondy getMe dla grammY, aby runner nie potrzebował drugiego getMe przed pierwszym getUpdates.
• Jeśli deleteWebhook kończy się przejściowym błędem sieci podczas uruchamiania odpytywania, OpenClaw przechodzi do długiego odpytywania zamiast wykonywać kolejne przedodpytywaniowe wywołanie płaszczyzny sterowania. Nadal aktywny Webhook ujawnia się jako konflikt getUpdates; OpenClaw następnie przebudowuje transport Telegram i ponawia czyszczenie webhooka.
• Jeśli gniazda Telegram odświeżają się w krótkim stałym rytmie, sprawdź niską wartość channels.telegram.timeoutSeconds; 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 tę wartość poniżej tych zabezpieczeń.
• Jeśli logi zawierają Polling stall detected, OpenClaw domyślnie restartuje odpytywanie i przebudowuje transport Telegram po 120 sekundach bez ukończonej żywotności długiego odpytywania.
• openclaw channels status --probe i openclaw doctor ostrzegają, gdy uruchomione konto odpytywania nie ukończyło getUpdates po okresie karencji startu, gdy uruchomione konto webhooka nie ukończyło setWebhook po okresie karencji startu, albo gdy ostatnia udana aktywność transportu odpytywania jest nieaktualna.
• Zwiększaj 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. Uporczywe zastoje zwykle wskazują na problemy z proxy, DNS, IPv6 lub 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 i ich warianty małymi literami. NO_PROXY / no_proxy nadal może omijać api.telegram.org.
• Jeśli zarządzany proxy OpenClaw jest skonfigurowany przez OPENCLAW_PROXY_URL dla środowiska usługi i nie ma standardowej zmiennej środowiskowej proxy, Telegram również używa tego URL-a dla transportu Bot API.
• Na hostach VPS z niestabilnym bezpośrednim wyjściem/TLS kieruj wywołania API Telegram przez channels.telegram.proxy:

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

• Node 22+ domyślnie używa autoSelectFamily=true (z wyjątkiem WSL2). Kolejność wyników DNS Telegram honoruje najpierw OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, potem 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 jawnie działa lepiej z zachowaniem tylko IPv4, wymuś wybór rodziny:

channels:
  telegram:
    network:
      autoSelectFamily: false

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

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• To samo ustawienie opcjonalne jest dostępne dla konta pod adresem channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Jeśli Twój 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 testów porównawczych 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
• Sprawdź odpowiedzi DNS:

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