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

• /setjoingroups, aby zezwolić/zabronić dodawania do grup
• /setprivacy dla zachowania widoczności w grupach

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

• channels.telegram.streaming ma wartość off | partial | block | progress (domyślnie: partial)
• progress jest mapowane do partial w Telegram (zgodność z nazewnictwem międzykanałowym)
• streaming.preview.toolProgress kontroluje, czy aktualizacje narzędzi/postępu używają tej samej edytowanej wiadomości podglądu (domyślnie: true). Ustaw false, aby zachować osobne wiadomości narzędzi/postępu.
• starsze channels.telegram.streamMode i wartości logiczne streaming są mapowane automatycznie

• DM: OpenClaw zachowuje tę samą wiadomość podglądu i wykonuje końcową edycję w miejscu (bez drugiej wiadomości)
• grupa/temat: OpenClaw zachowuje tę samą wiadomość podglądu i wykonuje końcową edycję w miejscu (bez drugiej wiadomości)

• /reasoning stream wysyła rozumowanie do podglądu na żywo podczas generowania
• odpowiedź końcowa jest wysyłana bez tekstu rozumowania

• Tekst w stylu Markdown jest renderowany do HTML bezpiecznego dla Telegram.
• Surowy HTML modelu jest escape’owany, aby ograniczyć błędy parsowania Telegram.
• Jeśli Telegram odrzuci sparsowany HTML, OpenClaw ponawia próbę jako zwykły tekst.

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

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

• 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/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 było przepełnione po przycięciu; zmniejsz liczbę poleceń plugin/Skills/niestandardowych albo wyłącz channels.telegram.commands.native.
• setMyCommands failed z błędami sieci/fetch zwykle oznacza, że wychodzące DNS/HTTPS do api.telegram.org jest zablokowane.

​

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 role/scopes)
4. zatwierdź żądanie:
   • /pair approve <requestId> dla jawnego zatwierdzenia
   • /pair approve, gdy istnieje tylko jedno oczekujące żądanie
   • /pair approve latest dla najnowszego

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

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

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

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

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

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

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

• off (domyślnie)
• first
• all

• klucze sesji tematów dopisują :topic:<threadId>
• odpowiedzi i wpisywanie kierowane są 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" },      // Temat ogólny → agent main
            "3": { agentId: "zu" },        // Temat dev → agent zu
            "5": { agentId: "coder" }      // Code review → agent coder
          }
        }
      }
    }
  }
}

• bindings[] z type: "acp" i match.channel: "telegram"

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}

• /acp spawn <agent> --thread here|auto może powiązać bieżący temat Telegram z nową sesją ACP.
• Kolejne wiadomości w temacie są kierowane bezpośrednio do powiązanej sesji ACP (bez potrzeby /acp steer).
• OpenClaw przypina wiadomość potwierdzającą uruchomienie w temacie po pomyślnym powiązaniu.
• Wymaga channels.telegram.threadBindings.spawnAcpSessions=true.

• MessageThreadId
• IsForum

• czaty prywatne z message_thread_id zachowują routing DM, ale używają kluczy sesji i celów odpowiedzi świadomych wątku.

​

Wiadomości audio

• domyślnie: zachowanie pliku audio
• tag [[audio_as_voice]] w odpowiedzi agenta wymusza wysłanie jako notatka głosowa

{
  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

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

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "machający kot",
  limit: 5,
}

• Dodano reakcję Telegram: 👍 przez Alice (@alice) do wiadomości 42

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

• own oznacza tylko reakcje użytkowników na wiadomości wysłane przez bota (best-effort przez cache 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 niebędące forami są kierowane do sesji czatu grupowego
  • grupy forum 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
• zapasowo emoji tożsamości agenta (agents.list[].identity.emoji, w przeciwnym razie ”👀”)

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

• zdarzenia migracji grup (migrate_to_chat_id) do aktualizacji channels.telegram.groups
• /config set i /config unset (wymaga włączenia poleceń)

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

• ustaw channels.telegram.webhookUrl
• ustaw channels.telegram.webhookSecret (wymagane, gdy ustawiony jest adres URL webhooka)
• opcjonalnie channels.telegram.webhookPath (domyślnie /telegram-webhook)
• opcjonalnie channels.telegram.webhookHost (domyślnie 127.0.0.1)
• opcjonalnie channels.telegram.webhookPort (domyślnie 8787)

• domyślna wartość channels.telegram.textChunkLimit to 4000.
• channels.telegram.chunkMode="newline" preferuje granice akapitów (puste linie) przed dzieleniem według długości.
• channels.telegram.mediaMaxMb (domyślnie 100) ogranicza rozmiar mediów Telegram przychodzących i wychodzących.
• channels.telegram.timeoutSeconds nadpisuje timeout klienta Telegram API (jeśli nie jest ustawione, obowiązuje wartość domyślna grammY).
• channels.telegram.pollingStallThresholdMs domyślnie wynosi 120000; dostrajaj w zakresie 30000–600000 tylko dla fałszywie dodatnich restartów zastoju polling.
• historia kontekstu grupy używa channels.telegram.historyLimit lub messages.groupChat.historyLimit (domyślnie 50); 0 wyłącza.
• dodatkowy kontekst odpowiedzi/cytatu/przekazania dalej jest obecnie przekazywany tak, jak został odebrany.
• listy dozwolonych Telegram przede wszystkim ograniczają to, kto może uruchomić 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 dotyczy pomocników wysyłania Telegram (CLI/narzędzia/akcje) dla możliwych do odzyskania wychodzących błędów API.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

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 (lub użyj celu :topic:)

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

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

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (opcjonalnie; zapasowo używa numerycznych identyfikatorów właścicieli wywnioskowanych z allowFrom oraz bezpośredniego defaultTo, gdy to możliwe)
• channels.telegram.execApprovals.target (dm | channel | both, domyślnie: dm)
• agentFilter, sessionFilter

• target: "dm" wysyła prośby o zatwierdzenie tylko do rozpoznanych DM zatwierdzających
• target: "channel" wysyła prośbę z powrotem do źródłowego czatu/tematu Telegram
• target: "both" wysyła do DM zatwierdzających i do źródłowego czatu/tematu

• ID z prefiksem plugin: są zawsze rozstrzygane przez zatwierdzenia Plugin.
• Inne ID najpierw próbują exec.approval.resolve.
• Jeśli Telegram jest również autoryzowany do zatwierdzeń Plugin, a gateway zwraca, że zatwierdzenie exec jest nieznane/wygasłe, Telegram ponawia próbę raz przez plugin.approval.resolve.
• Rzeczywiste odmowy/błędy zatwierdzeń exec nie przechodzą po cichu zapasowo do rozstrzygania zatwierdzeń Plugin.

• Jeśli requireMention=false, tryb prywatności Telegram musi pozwalać na pełną widoczność.
  • BotFather: /setprivacy -> Disable
  • następnie usuń bota i dodaj go ponownie 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ć sprawdzany pod kątem członkostwa.
• szybki test sesji: /activation always.

• gdy istnieje channels.telegram.groups, grupa musi być wymieniona (lub musi zawierać "*")
• zweryfikuj członkostwo bota w grupie
• przejrzyj logi: openclaw logs --follow, aby sprawdzić powody pomijania

• autoryzuj tożsamość swojego nadawcy (parowanie i/lub numeryczne allowFrom)
• autoryzacja poleceń nadal obowiązuje, nawet gdy zasady grupy mają wartość open
• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że natywne menu ma zbyt wiele wpisów; zmniejsz liczbę poleceń plugin/Skills/niestandardowych albo wyłącz menu natywne
• setMyCommands failed z błędami sieci/fetch zwykle wskazuje na problemy z dostępnością DNS/HTTPS do api.telegram.org

• Node 22+ + niestandardowy fetch/proxy może wywoływać natychmiastowe zachowanie abort, jeśli typy AbortSignal nie pasują.
• Niektóre hosty najpierw rozwiązują api.telegram.org do IPv6; uszkodzony ruch wychodzący IPv6 może powodować sporadyczne błędy Telegram API.
• 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.
• Jeśli logi zawierają Polling stall detected, OpenClaw restartuje polling i odbudowuje transport Telegram po 120 sekundach bez zakończonego sygnału życia long polling.
• Zwiększaj channels.telegram.pollingStallThresholdMs tylko wtedy, gdy długotrwałe wywołania getUpdates są zdrowe, ale host nadal zgłasza fałszywe restarty zastoju polling. Uporczywe zastoje zwykle wskazują na problemy proxy, DNS, IPv6 lub TLS egress między hostem a api.telegram.org.
• Na hostach VPS z niestabilnym bezpośrednim egress/TLS kieruj wywołania Telegram API 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) i dnsResultOrder=ipv4first.
• Jeśli Twój host to WSL2 lub jawnie lepiej działa w trybie 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 mediów Telegram. Jeśli zaufany fake-IP lub transparent proxy przepisuje api.telegram.org na jakiś inny prywatny/wewnętrzny/specjalnego przeznaczenia adres podczas pobierania mediów, możesz włączyć obejście tylko dla Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• To samo ustawienie opt-in jest dostępne per konto pod channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Jeśli Twoje proxy rozwiązuje hosty mediów Telegram do 198.18.x.x, najpierw pozostaw niebezpieczną flagę wyłączoną. Media Telegram już domyślnie dopuszczają zakres benchmarkowy RFC 2544.

• Nadpisania przez env (tymczasowe):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Zweryfikuj odpowiedzi DNS:

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