// dokumentacja openclaw

OpenClaw i Telegram — konfiguracja bota i grup

Wprowadzenie

Telegram to jeden z najpopularniejszych kanałów dla agentów OpenClaw. Dzięki bogatemu API, obsłudze mediów i grup, Telegram doskonale nadaje się zarówno do rozmów indywidualnych, jak i do obsługi społeczności. Ten przewodnik szczegółowo opisuje konfigurację integracji OpenClaw z Telegramem.

Tworzenie bota w BotFather

Każdy bot na Telegramie wymaga rejestracji przez oficjalnego BotFather.

  1. Otwórz Telegram i wyszukaj @BotFather
  2. Wyślij polecenie /newbot
  3. Podaj nazwę bota (wyświetlaną w rozmowach), np. Mój Asystent AI
  4. Podaj username bota (musi kończyć się na bot), np. moj_asystent_ai_bot
  5. BotFather zwróci token HTTP API — skopiuj go, będzie potrzebny do konfiguracji

Dodatkowo warto skonfigurować bota w BotFather:

  • /setdescription — opis widoczny przy pierwszym kontakcie z botem
  • /setabouttext — krótki opis w profilu bota
  • /setuserpic — zdjęcie profilowe bota
  • /setcommands — lista poleceń bota (np. /start, /help)
  • /setprivacy — ustaw na Disable, jeśli bot ma widzieć wszystkie wiadomości w grupie (nie tylko @mentions)

Konfiguracja w OpenClaw

Dodaj sekcję Telegram do pliku openclaw.json:

{
  channels: {
    telegram: {
      enabled: true,
      token: "${TELEGRAM_BOT_TOKEN}",

      // Polityka wiadomości prywatnych
      dm_policy: "pairing",

      // Polityka grup
      group_policy: "mention",

      // Opcjonalne ustawienia
      parse_mode: "Markdown",    // Markdown | HTML | MarkdownV2
      streaming: true,            // aktualizowanie wiadomości na bieżąco
      typing_indicator: true,     // "pisze..." podczas generowania
      max_message_length: 4096,   // limit Telegrama
      split_long_messages: true,  // dziel długie odpowiedzi na części
    }
  }
}

Polityki dostępu

OpenClaw oferuje osobne polityki dla wiadomości prywatnych (DM) i grup.

Polityki DM

  • pairing — użytkownik musi podać kod parowania (wygenerowany w Control UI lub CLI), aby rozpocząć rozmowę. Najbezpieczniejsza opcja.
  • allowlist — tylko użytkownicy z listy allowed_users mogą pisać do bota. Lista zawiera Telegram User ID (numeryczne).
  • open — każdy może pisać do bota. Używaj ostrożnie — każda wiadomość generuje zapytanie do API providera AI i związane z tym koszty.

Polityki grup

  • mention — bot odpowiada tylko, gdy zostanie wspomniany (@username) lub gdy wiadomość jest odpowiedzią na jego wiadomość. Zalecane dla aktywnych grup.
  • always — bot odpowiada na każdą wiadomość w grupie. Może generować duże koszty API w aktywnych grupach.
  • off — bot ignoruje wszystkie wiadomości grupowe. Przydatne, gdy bot obsługuje tylko DM.

Zaawansowana kontrola dostępu

{
  channels: {
    telegram: {
      dm_policy: "allowlist",
      allowed_users: [123456789, 987654321],
      allowed_groups: [-1001234567890],
      admin_users: [123456789],  // mogą zarządzać botem
      rate_limit: {
        messages_per_hour: 30,
        cooldown_seconds: 5,
      }
    }
  }
}

Wątki i tematy (forum supergroups)

Telegram umożliwia tworzenie grup forumowych z tematami (topics). OpenClaw obsługuje tę funkcję natywnie:

{
  channels: {
    telegram: {
      forum_support: true,
      topic_bindings: {
        "General": "default_agent",
        "Support": "support_agent",
        "Dev": "dev_agent",
      },
      auto_create_topics: false,
    }
  }
}

Możesz przypisać różnych agentów do różnych tematów w ramach jednej grupy. Na przykład temat „Support" obsługiwany jest przez agenta wsparcia, a „Dev" przez agenta technicznego.

Obsługa mediów

OpenClaw obsługuje pełny zakres mediów Telegrama:

  • Zdjęcia — automatycznie przesyłane do modelu vision. Agent analizuje i opisuje obrazy.
  • Wiadomości głosowe — transkrybowane przez Whisper/Deepgram. Tekst trafia do agenta.
  • Dokumenty — PDF, DOCX, XLSX i inne pliki są parsowane i ich treść przekazywana agentowi.
  • Stickery — traktowane jako obrazy, agent widzi grafikę stickera.
  • Lokalizacja — współrzędne GPS przekazywane agentowi (np. do wyszukiwania pobliskich miejsc).
  • Wideo — krótkie filmy i video notes (okrągłe wiadomości wideo) mogą być analizowane.

Agent może też wysyłać media w odpowiedziach — generowane obrazy, pliki audio (TTS) lub dokumenty.

Tryb dostarczania wiadomości

OpenClaw obsługuje dwa tryby odbierania wiadomości z Telegrama:

Polling (domyślny)

Gateway cyklicznie odpytuje serwery Telegrama o nowe wiadomości. Prostsze w konfiguracji, nie wymaga publicznego adresu IP.

{
  channels: {
    telegram: {
      delivery: "polling",
      poll_interval: 1000,  // milisekundy
    }
  }
}

Webhook

Telegram wysyła wiadomości bezpośrednio do Twojego serwera. Szybsze i bardziej wydajne, ale wymaga publicznego adresu HTTPS:

{
  channels: {
    telegram: {
      delivery: "webhook",
      webhook_url: "https://twoja-domena.pl/webhook/telegram",
      webhook_secret: "losowy_ciag_znakow",
    }
  }
}

Webhook jest zalecany dla produkcyjnych wdrożeń, ponieważ eliminuje opóźnienia pollingu i zmniejsza obciążenie sieci.

Proxy

Jeśli Twój serwer ma ograniczony dostęp do API Telegrama (np. w niektórych sieciach korporacyjnych), możesz skonfigurować proxy:

{
  channels: {
    telegram: {
      proxy: {
        type: "socks5",          // http | socks5
        host: "proxy.example.com",
        port: 1080,
        username: "user",        // opcjonalne
        password: "pass",        // opcjonalne
      }
    }
  }
}

Rozwiązywanie problemów

Najczęstsze problemy i ich rozwiązania:

  • Bot nie odpowiada — sprawdź openclaw gateway status. Upewnij się, że kanał Telegram jest podłączony. Zweryfikuj token bota.
  • Błąd 409 (Conflict) — inny proces używa tego samego tokena bota. Zatrzymaj inne instancje OpenClaw lub inne aplikacje korzystające z tego bota.
  • Bot nie widzi wiadomości w grupie — ustaw privacy mode na Disable w BotFather (/setprivacy).
  • Wiadomości są obcinane — Telegram ma limit 4096 znaków na wiadomość. Włącz split_long_messages: true.
  • Brak mediów — sprawdź, czy model AI obsługuje vision (GPT-4o, Claude, Gemini). Modele tekstowe ignorują obrazy.
  • Webhook nie działa — upewnij się, że URL jest publicznie dostępny i obsługuje HTTPS z ważnym certyfikatem SSL.

W razie dalszych problemów sprawdź logi: openclaw logs --channel telegram --tail 50

Wróc do dokumentacji