Dlaczego Feishu?
Feishu (飞书), znany międzynarodowo jako Lark, to korporacyjna platforma współpracy ByteDance — szeroko używana w chińskich firmach technologicznych, startupach i coraz częściej w Azji Południowo-Wschodniej. W wersji OpenClaw v2026.2.2 Feishu stał się pierwszym oficjalnie wspieranym chińskim klientem czatowym platformy.
- •Brak wymaganego publicznego URL — bez ngrok, bez domeny, bez serwera webhook
- •Działa za firewallami — połączenie jest wychodzące z twojej maszyny
- •Niskie opóźnienie — dwukierunkowa komunikacja w czasie rzeczywistym
- •Obsługa bogatej treści — tekst, obrazy, pliki, audio, wideo i naklejki
Wymagania wstępne
- •OpenClaw v2026.2.2 lub nowszy
- •Konto korporacyjne Feishu/Lark (darmowy plan wystarczy)
- •Dostęp administratora do tworzenia aplikacji na Feishu Open Platform
Krok 1: Utwórz aplikację Feishu
- 1.Przejdź do Feishu Open Platform (lub Lark Developer Console dla międzynarodowych tenantów)
- 2.Kliknij Create Custom App
- 3.Ustaw nazwę aplikacji (np. "OpenClaw Agent") i opis
- 4.Prześlij ikonę (logo homara OpenClaw dobrze się sprawdzi)
- 5.Skopiuj App ID (format:
cli_xxx) i App Secret ze strony poświadczeń
Krok 2: Skonfiguruj uprawnienia aplikacji
W ustawieniach uprawnień aplikacji włącz te zakresy:
| Uprawnienie | Cel |
|---|---|
im:message | Wysyłanie i odbieranie wiadomości |
im:message.group_at_msg | Odbieranie wzmianek @ w czatach grupowych |
im:resource | Dostęp do obrazów i plików |
contact:user.id:readonly | Identyfikacja użytkowników |
Po dodaniu uprawnień kliknij Publish, aby przesłać do recenzji. W większości tenantów korporacyjnych samodzielnie utworzone aplikacje są automatycznie zatwierdzane.
Krok 3: Włącz subskrypcję zdarzeń
- 1.W ustawieniach aplikacji przejdź do Event Subscriptions
- 2.Wybierz WebSocket Mode (długie połączenie) — to jest kluczowe. NIE używaj trybu webhook, ponieważ wymaga publicznego URL.
- 3.Zasubskrybuj te zdarzenia:
Krok 4: Skonfiguruj OpenClaw
Dodaj poświadczenia Feishu do konfiguracji OpenClaw. Edytuj ~/.openclaw/.env:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
Lub jeśli używasz pliku konfiguracyjnego OpenClaw (~/.openclaw/config.yaml):
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
Zrestartuj OpenClaw:
openclaw restart
Powinieneś zobaczyć komunikat w logach potwierdzający nawiązanie połączenia WebSocket z Feishu.
Krok 5: Przetestuj połączenie
Otwórz Feishu i znajdź swoją aplikację na liście czatów (wyszukaj nazwę aplikacji ustawioną w Kroku 1). Wyślij wiadomość:
> Cześć!
- •Wiadomości tekstowe
- •Obrazy (agent może je analizować, jeśli używa modelu z obsługą wizji)
- •Pliki (agent może czytać dokumenty)
- •Wiadomości głosowe (transkrybowane i przetwarzane jako tekst)
Konfiguracja czatu grupowego
OpenClaw obsługuje czaty grupowe Feishu z trzema trybami dostępu:
| Tryb | Zachowanie |
|---|---|
open (domyślny) | Każdy członek grupy może uruchomić bota przez @wzmiankę |
allowlist | Tylko zatwierdzeni użytkownicy mogą wchodzić w interakcję, nawet przez @wzmiankę |
disabled | Wiadomości grupowe są całkowicie ignorowane |
Konfiguracja w config.yaml:
channels:
feishu:
groupAccess: open # or "allowlist" or "disabled"
allowedUsers: # only used with "allowlist" mode
- user_id_1
- user_id_2
W czatach grupowych agent odpowiada tylko po @wzmiance, zapobiegając szumowi na ruchliwych kanałach.
Strumieniowanie odpowiedzi
OpenClaw obsługuje strumieniowanie odpowiedzi AI w Feishu za pomocą interaktywnych kart. Zamiast czekać na pełną odpowiedź, agent wysyła początkową kartę i aktualizuje ją w czasie rzeczywistym, gdy AI generuje tekst. Zapewnia to znacznie lepsze doświadczenie użytkownika przy długich odpowiedziach.
Strumieniowanie jest domyślnie włączone. Aby je wyłączyć:
channels:
feishu:
streaming: false
Obsługiwane typy wiadomości
| Kierunek | Obsługiwane typy |
|---|---|
| Przychodzące (użytkownik -> agent) | Tekst, tekst sformatowany (post), obrazy, pliki, audio, wideo, naklejki |
| Wychodzące (agent -> użytkownik) | Tekst, obrazy, pliki, audio, karty interaktywne |
Rozwiązywanie problemów
Błąd "App not found": Upewnij się, że aplikacja jest opublikowana i zatwierdzona w twoim tenancie Feishu. Samodzielnie utworzone aplikacje w tenantach korporacyjnych zwykle zatwierdzają się automatycznie, ale niektóre organizacje wymagają zatwierdzenia administratora.
Brak odpowiedzi od agenta: Sprawdź logi OpenClaw (openclaw logs) pod kątem błędów połączenia WebSocket. Zweryfikuj, czy App ID i App Secret są poprawne.
Wiadomości nie docierają w czatach grupowych: Upewnij się, że bot jest dodany do grupy i że użytkownik poprawnie @wzmiankuje bota. Sprawdź ustawienie groupAccess.
Rozłączenia: Połączenie WebSocket automatycznie się odłącza i ponownie łączy. Jeśli rozłączenia są częste, sprawdź stabilność sieci lub ustawienia firewalla.
Użycie mostu społecznościowego (alternatywa)
Jeśli potrzebujesz funkcji wykraczających poza natywną integrację, utrzymywany przez społeczność most feishu-openclaw autorstwa AlexAnys oferuje dodatkowe możliwości, takie jak niestandardowe formatowanie wiadomości i zaawansowane zarządzanie grupami. Konfiguracja zajmuje około 5 minut i nie wymaga publicznego serwera.
Pełną dokumentację znajdziesz w oficjalnym przewodniku kanału Feishu.