Bot Feishu

Feishu (Lark) to zespołowa platforma czatu używana przez firmy do komunikacji i współpracy. Ta wtyczka łączy OpenClaw z botem Feishu/Lark, wykorzystując subskrypcję zdarzeń WebSocket platformy, dzięki czemu wiadomości mogą być odbierane bez wystawiania publicznego adresu URL webhooka.

Wymagana wtyczka

Zainstaluj wtyczkę Feishu:

openclaw plugins install @openclaw/feishu

Lokalne repozytorium (gdy uruchamiasz z repozytorium git):

openclaw plugins install ./extensions/feishu

Szybki start

Istnieją dwa sposoby dodania kanału Feishu:

Metoda 1: kreator onboardingu (zalecane)

Jeśli właśnie zainstalowałeś OpenClaw, uruchom kreator:

openclaw onboard

Kreator przewodniczy Ci przez:

Utworzenie aplikacji Feishu i zebranie poświadczeń
Skonfigurowanie poświadczeń aplikacji w OpenClaw
Uruchomienie gateway

✅ Po konfiguracji sprawdź status gateway:

openclaw gateway status
openclaw logs --follow

Metoda 2: konfiguracja przez CLI

Jeśli masz już ukończoną instalację początkową, dodaj kanał przez CLI:

openclaw channels add

Wybierz Feishu, a następnie wprowadź App ID i App Secret. ✅ Po konfiguracji zarządzaj gateway:

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

Krok 1: Utwórz aplikację Feishu

1. Otwórz Feishu Open Platform

Odwiedź Feishu Open Platform i zaloguj się. Tenanci Lark (globalni) powinni użyć https://open.larksuite.com/app i ustawić domain: "lark" w konfiguracji Feishu.

2. Utwórz aplikację

Kliknij Create enterprise app
Uzupełnij nazwę aplikacji i opis
Wybierz ikonę aplikacji

3. Skopiuj poświadczenia

W sekcji Credentials & Basic Info skopiuj:

Identyfikator aplikacji (format: cli_xxx)
Sekret aplikacji

❗ Ważne: zachowaj App Secret w tajemnicy. Get credentials

4. Skonfiguruj uprawnienia

W Permissions kliknij Batch import i wklej:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. Włącz możliwości bota

W App Capability > Bot:

Włącz obsługę bota
Ustaw nazwę bota

6. Skonfiguruj subskrypcję zdarzeń

⚠️ Ważne: przed skonfigurowaniem subskrypcji zdarzeń upewnij się, że:

Wykonałeś już openclaw channels add dla Feishu
Gateway jest uruchomiony (openclaw gateway status)

W Event Subscription:

Wybierz Use long connection to receive events (WebSocket)
Dodaj zdarzenie: im.message.receive_v1

⚠️ Jeśli gateway nie jest uruchomiony, konfiguracja długiego połączenia może nie zapisać się poprawnie. Configure event subscription

7. Opublikuj aplikację

Utwórz wersję w Version Management & Release
Wyślij do przeglądu i opublikuj
Poczekaj na zatwierdzenie przez administratora (aplikacje enterprise zwykle są zatwierdzane automatycznie)

Krok 2: Skonfiguruj OpenClaw

Konfiguracja za pomocą kreatora (zalecane)

openclaw channels add

Wybierz Feishu i wklej App ID oraz App Secret.

Konfiguracja przez plik konfiguracyjny

Edytuj ~/.openclaw/openclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
        },
      },
    },
  },
}

Konfiguracja przez zmienne środowiskowe

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Domena Lark (globalna)

Jeśli Twój tenant korzysta z Lark (międzynarodowego), ustaw domenę na lark (lub pełny ciąg domeny). Możesz ustawić ją w channels.feishu.domain lub per konto (channels.feishu.accounts.<id>.domain).

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Krok 3: Uruchomienie i test

1. Uruchom gateway

openclaw gateway

2. Wyślij wiadomość testową

W Feishu znajdź swojego bota i wyślij wiadomość.

3. Zatwierdź parowanie

Domyślnie bot odpowiada kodem parowania. Zatwierdź go:

openclaw pairing approve feishu <CODE>

Po zatwierdzeniu możesz normalnie prowadzić rozmowę.

Przegląd

Kanał bota Feishu: bot Feishu zarządzany przez gateway
Deterministyczne routowanie: odpowiedzi zawsze wracają do Feishu
Izolacja sesji: DM-y współdzielą główną sesję; grupy są izolowane
Połączenie WebSocket: długie połączenie przez SDK Feishu, bez potrzeby publicznego URL-a

Kontrola dostępu

Wiadomości bezpośrednie

Domyślnie: dmPolicy: "pairing" (nieznani użytkownicy otrzymują kod parowania)

Zatwierdzanie parowania:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Tryb listy dozwolonych: ustaw channels.feishu.allowFrom z dozwolonymi Open ID

Czaty grupowe

1. Polityka grup (channels.feishu.groupPolicy):

"open" = zezwól wszystkim w grupach (domyślnie)
"allowlist" = zezwól tylko groupAllowFrom
"disabled" = wyłącz wiadomości grupowe

2. Wymóg wzmianki (channels.feishu.groups.<chat_id>.requireMention):

true = wymagaj @wzmianki (domyślnie)
false = odpowiadaj bez wzmianek

Przykłady konfiguracji grup

Zezwól na wszystkie grupy, wymagaj @wzmianki (domyślnie)

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // Default requireMention: true
    },
  },
}

Zezwól na wszystkie grupy, bez wymogu @wzmianki

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Zezwól tylko określonym użytkownikom w grupach

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

Uzyskiwanie identyfikatorów grup/użytkowników

ID grup (chat_id)

Identyfikatory grup wyglądają jak oc_xxx. Metoda 1 (zalecana)

Uruchom gateway i @wzmiankuj bota w grupie
Uruchom openclaw logs --follow i znajdź chat_id

Metoda 2 Użyj debuggera API Feishu do wylistowania czatów grupowych.

ID użytkowników (open_id)

Identyfikatory użytkowników wyglądają jak ou_xxx. Metoda 1 (zalecana)

Uruchom gateway i wyślij botowi DM
Uruchom openclaw logs --follow i znajdź open_id

Metoda 2 Sprawdź żądania parowania pod kątem Open ID użytkowników:

openclaw pairing list feishu

Typowe polecenia

Polecenie	Opis
`/status`	Pokaż status bota
`/reset`	Zresetuj sesję
`/model`	Pokaż/przełącz model

Uwaga: Feishu nie obsługuje jeszcze natywnych menu poleceń, dlatego polecenia muszą być wysyłane jako tekst.

Polecenia zarządzania gateway

Polecenie	Opis
`openclaw gateway status`	Pokaż status gateway
`openclaw gateway install`	Zainstaluj/uruchom usługę gateway
`openclaw gateway stop`	Zatrzymaj usługę gateway
`openclaw gateway restart`	Zrestartuj usługę gateway
`openclaw logs --follow`	Śledź logi gateway

Rozwiązywanie problemów

Bot nie odpowiada w czatach grupowych

Upewnij się, że bot został dodany do grupy
Upewnij się, że @wzmiankujesz bota (zachowanie domyślne)
Sprawdź, czy groupPolicy nie jest ustawione na "disabled"
Sprawdź logi: openclaw logs --follow

Bot nie odbiera wiadomości

Upewnij się, że aplikacja jest opublikowana i zatwierdzona
Upewnij się, że subskrypcja zdarzeń obejmuje im.message.receive_v1
Upewnij się, że włączone jest długie połączenie
Upewnij się, że uprawnienia aplikacji są kompletne
Upewnij się, że gateway jest uruchomiony: openclaw gateway status
Sprawdź logi: openclaw logs --follow

Wyciek App Secret

Zresetuj App Secret w Feishu Open Platform
Zaktualizuj App Secret w konfiguracji
Zrestartuj gateway

Błędy wysyłania wiadomości

Upewnij się, że aplikacja ma uprawnienie im:message:send_as_bot
Upewnij się, że aplikacja jest opublikowana
Sprawdź logi w poszukiwaniu szczegółowych błędów

Konfiguracja zaawansowana

Wiele kont

{
  channels: {
    feishu: {
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

Limity wiadomości

textChunkLimit: rozmiar fragmentu tekstu wychodzącego (domyślnie: 2000 znaków)
mediaMaxMb: limit wysyłania/pobierania mediów (domyślnie: 30 MB)

Strumieniowanie

Feishu obsługuje strumieniowe odpowiedzi za pomocą kart interaktywnych. Po włączeniu bot aktualizuje kartę w miarę generowania tekstu.

{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default true)
      blockStreaming: true, // enable block-level streaming (default true)
    },
  },
}

Ustaw streaming: false, aby czekać na pełną odpowiedź przed wysłaniem.

Routowanie wieloagentowe

Użyj bindings do kierowania DM-ów lub grup Feishu do różnych agentów.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Pola routowania:

match.channel: "feishu"
match.peer.kind: "direct" or "group"
match.peer.id: Open ID użytkownika (ou_xxx) lub ID grupy (oc_xxx)

Zobacz Uzyskiwanie identyfikatorów grup/użytkowników, aby uzyskać wskazówki.

Referencja konfiguracji

Pełna konfiguracja: Konfiguracja Gateway Kluczowe opcje:

Ustawienie	Opis	Domyślne
`channels.feishu.enabled`	Włącz/wyłącz kanał	`true`
`channels.feishu.domain`	Domena API (`feishu` lub `lark`)	`feishu`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	Nadpisanie domeny API per konto	`feishu`
`channels.feishu.dmPolicy`	Polityka DM	`pairing`
`channels.feishu.allowFrom`	Lista dozwolonych DM (lista open_id)	-
`channels.feishu.groupPolicy`	Polityka grup	`open`
`channels.feishu.groupAllowFrom`	Lista dozwolonych grup	-
`channels.feishu.groups.<chat_id>.requireMention`	Wymagaj @wzmianki	`true`
`channels.feishu.groups.<chat_id>.enabled`	Włącz grupy	`true`
`channels.feishu.textChunkLimit`	Rozmiar fragmentu wiadomości	`2000`
`channels.feishu.mediaMaxMb`	Limit rozmiaru mediów	`30`
`channels.feishu.streaming`	Włącz strumieniowe wyjście kart	`true`
`channels.feishu.blockStreaming`	Włącz strumieniowanie blokowe	`true`

Referencja dmPolicy

Wartość	Zachowanie
`"pairing"`	Domyślne. Nieznani użytkownicy otrzymują kod parowania; muszą zostać zatwierdzeni
`"allowlist"`	Tylko użytkownicy z `allowFrom` mogą prowadzić rozmowę
`"open"`	Zezwól wszystkim użytkownikom (wymaga `"*"` w allowFrom)
`"disabled"`	Wyłącz DM-y

Obsługiwane typy wiadomości

Odbiór

✅ Tekst
✅ Tekst sformatowany (post)
✅ Obrazy
✅ Pliki
✅ Audio
✅ Wideo
✅ Naklejki

Wysyłanie

✅ Tekst
✅ Obrazy
✅ Pliki
✅ Audio
⚠️ Tekst sformatowany (częściowe wsparcie)

​Bot Feishu

​Wymagana wtyczka

​Szybki start

​Metoda 1: kreator onboardingu (zalecane)

​Metoda 2: konfiguracja przez CLI

​Krok 1: Utwórz aplikację Feishu

​1. Otwórz Feishu Open Platform

​2. Utwórz aplikację

​3. Skopiuj poświadczenia

​4. Skonfiguruj uprawnienia

​5. Włącz możliwości bota

​6. Skonfiguruj subskrypcję zdarzeń

​7. Opublikuj aplikację

​Krok 2: Skonfiguruj OpenClaw

​Konfiguracja za pomocą kreatora (zalecane)

​Konfiguracja przez plik konfiguracyjny

​Konfiguracja przez zmienne środowiskowe

​Domena Lark (globalna)

​Krok 3: Uruchomienie i test

​1. Uruchom gateway

​2. Wyślij wiadomość testową

​3. Zatwierdź parowanie

​Przegląd

​Kontrola dostępu

​Wiadomości bezpośrednie

​Czaty grupowe

​Przykłady konfiguracji grup

​Zezwól na wszystkie grupy, wymagaj @wzmianki (domyślnie)

​Zezwól na wszystkie grupy, bez wymogu @wzmianki

​Zezwól tylko określonym użytkownikom w grupach

​Uzyskiwanie identyfikatorów grup/użytkowników

​ID grup (chat_id)

​ID użytkowników (open_id)

​Typowe polecenia

​Polecenia zarządzania gateway

​Rozwiązywanie problemów

​Bot nie odpowiada w czatach grupowych

​Bot nie odbiera wiadomości

​Wyciek App Secret

​Błędy wysyłania wiadomości

​Konfiguracja zaawansowana

​Wiele kont

​Limity wiadomości

​Strumieniowanie

​Routowanie wieloagentowe

​Referencja konfiguracji

​Referencja dmPolicy

​Obsługiwane typy wiadomości

​Odbiór

​Wysyłanie