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

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

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

• channels.telegram.streaming ma wartość off | partial | block | progress (domyślnie: partial)
• progress mapuje się do partial w Telegramie (zgodność z nazewnictwem międzykanałowym)
• starsze wartości channels.telegram.streamMode i logiczne streaming są automatycznie mapowane

• 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
• końcowa odpowiedź jest wysyłana bez tekstu rozumowania

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

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

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

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

• polecenia niestandardowe to tylko wpisy menu; nie implementują automatycznie zachowania
• polecenia plugin/Skills nadal mogą działać po wpisaniu, nawet jeśli nie są pokazane w menu Telegrama

• setMyCommands failed z BOT_COMMANDS_TOO_MUCH oznacza, że menu Telegrama nadal było przepełnione po przycięciu; zmniejsz liczbę poleceń plugin/Skills/niestandardowych lub wyłącz channels.telegram.commands.native.
• setMyCommands failed z błędami sieci/fetch zwykle oznacza, że wychodzący DNS/HTTPS do api.telegram.org jest zablokowany.

​

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

1. /pair generuje kod konfiguracji
2. wklej kod w aplikacji iOS
3. /pair pending wyświetla oczekujące żądania (w tym rolę/zakresy)
4. zatwierdź żądanie:
   • /pair approve <requestId> dla jawnego zatwierdzenia
   • /pair approve, gdy 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: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", 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 konkretny identyfikator wiadomości Telegrama

• off (domyślnie)
• first
• all

• klucze sesji tematów dodają :topic:<threadId>
• odpowiedzi i wpisywanie kierowane są do wątku tematu
• ścieżka konfiguracji tematu: channels.telegram.groups.<chatId>.topics.<threadId>

• wysyłanie wiadomości pomija message_thread_id (Telegram odrzuca sendMessage(...thread_id=1))
• akcje wpisywania nadal zawierają message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Temat ogólny → główny agent
            "3": { agentId: "zu" },        // Temat deweloperski → agent zu
            "5": { agentId: "coder" }      // Przegląd kodu → 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 Telegrama z nową sesją ACP.
• Kolejne wiadomości w temacie są kierowane bezpośrednio do powiązanej sesji ACP (bez potrzeby użycia /acp steer).
• OpenClaw przypina w temacie wiadomość potwierdzającą uruchomienie 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ątków.

​

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: "cat waving",
  limit: 5,
}

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

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

• own oznacza reakcje użytkowników tylko na wiadomości wysłane przez bota (best-effort przez cache wysłanych wiadomości).
• Zdarzenia reakcji nadal respektują kontrolę dostępu Telegrama (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); nieautoryzowani nadawcy są odrzucani.
• Telegram nie udostępnia identyfikatorów wątków w aktualizacjach reakcji.
  • grupy niebędące forum 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
• awaryjnie emoji tożsamości agenta (agents.list[].identity.emoji, w przeciwnym razie ”👀”)

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

• zdarzenia migracji grupy (migrate_to_chat_id) w celu 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 ustawiono webhook URL)
• 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 podziałem według długości.
• channels.telegram.mediaMaxMb (domyślnie 100) ogranicza rozmiar mediów przychodzących i wychodzących Telegrama.
• channels.telegram.timeoutSeconds nadpisuje limit czasu klienta Telegram API (jeśli nieustawione, obowiązuje domyślna wartość grammY).
• historia kontekstu grupy używa channels.telegram.historyLimit lub messages.groupChat.historyLimit (domyślnie 50); 0 wyłącza.
• dodatkowy kontekst odpowiedzi/cytatu/przekazania jest obecnie przekazywany tak, jak został odebrany.
• allowlisty Telegrama głównie kontrolują, 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 dotyczy pomocników wysyłania Telegrama (CLI/tools/actions) dla odzyskiwalnych błędów wychodzącego 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:)

• --buttons dla klawiatur inline, gdy channels.telegram.capabilities.inlineButtons zezwala na tę powierzchnię
• --force-document, aby wysyłać 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 Telegrama, w tym ankiety
• channels.telegram.actions.poll=false wyłącza tworzenie ankiet Telegrama, pozostawiając zwykłe wysyłanie włączone

• channels.telegram.execApprovals.enabled
• channels.telegram.execApprovals.approvers (opcjonalnie; awaryjnie używa numerycznych identyfikatorów właściciela 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 rozwiązanych wiadomości prywatnych zatwierdzających
• target: "channel" odsyła prośbę do źródłowego czatu/tematu Telegrama
• target: "both" wysyła do wiadomości prywatnych zatwierdzających i do źródłowego czatu/tematu

• Identyfikatory z prefiksem plugin: są zawsze rozwiązywane przez zatwierdzenia pluginów.
• Inne identyfikatory najpierw próbują exec.approval.resolve.
• Jeśli Telegram jest także autoryzowany do zatwierdzeń pluginów i gateway zwraca, że zatwierdzenie exec jest nieznane lub wygasłe, Telegram podejmuje jedną ponowną próbę przez plugin.approval.resolve.
• Rzeczywiste odrzucenia/błędy zatwierdzeń exec nie przechodzą po cichu do rozwiązywania zatwierdzeń pluginów.

• Jeśli requireMention=false, tryb prywatności Telegrama musi zezwalać na pełną widoczność.
  • BotFather: /setprivacy -> Disable
  • 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; członkostwa dla wildcard "*" nie da się sprawdzić sondą.
• szybki test sesji: /activation always.

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

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

• Node 22+ + niestandardowy fetch/proxy mogą wywoływać natychmiastowe przerywanie, 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ć sporadyczne błędy Telegram API.
• Jeśli logi zawierają TypeError: fetch failed lub Network request for 'getUpdates' failed!, OpenClaw teraz ponawia te operacje jako odzyskiwalne błędy sieciowe.
• Na hostach VPS z niestabilnym bezpośrednim ruchem wychodzącym/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) oraz dnsResultOrder=ipv4first.
• Jeśli host to WSL2 lub jawnie działa lepiej wyłącznie z 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 Telegrama. Jeśli zaufany fake-IP lub transparent proxy przepisuje api.telegram.org na inny prywatny/wewnętrzny/specjalnego przeznaczenia adres podczas pobierania mediów, możesz włączyć obejście tylko dla Telegrama:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

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

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