Telegram

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

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

• 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

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

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

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

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

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

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

​

Wiadomości dźwiękowe

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

​

Lokalizacje i miejsca

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

​

Naklejki

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

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

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

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

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

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

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

• 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

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