Telegram

Boty Telegram domyślnie używają Privacy Mode, który ogranicza odbierane przez nie wiadomości grupowe.

Aby bot widział wszystkie wiadomości grupowe:

• wyłącz tryb prywatności przez /setprivacy albo
• nadaj botowi uprawnienia administratora grupy.

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

Status administratora jest kontrolowany w ustawieniach grupy Telegram. Boty będące administratorami otrzymują wszystkie wiadomości grupowe, co jest przydatne do ciągłego działania w grupie.

• /setjoingroups — zezwalanie na dodawanie do grup lub jego blokowanie
• /setprivacy — sposób widoczności w grupach

Te same ustawienia są dostępne w aplikacji internetowej BotFather, jeśli interfejs jest wygodniejszy niż polecenia czatu.

OpenClaw strumieniuje częściowe odpowiedzi w czasie rzeczywistym w czatach bezpośrednich, grupach i tematach: wysyła wiadomość podglądu, następnie wielokrotnie wykonuje editMessageText, a na końcu finalizuje ją w miejscu.

• channels.telegram.streaming ma wartość off | partial | block | progress (domyślnie: partial)
• krótkie początkowe podglądy odpowiedzi są opóźniane mechanizmem debounce, a następnie materializowane po ograniczonym czasie, jeśli przebieg nadal jest aktywny
• progress utrzymuje jeden edytowalny szkic stanu dla postępu narzędzi, wyświetla stabilną etykietę stanu, gdy aktywność odpowiedzi pojawi się przed postępem narzędzi, usuwa go po zakończeniu i wysyła ostateczną odpowiedź jako zwykłą wiadomość
• streaming.preview.toolProgress określa, czy aktualizacje narzędzi/postępu ponownie wykorzystują tę samą edytowaną wiadomość podglądu (domyślnie: true, gdy strumieniowanie podglądu jest aktywne)
• streaming.preview.commandText określa poziom szczegółowości poleceń/wykonania w tych wierszach: raw (domyślnie) lub status (tylko etykieta narzędzia)
• streaming.progress.commentary (domyślnie: false) włącza tekst komentarza/wstępu asystenta w tymczasowym szkicu postępu
• wykrywane są starsze channels.telegram.streamMode, wartości logiczne streaming oraz wycofane klucze natywnego podglądu szkicu; aby je zmigrować, należy uruchomić openclaw doctor --fix

Wiersze postępu narzędzi to krótkie aktualizacje stanu wyświetlane podczas działania narzędzi (wykonywanie poleceń, odczyt plików, aktualizacje planowania, podsumowania poprawek oraz wstęp/komentarz Codex w trybie serwera aplikacji). Telegram domyślnie pozostawia je włączone (zgodnie z zachowaniem wydanym od wersji v2026.4.22+).

Aby zachować edycje podglądu odpowiedzi, ale ukryć wiersze postępu narzędzi:

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

Aby zachować widoczny postęp narzędzi, ale ukryć tekst poleceń/wykonania:

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

Tryb progress pokazuje postęp narzędzi bez edytowania ostatecznej odpowiedzi w tej wiadomości. Zasady dotyczące tekstu poleceń należy umieścić w streaming.progress:

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

streaming.mode: "off" wyłącza edycje podglądu i tłumi ogólne komunikaty narzędzi/postępu zamiast wysyłać je jako osobne wiadomości o stanie; monity o zatwierdzenie, multimedia i błędy nadal są kierowane przez standardowe dostarczanie końcowe. streaming.preview.toolProgress: false zachowuje tylko edycje podglądu odpowiedzi.

W przypadku odpowiedzi zawierających tylko tekst: krótkie podglądy otrzymują końcową edycję w miejscu; długie odpowiedzi końcowe dzielone na wiele wiadomości ponownie wykorzystują podgląd jako pierwszy fragment, po czym wysyłana jest tylko pozostała część; odpowiedzi końcowe w trybie postępu usuwają szkic stanu i korzystają ze standardowego dostarczania końcowego; jeśli końcowa edycja nie powiedzie się przed potwierdzeniem zakończenia, OpenClaw przechodzi na standardowe dostarczanie końcowe i usuwa nieaktualny podgląd. W przypadku złożonych odpowiedzi (ładunków multimedialnych) OpenClaw zawsze przechodzi na standardowe dostarczanie końcowe i usuwa podgląd.

Strumieniowanie podglądu i strumieniowanie bloków wzajemnie się wykluczają — gdy strumieniowanie bloków jest jawnie włączone, OpenClaw pomija strumień podglądu, aby uniknąć podwójnego strumieniowania.

Rozumowanie: /reasoning stream strumieniuje rozumowanie do podglądu na żywo podczas generowania, a następnie usuwa podgląd rozumowania po dostarczeniu odpowiedzi końcowej (aby pozostawić go widocznym, należy użyć /reasoning on). Ostateczna odpowiedź jest wysyłana bez tekstu rozumowania.

Tekst wychodzący domyślnie korzysta ze standardowych wiadomości HTML Telegrama, czytelnych we wszystkich obecnych klientach: pogrubienie, kursywa, linki, kod, spoilery, cytaty — bez bloków dostępnych wyłącznie w rozszerzonym formacie Bot API 10.2 (natywnych tabel, szczegółów, rozszerzonych multimediów i formuł).

Aby włączyć rozszerzone wiadomości Bot API 10.2:

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

Po włączeniu: agent otrzymuje informację, że rozszerzone wiadomości są dostępne dla tego bota/konta (wraz z obsługiwanym kontraktem tworzenia treści Markdown i wysp HTML); tekst Markdown jest renderowany przez reprezentację pośrednią Markdown OpenClaw jako typowane rozszerzone bloki Bot API 10.2 (nagłówki, tabele, szczegóły, listy kontrolne, rozszerzone multimedia, formuły, mapy i kolaże); podpisy multimediów nadal korzystają z podpisów HTML Telegrama (rozszerzone wiadomości nie zastępują podpisów, a ich limit wynosi 1024 znaki).

Dzięki temu tekst modelu nie zawiera znaczników rozszerzonego Markdown Telegrama, więc waluty takie jak $400-600K nie są interpretowane jako wyrażenia matematyczne. Długi rozszerzony tekst jest automatycznie dzielony zgodnie z limitami Telegrama. Tabele przekraczające limit 20 kolumn są zastępowane blokiem kodu.

Domyślnie: wyłączone ze względu na zgodność klientów — niektóre obecne klienty Desktop, Web, Android i klientów innych firm renderują zaakceptowane rozszerzone wiadomości jako nieobsługiwane. Należy pozostawić tę funkcję wyłączoną, chyba że każdy klient używany z botem potrafi je renderować. /status pokazuje, czy rozszerzone wiadomości są w bieżącej sesji włączone, czy wyłączone.

Podglądy linków są domyślnie włączone. channels.telegram.linkPreview: false wyłącza automatyczne wykrywanie encji w rozszerzonym tekście.

Menu poleceń Telegrama jest rejestrowane podczas uruchamiania za pomocą setMyCommands. commands.native: "auto" włącza natywne polecenia dla Telegrama.

Aby dodać niestandardowe pozycje menu poleceń:

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Kopia zapasowa Git" },    { command: "generate", description: "Utwórz obraz" },  ],},},}

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

Niestandardowe polecenia są wyłącznie pozycjami menu — nie implementują automatycznie żadnego działania. Polecenia Plugin/Skills mogą nadal działać po wpisaniu, nawet jeśli nie są widoczne w menu Telegrama. Jeśli natywne polecenia są wyłączone, polecenia wbudowane zostają usunięte; niestandardowe polecenia i polecenia Plugin mogą nadal zostać zarejestrowane, jeśli je skonfigurowano.

Typowe błędy konfiguracji:

• setMyCommands failed z BOT_COMMANDS_TOO_MUCH po ponownej próbie przycięcia oznacza, że menu nadal przekracza limit; należy zmniejszyć liczbę poleceń Plugin/Skills/niestandardowych lub wyłączyć channels.telegram.commands.native.
• Niepowodzenie deleteWebhook, deleteMyCommands lub setMyCommands z 404: Not Found, gdy bezpośrednie polecenia curl Bot API działają, zwykle oznacza, że channels.telegram.apiRoot ustawiono na pełny punkt końcowy /bot<TOKEN>. apiRoot musi wskazywać wyłącznie katalog główny Bot API; openclaw doctor --fix usuwa przypadkowe końcowe /bot<TOKEN>.
• getMe returned 401 oznacza, że Telegram odrzucił skonfigurowany token bota. Należy zaktualizować botToken, tokenFile lub TELEGRAM_BOT_TOKEN (konto domyślne), używając bieżącego tokenu BotFather; OpenClaw zatrzymuje się przed rozpoczęciem odpytywania, więc błąd nie jest zgłaszany jako niepowodzenie czyszczenia Webhook.
• setMyCommands failed z błędami sieci/pobierania zwykle oznacza, że wychodzący ruch DNS/HTTPS do api.telegram.org jest zablokowany.

Polecenia parowania urządzeń (Plugin device-pair)

Po zainstalowaniu:

1. /pair generuje kod konfiguracji
2. kod należy wkleić w aplikacji iOS
3. /pair pending wyświetla oczekujące żądania (w tym rolę/zakresy)
4. zatwierdzanie: /pair approve <requestId>, /pair approve (tylko oczekujące żądanie) lub /pair approve latest

Jeśli urządzenie ponawia próbę ze zmienionymi danymi uwierzytelniania (rolą, zakresami lub kluczem publicznym), poprzednie oczekujące żądanie zostaje zastąpione nowym requestId; przed zatwierdzeniem należy ponownie uruchomić /pair pending.

Więcej informacji: Parowanie.

Konfiguracja zakresu klawiatury wbudowanej:

{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"] jest mapowane na "all".

Przykład akcji wiadomości:

{action: "send",channel: "telegram",to: "123456789",message: "Wybierz opcję:",buttons: [[  { text: "Tak", callback_data: "yes" },  { text: "Nie", callback_data: "no" },],[{ text: "Anuluj", callback_data: "cancel" }],],}

Przykład przycisku Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "Otwórz aplikację:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Uruchom", web_app: { url: "https://example.com/app" } }],  },],},}

Przyciski web_app działają tylko w prywatnych czatach między użytkownikiem a botem.

Kliknięcia wywołań zwrotnych nieprzejęte przez zarejestrowany interaktywny moduł obsługi pluginu są przekazywane agentowi jako tekst: callback_data: <value>.

Akcje:

• sendMessage (to, content, opcjonalnie mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content lub caption, opcjonalnie przyciski wbudowane presentation; edycje dotyczące wyłącznie przycisków aktualizują znaczniki odpowiedzi)
• createForumTopic (chatId, name, opcjonalnie iconColor, iconCustomEmojiId)

Ergonomiczne aliasy: send, react, delete, edit, sticker, sticker-search, topic-create.

Ograniczenia: channels.telegram.actions.sendMessage, deleteMessage, reactions, sticker (domyślnie: wyłączone). edit, createForumTopic i editForumTopic są domyślnie włączone bez osobnego przełącznika. Wysyłanie w czasie wykonywania korzysta z aktywnej migawki konfiguracji i sekretów utworzonej podczas uruchamiania lub ponownego ładowania, dlatego ścieżki akcji nie rozwiązują ponownie wartości SecretRef przy każdym wysłaniu.

Semantyka usuwania reakcji: /tools/reactions.

Jawne znaczniki wątków odpowiedzi w generowanych danych wyjściowych:

• [[reply_to_current]] — odpowiada na wiadomość wyzwalającą
• [[reply_to:<id>]] — odpowiada na wiadomość o określonym identyfikatorze

channels.telegram.replyToMode: off (domyślnie), first, all.

Gdy wątki odpowiedzi są włączone, a oryginalny tekst lub podpis jest dostępny, OpenClaw automatycznie dodaje natywny fragment cytatu. Telegram ogranicza tekst natywnego cytatu do 1024 jednostek kodowych UTF-16; w przypadku dłuższych wiadomości cytowany jest ich początek, a jeśli Telegram odrzuci cytat, używana jest zwykła odpowiedź.

off wyłącza tylko niejawne wątki odpowiedzi; jawne znaczniki [[reply_to_*]] są nadal respektowane.

Supergrupy forum: do kluczy sesji tematów dołączany jest :topic:<threadId>; odpowiedzi i wskaźniki pisania są kierowane do wątku tematu; ścieżka konfiguracji tematu to channels.telegram.groups.<chatId>.topics.<threadId>.

Temat ogólny (threadId=1) jest przypadkiem szczególnym: wysyłane wiadomości pomijają message_thread_id (Telegram odrzuca sendMessage(...thread_id=1) z komunikatem „nie znaleziono wątku”), ale akcje pisania nadal zawierają message_thread_id (zgodnie z obserwacjami jest to wymagane, aby wskaźnik pisania był widoczny).

Wpisy tematów dziedziczą ustawienia grupy, chyba że zostaną nadpisane (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId dotyczy wyłącznie tematu i nie dziedziczy wartości domyślnych grupy. topics."*" ustawia wartości domyślne dla każdego tematu w tej grupie; dokładne identyfikatory tematów nadal mają pierwszeństwo przed "*".

Kierowanie agentów według tematów: każdy temat można skierować do innego agenta za pomocą agentId w konfiguracji tematu, zapewniając mu własny obszar roboczy, pamięć i sesję:

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // Temat ogólny -> agent główny            "3": { agentId: "zu" },        // Temat programistyczny -> agent zu            "5": { agentId: "coder" }      // Przegląd kodu -> agent coder          }        }      }    }  }}

Każdy temat ma wtedy własny klucz sesji, na przykład agent:zu:telegram:group:-1001234567890:topic:3.

Trwałe powiązanie tematu ACP: tematy forum mogą przypinać sesje środowiska ACP za pomocą typowanych powiązań najwyższego poziomu (bindings[] z type: "acp", match.channel: "telegram", peer.kind: "group" oraz identyfikatorem uwzględniającym temat, takim jak -1001234567890:topic:42). Obecnie zakres jest ograniczony do tematów forum w grupach i supergrupach. Zobacz Agenci ACP.

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

Kontekst szablonu udostępnia MessageThreadId i IsForum. Czaty w wiadomościach prywatnych z message_thread_id zachowują metadane odpowiedzi, ale używają kluczy sesji uwzględniających wątki tylko wtedy, gdy Telegram getMe zgłasza has_topics_enabled: true. Wycofane nadpisania dm.threadReplies i direct.*.threadReplies zostały usunięte; tryb wątków BotFather jest jedynym źródłem prawdy. Uruchom openclaw doctor --fix, aby usunąć nieaktualne klucze konfiguracji.

Wiadomości dźwiękowe

Telegram rozróżnia notatki głosowe od plików dźwiękowych. Domyślnie używane jest zachowanie pliku dźwiękowego; znacznik [[audio_as_voice]] w odpowiedzi agenta wymusza wysłanie notatki głosowej. Transkrypcje przychodzących notatek głosowych są przedstawiane w kontekście agenta jako wygenerowany maszynowo, niezaufany tekst, ale wykrywanie wzmianek nadal korzysta z nieprzetworzonej transkrypcji, dzięki czemu 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

Telegram rozróżnia pliki wideo od notatek wideo. Notatki wideo nie obsługują podpisów; podany tekst wiadomości jest wysyłany osobno.

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

Lokalizacje i miejsca

Użyj istniejącej akcji send z jednym samodzielnym obiektem location. Współrzędne powodują wysłanie natywnego znacznika; dodanie zarówno name, jak i address powoduje wysłanie natywnej karty miejsca. Lokalizacji nie można wysyłać razem z tekstem wiadomości ani multimediami.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Eiffel Tower",address: "Champ de Mars, Paris",},}

Naklejki

Dane przychodzące: statyczny plik WEBP jest pobierany i przetwarzany (symbol zastępczy <media:sticker>); animowane pliki TGS i pliki wideo WEBM są pomijane.

Pola kontekstu naklejki: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Opisy są buforowane w stanie pluginu OpenClaw w SQLite, aby ograniczyć powtarzające się wywołania analizy obrazu.

Włącz akcje naklejek:

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

Wyślij:

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

Wyszukaj naklejki w pamięci podręcznej:

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

Reakcje Telegram są odbierane jako aktualizacje message_reaction, niezależnie od ładunków wiadomości. Po włączeniu OpenClaw umieszcza w kolejce zdarzenia systemowe, takie jak 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 wyłącznie reakcje użytkowników na wiadomości wysłane przez bota (w miarę możliwości, z użyciem pamięci podręcznej wysłanych wiadomości). Zdarzenia reakcji nadal podlegają mechanizmom kontroli dostępu Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); wiadomości od nieuprawnionych nadawców są odrzucane.

Telegram nie udostępnia identyfikatorów wątków w aktualizacjach reakcji: grupy niebędące forami są kierowane do sesji czatu grupowego; grupy forum są kierowane do sesji tematu ogólnego (:topic:1), a nie do dokładnego tematu źródłowego.

allowed_updates dla odpytywania lub Webhooka automatycznie zawiera message_reaction.

ackReaction wysyła emoji potwierdzenia, gdy OpenClaw przetwarza wiadomość przychodzącą. messages.ackReactionScope określa, kiedy jest ono wysyłane.

Kolejność rozwiązywania emoji:

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• zastępcze 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.

Zakres (messages.ackReactionScope, domyślnie "group-mentions"; obecnie bez nadpisania na poziomie konta ani kanału Telegram):

all (wiadomości prywatne i grupy, w tym zdarzenia otoczenia pokoju), direct (tylko wiadomości prywatne), group-all (każda wiadomość grupowa z wyjątkiem zdarzeń otoczenia pokoju, bez wiadomości prywatnych), group-mentions (grupy, gdy wspomniano bota; bez wiadomości prywatnych — domyślnie), off / none (wyłączone).

Zapisywanie konfiguracji kanału jest domyślnie włączone (configWrites !== false). Zapisy wyzwalane przez Telegram obejmują zdarzenia migracji grup (migrate_to_chat_id, aktualizuje channels.telegram.groups) oraz /config set / /config unset (wymaga włączenia poleceń).

Wyłącz:

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

Domyślnie używane jest długie odpytywanie. W trybie Webhooka ustaw channels.telegram.webhookUrl i channels.telegram.webhookSecret; opcjonalnie webhookPath (domyślnie /telegram-webhook), webhookHost (domyślnie 127.0.0.1), webhookPort (domyślnie 8787), webhookCertPath (certyfikat PEM z podpisem własnym dla konfiguracji korzystających bezpośrednio z adresu IP lub bez domeny).

W trybie długiego odpytywania OpenClaw utrwala znacznik wznowienia dopiero po pomyślnym przekazaniu aktualizacji; niepowodzenie modułu obsługi pozostawia możliwość ponowienia tej aktualizacji w tym samym procesie zamiast oznaczać ją jako ukończoną.

Lokalny odbiornik domyślnie wiąże się z 127.0.0.1:8787. W przypadku publicznego ruchu przychodzącego umieść odwrotne proxy przed lokalnym portem albo świadomie ustaw webhookHost: "0.0.0.0".

Tryb Webhooka weryfikuje zabezpieczenia żądania, tajny token Telegram i treść JSON, a następnie zatwierdza aktualizację w trwałej kolejce ruchu przychodzącego przed zwróceniem pustej odpowiedzi 200. Pomyślne trwałe przyjęcie zawiera x-openclaw-delivery-accepted: durable; odpowiedzi dotyczące stanu, routingu, uwierzytelniania, walidacji i błędów pamięci masowej pomijają ten nagłówek. Odwrotne proxy i kontrolery hosta mogą wymagać tego nagłówka, aby odróżnić przyjęcie przez OpenClaw od ogólnej pustej odpowiedzi 200 bez wnioskowania o akceptacji na podstawie czasu odpowiedzi.

Następnie OpenClaw przetwarza aktualizację asynchronicznie w tych samych ścieżkach bota przypisanych do poszczególnych czatów i tematów, które są używane przez długie odpytywanie, dzięki czemu powolne przebiegi agenta nie wstrzymują potwierdzenia dostarczenia do Telegram.

• channels.telegram.textChunkLimit domyślnie 4000; streaming.chunkMode="newline" preferuje granice akapitów (puste wiersze) przed podziałem według długości.
• channels.telegram.mediaMaxMb (domyślnie 100) ogranicza rozmiar przychodzących i wychodzących multimediów.
• channels.telegram.mediaGroupFlushMs (domyślnie 500, zakres 10-60000) określa, jak długo albumy/grupy multimediów są buforowane, zanim OpenClaw przekaże je jako jedną wiadomość przychodzącą. Należy zwiększyć tę wartość, jeśli części albumu docierają z opóźnieniem; zmniejszyć ją, aby skrócić opóźnienie odpowiedzi na album.
• channels.telegram.timeoutSeconds zastępuje limit czasu klienta API (jeśli nie ustawiono wartości, obowiązuje domyślna wartość grammY). Klienty botów ograniczają skonfigurowane wartości poniżej 60-sekundowego zabezpieczenia żądań wychodzącego tekstu/pisania, aby grammY nie przerwał dostarczania widocznej odpowiedzi, zanim zadziałają zabezpieczenie transportu i mechanizm awaryjny OpenClaw. Długie odpytywanie nadal korzysta z 45-sekundowego zabezpieczenia żądania getUpdates, aby bezczynne odpytywania nie były porzucane na czas nieokreślony.
• channels.telegram.pollingStallThresholdMs ma domyślną wartość 120000; wartość z zakresu od 30000 do 600000 należy dostosowywać wyłącznie w przypadku fałszywie dodatnich restartów spowodowanych wykryciem zastoju odpytywania.
• historia kontekstu grupy używa channels.telegram.historyLimit lub messages.groupChat.historyLimit (domyślnie 50); 0 ją wyłącza.
• dodatkowy kontekst odpowiedzi/cytowania/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 pluginu SQLite OpenClaw, a openclaw doctor --fix importuje starsze pliki pomocnicze. Telegram uwzględnia tylko jeden płytki reply_to_message na aktualizację, dlatego łańcuchy starsze niż pamięć podręczna są ograniczone do tego ładunku.
• listy dozwolonych Telegram przede wszystkim określają, kto może uruchamiać agenta, a nie stanowią pełnej granicy redagowania dodatkowego kontekstu.
• historia wiadomości prywatnych: channels.telegram.dmHistoryLimit, channels.telegram.dms["<user_id>"].historyLimit.
• channels.telegram.retry dotyczy funkcji pomocniczych wysyłania Telegram (CLI/narzędzia/akcje) w przypadku możliwych do usunięcia błędów wychodzącego API. Dostarczanie końcowej odpowiedzi przychodzącej korzysta z ograniczonego, bezpiecznego ponawiania prób w przypadku błędów sprzed nawiązania połączenia, ale nie ponawia niejednoznacznych kopert sieciowych po wysłaniu, które mogłyby spowodować zduplikowanie widocznych wiadomości.

Cele wysyłania CLI i narzędzia wiadomości akceptują numeryczny identyfikator czatu, nazwę użytkownika lub cel 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"

Ankiety 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 ankiet dostępne tylko w Telegram: --poll-duration-seconds (5-600), --poll-anonymous, --poll-public, --thread-id (lub cel :topic:). --poll-option powtarza się 2-12 razy (limit opcji Telegram).

Wysyłanie w Telegram obsługuje także --presentation z blokami buttons dla klawiatur wbudowanych (gdy zezwala na to channels.telegram.capabilities.inlineButtons), --pin lub --delivery '{"pin":true}' w celu zażądania przypięcia dostarczonej wiadomości, gdy bot może przypinać wiadomości na danym czacie, oraz --force-document, aby wysyłać wychodzące obrazy, pliki GIF i filmy jako dokumenty zamiast skompresowanych/animowanych przesyłanych plików lub filmów.

Ograniczanie akcji: channels.telegram.actions.sendMessage=false wyłącza wszystkie wiadomości wychodzące, w tym ankiety; channels.telegram.actions.poll=false wyłącza tworzenie ankiet, pozostawiając włączone zwykłe wysyłanie.

Telegram obsługuje zatwierdzanie wykonywania poleceń w wiadomościach prywatnych osób zatwierdzających i opcjonalnie może publikować monity na czacie lub w temacie źródłowym. Osoby zatwierdzające muszą być identyfikowane za pomocą numerycznych identyfikatorów użytkowników Telegram.

• channels.telegram.execApprovals.enabled ("auto" włącza funkcję, gdy można rozpoznać co najmniej jedną osobę zatwierdzającą)
• channels.telegram.execApprovals.approvers (w razie potrzeby używa numerycznych identyfikatorów właścicieli z commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (domyślnie) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom i defaultTo określają, kto może komunikować się z botem i gdzie bot wysyła zwykłe odpowiedzi — nie nadają one uprawnień do zatwierdzania wykonywania poleceń. Pierwsze zatwierdzone parowanie przez wiadomość prywatną inicjuje commands.ownerAllowFrom, jeśli nie istnieje jeszcze właściciel poleceń, dzięki czemu konfiguracje z jednym właścicielem działają bez powielania identyfikatorów w execApprovals.approvers.

Dostarczanie do kanału wyświetla tekst polecenia na czacie; channel lub both należy włączać wyłącznie w zaufanych grupach/tematach. Gdy monit trafia do tematu forum, OpenClaw zachowuje temat dla monitu zatwierdzenia i dalszych wiadomości. Zatwierdzenia wykonywania poleceń domyślnie wygasają po 30 minutach.

Przyciski zatwierdzania w treści wymagają również, aby channels.telegram.capabilities.inlineButtons zezwalało na docelową powierzchnię (dm, group lub all). Identyfikatory zatwierdzeń z prefiksem plugin: są rozpoznawane przez zatwierdzenia pluginu; pozostałe są najpierw rozpoznawane przez zatwierdzenia wykonywania poleceń.

Zobacz Zatwierdzanie wykonywania poleceń.

• Jeśli requireMention=false, tryb prywatności Telegram musi zezwalać na pełną widoczność: BotFather /setprivacy -> Disable, a następnie należy usunąć bota z grupy i dodać go ponownie.
• openclaw channels status ostrzega, gdy konfiguracja oczekuje wiadomości grupowych bez wzmianki.
• openclaw channels status --probe sprawdza jawne numeryczne identyfikatory grup; nie można sprawdzić członkostwa dla symbolu wieloznacznego "*".
• Szybki test sesji: /activation always.

• Gdy istnieje channels.telegram.groups, grupa musi znajdować się na liście (lub zawierać "*").
• Należy sprawdzić członkostwo bota w grupie.
• Należy przejrzeć openclaw logs --follow pod kątem przyczyn pominięcia.

• Należy autoryzować tożsamość nadawcy (parowanie i/lub numeryczny allowFrom); autoryzacja poleceń nadal obowiązuje, nawet gdy zasada grupy to open.
• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że menu natywne zawiera zbyt wiele pozycji; należy zmniejszyć liczbę poleceń pluginów/Skills/niestandardowych lub wyłączyć menu natywne.
• Wywołania startowe deleteMyCommands / setMyCommands oraz wywołania pisania sendChatAction są ograniczone i w przypadku przekroczenia limitu czasu żądania są ponawiane raz za pośrednictwem awaryjnego transportu Telegram. Utrzymujące się błędy sieci/pobierania zazwyczaj oznaczają, że DNS/HTTPS do api.telegram.org jest nieosiągalny.

• getMe returned 401 to błąd uwierzytelniania Telegram dotyczący skonfigurowanego tokenu bota. Należy ponownie skopiować lub wygenerować token w BotFather, a następnie zaktualizować channels.telegram.botToken, tokenFile, accounts.<id>.botToken lub TELEGRAM_BOT_TOKEN (konto domyślne).
• deleteWebhook 401 Unauthorized podczas uruchamiania również oznacza błąd uwierzytelniania; potraktowanie go jako „brak Webhooka” jedynie odroczyłoby ten sam błąd nieprawidłowego tokenu do późniejszego wywołania API.

• Node 22+ z niestandardowym mechanizmem fetch/proxy może powodować natychmiastowe przerywanie, jeśli typy AbortSignal są niezgodne.
• Niektóre hosty najpierw rozwiązują api.telegram.org do IPv6; niesprawny ruch wychodzący IPv6 powoduje sporadyczne błędy API.
• Wpisy dziennika zawierające TypeError: fetch failed lub Network request for 'getUpdates' failed! są ponawiane jako możliwe do usunięcia błędy sieciowe.
• Podczas uruchamiania odpytywania OpenClaw ponownie wykorzystuje udaną startową próbę getMe dla grammY, dzięki czemu moduł uruchamiający nie potrzebuje drugiego getMe przed pierwszym getUpdates.
• Jeśli deleteWebhook zakończy się przejściowym błędem sieci podczas uruchamiania odpytywania, OpenClaw przechodzi do długiego odpytywania zamiast wykonywać kolejne wywołanie płaszczyzny sterowania przed odpytywaniem. Nadal aktywny Webhook ujawnia się wtedy jako konflikt getUpdates; OpenClaw przebudowuje transport i ponawia czyszczenie Webhooka.
• Jeśli gniazda Telegram są odnawiane w krótkim, stałym cyklu, należy sprawdzić, czy channels.telegram.timeoutSeconds nie ma niskiej wartości — klienty botów ograniczają skonfigurowane wartości poniżej zabezpieczeń żądań wychodzących i getUpdates, ale starsze wersje mogły przerywać każde odpytywanie lub odpowiedź, gdy ustawiono wartość niższą od tych zabezpieczeń.
• Polling stall detected w dziennikach oznacza, że OpenClaw restartuje odpytywanie i przebudowuje transport po domyślnie 120 sekundach bez ukończonego potwierdzenia aktywności długiego odpytywania.
• openclaw channels status --probe i openclaw doctor ostrzegają, gdy uruchomione konto korzystające z odpytywania nie ukończyło getUpdates po okresie karencji uruchamiania, uruchomione konto korzystające z Webhooka nie ukończyło setWebhook po okresie karencji uruchamiania albo ostatnia pomyślna aktywność transportu odpytywania jest nieaktualna.
• Wartość channels.telegram.pollingStallThresholdMs należy zwiększać tylko wtedy, gdy długotrwałe wywołania getUpdates działają prawidłowo, ale host nadal zgłasza fałszywe restarty z powodu zastoju odpytywania. Utrzymujące się zastoje zazwyczaj wskazują na problemy z proxy, DNS, IPv6 lub wychodzącym TLS do api.telegram.org.
• Telegram uwzględnia zmienne środowiskowe proxy procesu dla transportu Bot API: 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 OPENCLAW_PROXY_URL jest ustawione dla środowiska usługi i nie istnieją standardowe zmienne środowiskowe proxy, Telegram również używa tego adresu URL dla transportu Bot API.
• Na hostach VPS z niestabilnym bezpośrednim ruchem wychodzącym/TLS należy kierować wywołania API Telegram przez 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 uwzględnia najpierw OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, następnie channels.telegram.network.dnsResultOrder, a potem ustawienie domyślne procesu (na przykład NODE_OPTIONS=--dns-result-order=ipv4first); jeśli żadne z nich nie ma zastosowania, w Node 22+ używane jest ipv4first.
• W WSL2 lub gdy lepiej działa tryb wyłącznie IPv4, należy wymusić wybór rodziny:

channels:telegram:network:  autoSelectFamily: false

• Odpowiedzi z zakresu testowego RFC 2544 (198.18.0.0/15) są już domyślnie dozwolone podczas pobierania multimediów Telegram. Jeśli zaufany serwer proxy typu fake-IP lub przezroczysty serwer proxy podczas pobierania multimediów przepisuje api.telegram.org na inny adres prywatny, wewnętrzny lub specjalnego przeznaczenia, należy włączyć obejście dotyczące wyłącznie Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• To samo ustawienie można włączyć osobno dla każdego konta w channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Jeśli serwer proxy rozwiązuje nazwy hostów multimediów Telegram na adresy z zakresu 198.18.x.x, należy najpierw pozostawić niebezpieczną flagę wyłączoną — ten zakres jest już domyślnie dozwolony.

• Tymczasowe nadpisania za pomocą zmiennych środowiskowych: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Sprawdzanie odpowiedzi DNS:

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