1. Dlaczego Telegram to najlepszy wybor?

Jeśli dopiero zaczynasz przygode z OpenClaw, Telegram powinien byc Twoim pierwszym kanalem. Oto dlaczego:

✓ Oficjalne Bot API — dzialasz zgodnie z regulaminem
✓ Zero ryzyka bana — to bot, nie symulacja klienta
✓ Wbudowany kanal — nie trzeba instalowac pluginu
✓ Inline buttons — interaktywne przyciski w wiadomosciach
✓ Forum topics — oddzielne watki dla różnych agentow
✓ Streaming odpowiedzi — "pisze na zywo" w czacie

WhatsApp (dla porownania)

~ Nieoficjalny klient (Baileys) — ryzyko bana
~ Wymaga osobnego numeru telefonu
~ Wymaga instalacji pluginu
~ Limit 4 powiazanych urządzeń
~ Brak inline buttons
~ Slabsza obsługa formatowania

Kluczowa różnica

Telegram jest wbudowanym kanalem OpenClaw — nie wymaga instalacji żadnego pluginu. Konfiguracja polega tylko na ustawieniu tokena bota. WhatsApp natomiast wymaga pluginu @openclaw/whatsapp, logowania QR i niesie ryzyko blokady konta. Więcej o WhatsApp w oddzielnym poradniku.

2. Tworzenie bota przez @BotFather

Kazdy bot Telegram musi byc zarejestrowany przez oficjalnego bota @BotFather. Caly proces trwa 2 minuty:

Otworz czat z @BotFather

W Telegramie wyszukaj @BotFather (z niebieska ikona weryfikacji) i rozpocznij rozmowe.

Uwaga: Upewnij się, ze rozmawiasz z prawdziwym @BotFather — sprawdz niebieska odznake. Falszywi "BotFatherzy" kradna tokeny!

Wyslij komende /newbot

/newbot

BotFather zapyta o nazwe bota (może zawierac spacje, np. "Moj Asystent AI") i nazwe uzytkownika (musi konczyc się na "bot", np. "moj_asystent_ai_bot").

Zapisz token bota

BotFather wygenereruje token w formacie:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz_1234567890

Zapisz ten token w bezpiecznym miejscu — będziesz go potrzebowal w nastepnym kroku. Traktuj go jak haslo.

(Opcjonalnie) Skonfiguruj Privacy Mode

Jeśli chcesz, żeby bot widzial wszystkie wiadomosci w grupach (nie tylko wzmianki), wyłącz Privacy Mode:

/setprivacy
# Wybierz swojego bota
# Wybierz "Disable"

Pamiętaj: po zmianie tego ustawienia musisz usunac i ponownie dodac bota do grupy, żeby zmiana zaczela dzialac.

(Opcjonalnie) Kontroluj dodawanie do grup

/setjoingroups
# Wybierz swojego bota
# "Enable" lub "Disable"

Jeśli ustawisz "Disable", nikt nie będzie mogl dodac bota do grup — przydatne, gdy chcesz uzywac go tylko w DM.

3. Konfiguracja tokena w OpenClaw

Masz token z BotFathera. Teraz musisz powiedziec OpenClaw, jak go uzyc. Sa trzy sposoby:

Sposob 1: Plik konfiguracyjny (zalecany)

// openclaw.config.json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "pairing",
    },
  },
}

Sposob 2: Zmienna srodowiskowa

$ export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
$ openclaw gateway

Wartość z pliku konfiguracyjnego ma priorytet nad zmienna srodowiskowa. Zmienna TELEGRAM_BOT_TOKEN dziala tylko dla domyslnego konta.

Sposob 3: Plik z tokenem

// openclaw.config.json5
{
  channels: {
    telegram: {
      tokenFile: "/etc/openclaw/telegram-token.txt",
    },
  },
}

Przydatne w środowiskach produkcyjnych, gdzie nie chcesz trzymac tokena bezposrednio w konfiguracji. Uwaga: symlinki sa odrzucane ze wzgledow bezpieczeństwa.

Czesty błąd: telegram pod plugins zamiast channels

Telegram jest wbudowanym kanalem, nie pluginem. Jeśli umieszcisz konfiguracje pod plugins.entries.telegram zamiast channels.telegram, dostaniesz błąd "plugin not found". To jeden z najczestszych błędów początkujących.

4. Polityki dostepu (DM i grupy)

Podobnie jak w kanale WhatsApp, Telegram obsluguje cztery tryby dostepu dla wiadomosci prywatnych:

dmPolicy	Opis	Rekomendacja
pairing	Nowy uzytkownik dostaje kod do zatwierdzenia (domyslne)	Dobry start dla wiekszosci uzytkownikow
allowlist	Tylko user ID z listy allowFrom moga pisac	Osobisty asystent — tylko Ty masz dostep
open	Kazdy może pisac (wymaga allowFrom: ["*"])	Publiczny bot — uwaga na koszty API
disabled	DM całkowicie wylaczone	Gdy bot dziala tylko w grupach

Jak zdobyc swoj Telegram user ID?

W przeciwienstwie do WhatsApp (numery telefonu), Telegram uzywa numerycznych user ID. Oto trzy sposoby na ich zdobycie:

Sposob 1: Logi OpenClaw (najlepszy)

$ openclaw logs --follow
# Wyslij wiadomosc do bota i odczytaj from.id z logow

Sposob 2: Bot API getUpdates

$ curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
# Przeczytaj pole "from.id" z odpowiedzi JSON

Sposob 3: Boty pomocnicze

Napisz do @userinfobot lub @getidsbot na Telegramie — odpowiedza Twoim ID.

Przykład konfiguracji z allowlista

// openclaw.config.json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "allowlist",
      allowFrom: ["8734062810", "745123456"],
    },
  },
}

Po zmianie konfiguracji musisz zrestartowac OpenClaw. Bez restartu kanal Telegram nie zaladuje nowych ustawien:

# Zatrzymaj i uruchom ponownie gateway
$ openclaw gateway

5. Integracja z grupami i kanalami

OpenClaw na Telegramie ma bardzo rozbudowana obsługę grup z dwupoziomowym systemem kontroli dostepu. Jeden poziom okresla, które grupy sa dozwolone, a drugi — kto w grupie może wyzwalac bota.

Kontrola na poziomie grup

// Pozwol konkretnemu ID grupy, otwarta polityka nadawcow
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Ważne: chat ID grup sa ujemne

Telegram ID grup i supergrup sa liczbami ujemnymi (np. -1001234567890). Nie wrzucaj ich do groupAllowFrom — to pole jest na user ID nadawcow. Chat ID grup nalezy wpisac do channels.telegram.groups.

Kontrola nadawcow w grupie

// Tylko wybrani uzytkownicy w grupie moga aktywowac bota
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: true,
          allowFrom: ["8734062810", "745123456"],
        },
      },
    },
  },
}

Jak zdobyc chat ID grupy?

• Przekaz wiadomosc z grupy do @userinfobot lub @getidsbot
• Odczytaj chat.id z logow: openclaw logs --follow
• Uzyj endpointu Bot API getUpdates

Forum topics — oddzielne watki

Jeśli Twoja grupa Telegram ma wlaczone tematy (forum mode), możesz przypisac różnych agentow AI do różnych tematow:

// Różni agenci dla różnych tematow
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },
            "3": { agentId: "programista" },
            "5": { agentId: "tlumacz" },
          },
        },
      },
    },
  },
}

Kazdy temat ma izolowana sesje w formacie: agent:programista:telegram:group:-1001234567890:topic:3. Tematy dziedzicza ustawienia grupy (requireMention, allowFrom, itp.), ale można je nadpisac indywidualnie.

6. Rich media — zdjecia, glos, stickery

Telegram ma znacznie bogatsza obsługę mediow niz wiekszosci komunikatorow. OpenClaw w pelni to wykorzystuje:

Wysylanie mediow

▶ Wiadomosci glosowe — OGG z tagiem asVoice: true
▶ Video notes — okragle wideo z asVideoNote: true
▶ Dokumenty — pliki wyslane jako zalaczniki
▶ Stickery — po wlaczeniu actions.sticker: true

Odbieranie mediow

▶ Statyczne stickery (WEBP) — pobierane i przetwarzane
▶ Animowane TGS — pomijane (brak dekodera)
▶ Video WEBM — pomijane
▶ Cache stickerow w ~/.openclaw/telegram/sticker-cache.json

Limity mediow

// Limit rozmiaru mediow (domyslnie: brak ograniczenia ze strony OpenClaw)
{
  channels: {
    telegram: {
      mediaMaxMb: 100,
    },
  },
}

Wyszukiwanie i wysylanie stickerow

Agenci moga wyszukiwac stickery po opisie i wysylac je jako odpowiedzi:

// Akcja agenta: wyszukaj sticker
{
  action: "sticker-search",
  channel: "telegram",
  query: "kot macha",
  limit: 5,
}

// Akcja agenta: wyslij sticker
{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

7. Inline buttons — interaktywne przyciski

Jedna z najwiekszych zalet Telegrama nad WhatsApp to obsługa inline buttons — interaktywnych przyciskow wyswietlanych bezposrednio pod wiadomoscia bota. Agent AI może wysylac wiadomosci z przyciskami, a klikniecia sa zwracane jako tekst.

Włączenie inline buttons

// openclaw.config.json5
{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
        // Opcje: "off" | "dm" | "group" | "all" | "allowlist"
      },
    },
  },
}

Wysylanie wiadomosci z przyciskami

// Akcja agenta
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Wybierz opcje:",
  buttons: [
    [
      { text: "Tak", callback_data: "yes" },
      { text: "Nie", callback_data: "no" },
    ],
  ],
}

Gdy uzytkownik kliknie przycisk, do agenta trafia tekst w formacie: callback_data: yes. Agent może wtedy przetworzyc odpowiedź i odpowiedziec kontekstowo.

Przyciski sa zorganizowane w wiersze — kazda tablica wewnetrzna to jeden wiersz przyciskow. Możesz miec wiele wierszy, kazdy z wieloma przyciskami.

8. Webhook vs long polling

OpenClaw obsluguje dwa tryby odbierania wiadomosci z Telegrama. Domyslny to long polling, który jest prostszy w konfiguracji.

Long polling (domyslny)

+ Zero konfiguracji — dziala od razu
+ Nie wymaga publicznego IP ani domeny
+ Dziala za NAT, VPN, firewallami
- Minimalne opoznienie (100-300ms)
- Większe zuzycie pasma (ciagle zapytania)

Uzywa grammY runner z per-chat sequencing dla niezawodnosci.

Webhook

+ Natychmiastowe dostarczanie wiadomosci
+ Mniejsze zuzycie pasma
+ Lepsze skalowanie
- Wymaga publicznego HTTPS endpoint
- Wymaga SSL certyfikatu

Konfiguracja webhooka

Jeśli masz publiczna domene z SSL (np. VPS z Caddy lub nginx), możesz przelacz się na webhook:

// openclaw.config.json5
{
  channels: {
    telegram: {
      webhookUrl: "https://example.com/webhook",
      webhookSecret: "twój-losowy-sekret-32-znaki",
      webhookPath: "/telegram-webhook",
      webhookHost: "127.0.0.1",
      webhookPort: 8787,
    },
  },
}

Rekomendacja

Jeśli dopiero zaczynasz — zostaw long polling. Nie musisz niczego konfigurowac, a różnica w opoznieniu jest niezauwazalna dla typowego uzycia osobistego asystenta. Webhook oplacaja się przy duzym ruchu (setki wiadomosci dziennie) lub w środowiskach cloud-native.

9. Streaming odpowiedzi AI

Jedyna z najbardziej imponujacych funkcji OpenClaw na Telegramie jest streaming odpowiedzi — uzytkownik widzi, jak bot "pisze" odpowiedź w czasie rzeczywistym, zamiast czekac na cala wiadomosc.

// openclaw.config.json5
{
  channels: {
    telegram: {
      streaming: "partial",
      // Opcje: "off" | "partial" | "block" | "progress"
    },
  },
}

Tryb	Zachowanie
off	Brak streamingu — czekaj na pelna odpowiedź
partial	Edytuje wiadomosc w czasie rzeczywistym (najbardziej plynne)
block	Wysyla bloki tekstu po kazdym akapicie
progress	Pokazuje postep generowania

Dodatkowo możesz wlaczyc stream "myslenia" AI (reasoning):

# Komenda w czacie Telegram:
/reasoning stream

To wysyla proces "myslenia" AI do podgladu na zywo, a finalna odpowiedź pojawia się bez reasioningu. Przydatne do debugowania i zrozumienia, jak AI dochodzi do odpowiedzi.

10. Custom commands i menu

OpenClaw automatycznie rejestruje menu komend Twojego bota w Telegramie. Możesz też dodac wlasne komendy:

// openclaw.config.json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Zrob backup" },
        { command: "generate", description: "Wygeneruj obraz" },
        { command: "summary", description: "Podsumuj rozmowe" },
      ],
    },
  },
}

Zasady dotyczace nazw komend:

• Tylko male litery, cyfry i podkreslnik: a-z, 0-9, _
• Długość: 1-32 znakow
• Nie można nadpisac wbudowanych komend OpenClaw
• Konflikty nazw sa pomijane i logowane

Wysylanie wiadomosci i ankiet z CLI

OpenClaw pozwala też wysylac wiadomosci i tworzyc ankiety bezposrednio z linii komend:

# Wyslij wiadomosc do uzytkownika
$ openclaw message send --channel telegram \
  --target 123456789 --message "Cześć!"

# Wyslij do uzytkownika po @username
$ openclaw message send --channel telegram \
  --target @jankowalski --message "Hej!"

# Utworz ankiete w grupie
$ openclaw message poll --channel telegram \
  --target -1001234567890 \
  --poll-question "Spotkanie o której?" \
  --poll-option "10:00" \
  --poll-option "14:00" \
  --poll-option "16:00" \
  --poll-duration-seconds 300

11. Troubleshooting — najczestsze problemy

Problem: Bot nie odpowiada na wiadomosci

Najczestszy problem początkujących. Checklist rozwiazywania:

1. Czy token jest prawidlowy? Sprawdz w BotFather (/token)
2. Czy konfiguracja jest pod channels.telegram (nie plugins.entries.telegram)?
3. Czy enabled: true jest ustawione?
4. Czy zrestartowales gateway po zmianie konfiguracji?
5. Czy Twój user ID jest na liscie allowFrom (dla trybu allowlist)?

$ openclaw channels status
$ openclaw doctor
$ openclaw logs --follow

Problem: Bot ignoruje wiadomosci grupowe

Cztery najczestsze przyczyny:

1. Sprawdz, czy requireMention: false jest ustawione
2. Wyłącz Privacy Mode w BotFather (/setprivacy)
3. Usun i ponownie dodaj bota do grupy
4. Przetestuj z /activation always

Problem: "BOT_COMMANDS_TOO_MUCH"

Telegram ma limit na liczbę komend w menu bota.

Rozwiązanie: Zmniejsz liczbę pluginow/skills/custom commands lub wyłącz natywne menu:

commands: { native: "off" }

Problem: Problemy z siecia / IPv6

Jeśli polling jest niestabilny, może to byc problem z IPv6 lub DNS:

# Sprawdz DNS
$ dig +short api.telegram.org A
$ dig +short api.telegram.org AAAA

# Wymus IPv4
$ export OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
$ openclaw gateway

Problem: Migracja legacy konfiguracji

Jeśli masz starsza wersje OpenClaw z @username w allowFrom (zamiast numerycznego ID):

$ openclaw doctor --fix
# Automatycznie konwertuje @username na numeryczne ID

12. Podsumowanie i następne kroki

Jeśli wykonales wszystkie kroki, masz teraz dzialajacego asystenta AI na Telegramie. Caly proces zajal prawdopodobnie mniej niz 15 minut — to właśnie dlatego Telegram jest najlepszym kanalem na początek.

Szybkie podsumowanie krokow

1. Utworz bota w @BotFather i zapisz token
2. Dodaj token do channels.telegram.botToken
3. Ustaw dmPolicy i allowFrom
4. Uruchom openclaw gateway
5. Wyslij pierwsza wiadomosc do bota

OpenClaw + Telegram — najlepsza integracja dla początkujących

Spis treści