Telegram

Boty Telegram domyślnie używają trybu prywatności, który ogranicza wiadomości grupowe, jakie otrzymują.

Jeśli bot musi widzieć wszystkie wiadomości grupowe, wykonaj jedną z czynności:

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

Po przełączeniu trybu prywatności usuń i ponownie dodaj bota w każdej grupie, aby Telegram zastosował zmianę.

Status administratora jest kontrolowany w ustawieniach grupy Telegram.

Boty administratorzy otrzymują wszystkie wiadomości grupowe, co jest przydatne dla stale aktywnego zachowania grupowego.

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

OpenClaw może przesyłać częściowe odpowiedzi strumieniowo w czasie rzeczywistym:

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

Wymaganie:

• 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

Aktualizacje podglądu postępu narzędzi to krótkie wiersze statusu pokazywane podczas działania narzędzi, na przykład wykonywania poleceń, odczytów plików, aktualizacji planowania albo podsumowań poprawek. Telegram domyślnie pozostawia je włączone, aby odpowiadać opublikowanemu zachowaniu OpenClaw od v2026.4.22 i nowszych wersji. Aby zachować edytowany podgląd tekstu odpowiedzi, ale ukryć wiersze postępu narzędzi, ustaw:

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

Aby postęp narzędzi pozostał widoczny, ale tekst polecenia/wykonania był ukryty, ustaw:

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

Użyj trybu progress, gdy chcesz widzieć postęp narzędzi bez edytowania końcowej odpowiedzi w tej samej wiadomości. Umieść politykę tekstu poleceń pod streaming.progress:

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

Używaj streaming.mode: "off" tylko wtedy, gdy chcesz dostarczanie wyłącznie końcowe: edycje podglądu Telegram są wyłączone, a ogólne komunikaty narzędzi/postępu są tłumione zamiast wysyłane jako samodzielne wiadomości statusu. Monity o zatwierdzenie, ładunki multimedialne i błędy nadal przechodzą przez normalne dostarczanie końcowe. Użyj streaming.preview.toolProgress: false, gdy chcesz zachować tylko edycje podglądu odpowiedzi, ukrywając wiersze statusu postępu narzędzi.

Dla odpowiedzi wyłącznie tekstowych:

• 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

Dla złożonych odpowiedzi (na przykład ładunków multimedialnych) OpenClaw wraca do normalnego dostarczania końcowego, a następnie czyści wiadomość podglądu.

Strumieniowanie podglądu jest oddzielne od strumieniowania blokowego. Gdy strumieniowanie blokowe jest jawnie włączone dla Telegram, OpenClaw pomija strumień podglądu, aby uniknąć podwójnego strumieniowania.

Strumień rozumowania tylko dla Telegram:

• /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 wychodzący używa Telegram parse_mode: "HTML".

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

Podglądy linków są domyślnie włączone i można je wyłączyć za pomocą channels.telegram.linkPreview: false.

Rejestracja menu poleceń Telegram jest obsługiwana podczas uruchamiania przez setMyCommands.

Domyślne ustawienia poleceń natywnych:

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

Dodaj niestandardowe wpisy menu poleceń:

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

Reguły:

• 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

Uwagi:

• 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

Jeśli polecenia natywne są wyłączone, wbudowane pozycje są usuwane. Polecenia niestandardowe/Plugin nadal mogą się rejestrować, jeśli są skonfigurowane.

Typowe błędy konfiguracji:

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

Gdy Plugin device-pair jest zainstalowany:

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

Kod konfiguracji zawiera krótkotrwały token bootstrap. Wbudowane przekazanie bootstrap utrzymuje token głównego węzła przy scopes: []; każdy przekazany token operatora pozostaje ograniczony do operator.approvals, operator.read, operator.talk.secrets oraz operator.write. Kontrole zakresu bootstrap są prefiksowane rolą, więc ta allowlista operatora spełnia tylko żądania operatora; role niebędące operatorem nadal potrzebują zakresów pod własnym prefiksem roli.

Jeśli urządzenie ponowi próbę ze zmienionymi szczegółami uwierzytelniania (na przykład rolą/zakresami/kluczem publicznym), poprzednie oczekujące żądanie zostanie zastąpione, a nowe żądanie użyje innego requestId. Uruchom ponownie /pair pending przed zatwierdzeniem.

Więcej szczegółów: Parowanie.

Skonfiguruj zakres klawiatury inline:

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

Nadpisanie dla konta:

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

Zakresy:

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

Starsze capabilities: ["inlineButtons"] mapuje się na inlineButtons: "all".

Przykład akcji wiadomości:

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

Kliknięcia callback są przekazywane agentowi jako tekst: callback_data: <value>

Akcje narzędzi Telegram obejmują:

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

Akcje wiadomości kanału udostępniają ergonomiczne aliasy (send, react, delete, edit, sticker, sticker-search, topic-create).

Kontrole bramkowania:

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

Uwaga: edit i topic-create są obecnie domyślnie włączone i nie mają oddzielnych przełączników channels.telegram.actions.*. Wysyłki w czasie działania używają aktywnej migawki konfiguracji/sekretów (uruchomienie/przeładowanie), więc ścieżki akcji nie wykonują doraźnego ponownego rozwiązywania SecretRef dla każdej wysyłki.

Semantyka usuwania reakcji: /tools/reactions

Telegram obsługuje jawne tagi wątkowania odpowiedzi w generowanym wyjściu:

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

channels.telegram.replyToMode kontroluje obsługę:

• off (domyślnie)
• first
• all

Gdy wątkowanie odpowiedzi jest włączone i dostępny jest oryginalny tekst lub podpis Telegram, OpenClaw automatycznie dołącza natywny fragment cytatu Telegram. Telegram ogranicza natywny tekst cytatu do 1024 jednostek kodu UTF-16, więc dłuższe wiadomości są cytowane od początku i wracają do zwykłej odpowiedzi, jeśli Telegram odrzuci cytat.

Uwaga: off wyłącza niejawne wątkowanie odpowiedzi. Jawne tagi [[reply_to_*]] nadal są honorowane.

Supergrupy forum:

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

Temat ogólny (threadId=1) jako przypadek specjalny:

• wysyłki wiadomości pomijają message_thread_id (Telegram odrzuca sendMessage(...thread_id=1))
• akcje pisania nadal zawierają message_thread_id

Dziedziczenie tematu: wpisy tematu dziedziczą ustawienia grupy, chyba że są nadpisane (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId jest wyłącznie tematyczny i nie dziedziczy z domyślnych ustawień grupy.

Routing agenta per temat: Każdy temat może kierować do innego agenta przez ustawienie agentId w konfiguracji tematu. Daje to każdemu tematowi własny izolowany obszar roboczy, pamięć i sesję. Przykład:

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

Każdy temat ma następnie własny klucz sesji: agent:zu:telegram:group:-1001234567890:topic:3

Trwałe powiązanie tematu ACP: Tematy forum mogą przypinać sesje mechanizmu ACP za pomocą typowanych powiązań ACP najwyższego poziomu (bindings[] z type: "acp" oraz match.channel: "telegram", peer.kind: "group" i identyfikatorem kwalifikowanym tematem, takim jak -1001234567890:topic:42). Obecnie ograniczone do tematów forum w grupach/supergrupach. Zobacz Agenci ACP.

Uruchomienie ACP powiązane z wątkiem z czatu: /acp spawn <agent> --thread here|auto wiąże bieżący temat z nową sesją ACP; kolejne wiadomości są kierowane bezpośrednio tam. OpenClaw przypina potwierdzenie uruchomienia w temacie. Wymaga pozostawienia włączonego channels.telegram.threadBindings.spawnSessions (domyślnie: true).

Kontekst szablonu udostępnia MessageThreadId i IsForum. Czaty DM z message_thread_id domyślnie zachowują trasowanie DM i metadane odpowiedzi w płaskich sesjach; używają kluczy sesji świadomych wątków tylko wtedy, gdy są skonfigurowane z threadReplies: "inbound", threadReplies: "always", requireTopic: true albo pasującą konfiguracją tematu. Użyj channels.telegram.dm.threadReplies dla domyślnego ustawienia konta albo direct.<chatId>.threadReplies dla jednego DM.

Wiadomości audio

Telegram rozróżnia notatki głosowe i pliki 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ą.

Przykład akcji wiadomości:

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

Wiadomości wideo

Telegram rozróżnia pliki wideo i notatki wideo.

Przykład akcji wiadomości:

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

Notatki wideo nie obsługują podpisów; podany tekst wiadomości jest wysyłany osobno.

Naklejki

Obsługa przychodzących naklejek:

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

Pola kontekstu naklejki:

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

Plik pamięci podręcznej naklejek:

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

Naklejki są opisywane raz (gdy to możliwe) i buforowane, aby ograniczyć powtarzające się wywołania rozpoznawania obrazu.

Włącz akcje naklejek:

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

Akcja wysłania naklejki:

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

Wyszukiwanie naklejek z pamięci podręcznej:

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

Reakcje Telegram przychodzą jako aktualizacje message_reaction (oddzielnie od ładunków wiadomości).

Po włączeniu OpenClaw kolejkuje zdarzenia systemowe, takie jak:

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

Konfiguracja:

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

Uwagi:

• 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

allowed_updates dla pollingu/Webhook automatycznie obejmuje message_reaction.

ackReaction wysyła emoji potwierdzenia, gdy OpenClaw przetwarza wiadomość przychodzącą.

Kolejność rozstrzygania:

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

Uwagi:

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

Zapisy konfiguracji kanału są domyślnie włączone (configWrites !== false).

Zapisy wyzwalane przez Telegram obejmują:

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

Wyłączanie:

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

Domyślnie używany jest long polling. W trybie Webhook ustaw channels.telegram.webhookUrl i channels.telegram.webhookSecret; opcjonalnie webhookPath, webhookHost, webhookPort (domyślnie /telegram-webhook, 127.0.0.1, 8787).

W trybie long pollingu OpenClaw utrwala swój znacznik restartu dopiero po pomyślnym wysłaniu aktualizacji do obsługi. Jeśli handler się nie powiedzie, ta aktualizacja pozostaje możliwa do ponowienia w tym samym procesie i nie jest zapisywana jako ukończona na potrzeby deduplikacji po restarcie.

Lokalny listener wiąże się z 127.0.0.1:8787. Dla publicznego wejścia umieść reverse proxy przed lokalnym portem albo celowo ustaw webhookHost: "0.0.0.0".

Tryb Webhook weryfikuje zabezpieczenia żądania, tajny token Telegram i treść JSON przed zwróceniem 200 do Telegram. Następnie OpenClaw przetwarza aktualizację asynchronicznie przez te same pasma bota per czat/per temat, których używa long polling, więc wolne tury agenta nie blokują potwierdzenia dostarczenia Telegram.

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

Cele wysyłania CLI i narzędzia wiadomości mogą być numerycznym ID czatu, nazwą użytkownika albo celem tematu forum:

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"

Pollingi Telegram używają openclaw message poll i obsługują tematy forum:

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

Flagi pollingu tylko dla Telegram:

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id dla tematów forum (albo użyj celu :topic:)

Wysyłanie Telegram obsługuje także:

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

Bramy akcji:

• 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

Telegram obsługuje zatwierdzenia wykonania w DM zatwierdzających i może opcjonalnie publikować prompty w czacie lub temacie źródłowym. Zatwierdzający muszą być numerycznymi identyfikatorami użytkowników Telegram.

Ścieżka konfiguracji:

• 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

channels.telegram.allowFrom, groupAllowFrom i defaultTo kontrolują, kto może rozmawiać z botem i gdzie wysyła on zwykłe odpowiedzi. Nie czynią nikogo zatwierdzającym wykonanie. Pierwsze zatwierdzone sparowanie DM inicjuje commands.ownerAllowFrom, gdy nie istnieje jeszcze właściciel poleceń, więc konfiguracja z jednym właścicielem nadal działa bez duplikowania ID w execApprovals.approvers.

Dostarczanie kanałowe pokazuje tekst polecenia na czacie; włączaj channel lub both tylko w zaufanych grupach/tematach. Gdy prompt trafia do tematu forum, OpenClaw zachowuje temat dla promptu zatwierdzenia i kolejnej wiadomości. Zatwierdzenia wykonania domyślnie wygasają po 30 minutach.

Przyciski zatwierdzania inline również wymagają, aby channels.telegram.capabilities.inlineButtons dopuszczało docelową powierzchnię (dm, group albo all). Identyfikatory zatwierdzeń z prefiksem plugin: są rozpoznawane przez zatwierdzenia pluginów; pozostałe są najpierw rozpoznawane przez zatwierdzenia wykonania.

Zobacz Zatwierdzenia wykonania.

• 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 Adig +short api.telegram.org AAAA