Feishu

OpenClaw łączy się z Feishu/Lark (kompleksową platformą współpracy) za pośrednictwem oficjalnego pluginu @openclaw/feishu: wiadomości prywatne z botem, czaty grupowe, strumieniowe odpowiedzi w kartach oraz narzędzia Feishu do dokumentów, wiki, dysku i Bitable.

Stan: gotowe do użytku produkcyjnego w przypadku wiadomości prywatnych z botem i czatów grupowych. WebSocket jest domyślnym transportem zdarzeń (publiczny adres URL nie jest wymagany); tryb webhooka jest opcjonalny.

Szybki start

openclaw channels login --channel feishu

openclaw gateway restart

Kontrola dostępu

Wiadomości prywatne

Skonfiguruj channels.feishu.dmPolicy (domyślnie: pairing), aby określić, kto może wysyłać botowi wiadomości prywatne:

Zatwierdzanie żądania parowania:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Czaty grupowe

Zasady grup (channels.feishu.groupPolicy, domyślnie: allowlist):

Wymóg wzmianki (channels.feishu.requireMention):

• Domyślnie: wymagana jest @wzmianka, z wyjątkiem sytuacji, gdy obowiązującą zasadą grup jest "open"; wtedy wartością domyślną jest false, dzięki czemu wiadomości, które nie mogą zawierać wzmianek (na przykład obrazy), nadal docierają do agenta.
• Aby zastąpić to ustawienie, jawnie ustaw true lub false; ustawienie dla poszczególnych grup: channels.feishu.groups.<chat_id>.requireMention.
• Wzmianki służące wyłącznie do rozgłaszania, @all i @_all, nie są traktowane jako wzmianki o bocie. Wiadomość zawierająca zarówno wzmiankę @all, jak i bezpośrednią wzmiankę o bocie nadal jest uznawana za wzmiankę o bocie.

Przykłady konfiguracji grup

Zezwalanie na wszystkie grupy bez wymagania @wzmianki

{  channels: {    feishu: {      groupPolicy: "open", // requireMention ma domyślnie wartość false przy ustawieniu "open"    },  },}

Zezwalanie na wszystkie grupy z nadal wymaganą @wzmianką

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

Zezwalanie tylko na określone grupy

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Identyfikatory grup mają postać: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

W trybie allowlist można również dopuścić grupę, dodając jawny wpis groups.<chat_id>. Jawne wpisy nie zastępują groupPolicy: "disabled". Domyślne ustawienia z symbolem wieloznacznym w groups.* konfigurują pasujące grupy, ale same ich nie dopuszczają.

{  channels: {    feishu: {      groupPolicy: "allowlist",      groups: {        oc_xxx: {          requireMention: false,        },      },    },  },}

Ograniczanie nadawców w grupie

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // Identyfikatory open_id użytkowników mają postać: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom ustawia tę samą listę dozwolonych nadawców dla wszystkich grup; ustawienie allowFrom dla konkretnej grupy ma pierwszeństwo.

Uzyskiwanie identyfikatorów grup i użytkowników

Identyfikatory grup (chat_id, format: oc_xxx)

Otwórz grupę w Feishu/Lark, kliknij ikonę menu w prawym górnym rogu i przejdź do Settings. Identyfikator grupy (chat_id) znajduje się na stronie ustawień.

Identyfikatory użytkowników (open_id, format: ou_xxx)

Uruchom Gateway, wyślij botowi wiadomość prywatną, a następnie sprawdź dzienniki:

openclaw logs --follow

W danych wyjściowych dziennika wyszukaj open_id. Można również sprawdzić oczekujące żądania parowania:

openclaw pairing list feishu

Typowe polecenia

Rozwiązywanie problemów

Bot nie odpowiada na czatach grupowych

1. Upewnij się, że bot został dodany do grupy
2. Upewnij się, że użyto @wzmianki o bocie (domyślnie wymagane)
3. Sprawdź, czy groupPolicy nie ma wartości "disabled"
4. Sprawdź dzienniki: openclaw logs --follow

Bot nie otrzymuje wiadomości

1. Upewnij się, że bot został opublikowany i zatwierdzony w Feishu Open Platform / Lark Developer
2. Upewnij się, że subskrypcja zdarzeń obejmuje im.message.receive_v1
3. Upewnij się, że wybrano persistent connection (WebSocket)
4. Upewnij się, że przyznano wszystkie wymagane zakresy uprawnień
5. Upewnij się, że Gateway działa: openclaw gateway status
6. Sprawdź dzienniki: openclaw logs --follow

Konfiguracja za pomocą kodu QR nie wywołuje reakcji w aplikacji mobilnej Feishu

1. Uruchom konfigurację ponownie: openclaw channels login --channel feishu
2. Wybierz konfigurację ręczną
3. W Feishu Open Platform utwórz aplikację własną i skopiuj jej App ID oraz App Secret
4. Wklej te dane uwierzytelniające w kreatorze konfiguracji

Wyciek App Secret

1. Zresetuj App Secret w Feishu Open Platform / Lark Developer
2. Zaktualizuj wartość w konfiguracji
3. Uruchom ponownie Gateway: openclaw gateway restart

Konfiguracja zaawansowana

Wiele kont

{  channels: {    feishu: {      defaultAccount: "main",      accounts: {        main: {          appId: "cli_xxx",          appSecret: "xxx",          name: "Główny bot",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "Bot zapasowy",          enabled: false,        },      },    },  },}

defaultAccount określa, które konto jest używane, gdy wychodzące interfejsy API nie podają accountId. Wpisy kont dziedziczą ustawienia najwyższego poziomu; większość kluczy najwyższego poziomu można zastąpić dla poszczególnych kont. accounts.<id>.tts ma taką samą strukturę jak messages.tts i jest głęboko scalane z globalną konfiguracją TTS, dzięki czemu konfiguracje Feishu z wieloma botami mogą przechowywać wspólne dane uwierzytelniające dostawców globalnie, zastępując dla poszczególnych kont tylko głos, model, personę lub tryb automatyczny.

Limity wiadomości

• textChunkLimit — rozmiar fragmentu tekstu wychodzącego (domyślnie: 4000 znaków)
• streaming.chunkMode — "length" (domyślnie) dzieli tekst po osiągnięciu limitu; "newline" preferuje granice nowych wierszy
• mediaMaxMb — limit wysyłania i pobierania multimediów (domyślnie: 30 MB)

Przesyłanie strumieniowe

Feishu/Lark obsługuje odpowiedzi strumieniowe za pomocą kart interaktywnych (interfejs API przesyłania strumieniowego Card Kit). Po włączeniu bot aktualizuje kartę w czasie rzeczywistym podczas generowania tekstu.

{  channels: {    feishu: {      streaming: {        mode: "partial", // strumieniowe dane wyjściowe w karcie (domyślnie: "partial")        block: { enabled: true }, // włącza przesyłanie strumieniowe ukończonych bloków      },    },  },}

Ustaw streaming.mode: "off", aby wysyłać pełną odpowiedź w jednej wiadomości; renderMode: "raw" (zwykły tekst zamiast kart) również wyłącza karty strumieniowe. streaming.block.enabled jest domyślnie wyłączone; należy je włączyć tylko wtedy, gdy ukończone bloki asystenta mają być wysyłane przed odpowiedzią końcową. Starsza wartość logiczna streaming oraz płaskie klucze blockStreaming / blockStreamingCoalesce / chunkMode są migrowane do tej zagnieżdżonej struktury za pomocą openclaw doctor --fix.

Optymalizacja limitu użycia

Liczbę wywołań interfejsu API Feishu/Lark można ograniczyć za pomocą dwóch opcjonalnych flag:

• typingIndicator (domyślnie true): ustaw false, aby pomijać wywołania reakcji sygnalizującej pisanie
• resolveSenderNames (domyślnie true): ustaw false, aby pomijać wyszukiwanie profilu nadawcy

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false,    },  },}

Zakres sesji grupowej i wątki tematyczne

channels.feishu.groupSessionScope (na najwyższym poziomie, dla poszczególnych kont lub grup) określa sposób mapowania wiadomości grupowych na sesje agenta:

W przypadku zakresów tematycznych natywne grupy tematyczne Feishu/Lark używają zdarzenia thread_id (omt_*) jako kanonicznego klucza sesji tematu. Jeśli natywne zdarzenie rozpoczynające temat nie zawiera thread_id, OpenClaw pobiera tę wartość z Feishu przed przekierowaniem tury. Zwykłe odpowiedzi grupowe przekształcane przez OpenClaw w wątki nadal używają identyfikatora wiadomości głównej odpowiedzi (om_*), dzięki czemu pierwsza i kolejne tury pozostają w tej samej sesji.

Ustaw replyInThread: "enabled" (na najwyższym poziomie lub dla poszczególnych grup), aby odpowiedzi bota tworzyły lub kontynuowały wątek tematyczny Feishu zamiast odpowiadać bezpośrednio. topicSessionMode jest przestarzałym poprzednikiem groupSessionScope; preferowane jest groupSessionScope.

Narzędzia przestrzeni roboczej Feishu

Plugin zawiera narzędzia agenta do dokumentów Feishu, czatów, bazy wiedzy, pamięci masowej w chmurze, uprawnień i Bitable, a także odpowiadające im Skills (feishu-doc, feishu-drive, feishu-perm, feishu-wiki). Rodziny narzędzi są kontrolowane przez channels.feishu.tools:

tools.base jest aliasem tools.bitable; gdy ustawiono obie wartości, pierwszeństwo ma jawna wartość bitable. Ograniczenia dla poszczególnych kont znajdują się w accounts.<id>.tools.

Należy przyznać drive:drive.metadata:readonly na potrzeby bezpośrednich wyszukiwań feishu_drive info poza katalogiem głównym, chyba że aplikacja ma już pełny zakres drive:drive. Bez żadnego z tych zakresów info zachowuje dotychczasowe wyszukiwanie w katalogu głównym dostępne przez drive:drive:readonly.

Sesje ACP

Feishu/Lark obsługuje ACP dla wiadomości prywatnych i wiadomości w wątkach grupowych. ACP w Feishu/Lark jest sterowane poleceniami tekstowymi — nie ma natywnych menu poleceń z ukośnikiem, dlatego wiadomości /acp ... należy wpisywać bezpośrednio w rozmowie.

Trwałe powiązanie ACP

{  agents: {    list: [      {        id: "codex",        runtime: {          type: "acp",          acp: {            agent: "codex",            backend: "acpx",            mode: "persistent",            cwd: "/workspace/openclaw",          },        },      },    ],  },  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "feishu",        accountId: "default",        peer: { kind: "direct", id: "ou_1234567890" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "feishu",        accountId: "default",        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },      },      acp: { label: "codex-feishu-topic" },    },  ],}

Uruchamianie ACP z czatu

W wiadomości prywatnej lub wątku Feishu/Lark:

/acp spawn codex --thread here

--thread here działa w wiadomościach prywatnych i wiadomościach w wątkach Feishu/Lark. Kolejne wiadomości w powiązanej rozmowie są kierowane bezpośrednio do tej sesji ACP.

Kierowanie do wielu agentów

Należy użyć bindings, aby kierować wiadomości prywatne lub grupy Feishu/Lark do różnych agentów.

{  agents: {    list: [      { id: "main" },      { id: "agent-a", workspace: "/home/user/agent-a" },      { id: "agent-b", workspace: "/home/user/agent-b" },    ],  },  bindings: [    {      agentId: "agent-a",      match: {        channel: "feishu",        peer: { kind: "direct", id: "ou_xxx" },      },    },    {      agentId: "agent-b",      match: {        channel: "feishu",        peer: { kind: "group", id: "oc_zzz" },      },    },  ],}

Pola kierowania:

• match.channel: "feishu"
• match.peer.kind: "direct" (wiadomość prywatna) lub "group" (czat grupowy)
• match.peer.id: identyfikator Open ID użytkownika (ou_xxx) lub identyfikator grupy (oc_xxx)

Wskazówki dotyczące wyszukiwania zawiera sekcja Uzyskiwanie identyfikatorów grup i użytkowników.

Izolacja agenta dla każdego użytkownika (dynamiczne tworzenie agentów)

Należy włączyć dynamicAgentCreation, aby automatycznie tworzyć izolowane instancje agentów dla każdego użytkownika wiadomości prywatnych. Każdy użytkownik otrzymuje własne:

• Niezależny katalog przestrzeni roboczej
• Oddzielne USER.md / SOUL.md / MEMORY.md
• Prywatną historię rozmów
• Izolowane umiejętności i stan

Jest to niezbędne w przypadku publicznych botów, gdy każdy użytkownik ma korzystać z własnego, prywatnego asystenta AI.

Szybka konfiguracja

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Kluczowe: ustawia wiadomości prywatne każdego użytkownika jako jego „sesję główną”    // Automatycznie wczytuje USER.md / SOUL.md / MEMORY.md    // Aby uzyskać silniejszą izolację, należy zamiast tego użyć "per-channel-peer"    dmScope: "main",  },}

Jak to działa

Gdy nowy użytkownik wysyła pierwszą wiadomość prywatną:

1. Kanał generuje unikatowy agentId: feishu-{user_open_id} dla konta domyślnego albo ograniczony skrót tożsamości z prefiksem konta dla konta nazwanego
2. Tworzy nową przestrzeń roboczą w ścieżce workspaceTemplate
3. Rejestruje agenta i tworzy powiązanie dla tego użytkownika
4. Przy pierwszym dostępie pomocnik przestrzeni roboczej zapewnia obecność plików inicjalizacyjnych (AGENTS.md, SOUL.md, USER.md itd.)
5. Kieruje wszystkie przyszłe wiadomości tego użytkownika do jego dedykowanego agenta

Opcje konfiguracji

Zmienne szablonu:

• {agentId} — wygenerowany identyfikator agenta (np. feishu-ou_xxxxxx lub feishu-support-<identity_digest>)
• {userId} — identyfikator open_id nadawcy w Feishu (np. ou_xxxxxx)

Zakres sesji

session.dmScope określa sposób mapowania wiadomości prywatnych na sesje agentów. Jest to ustawienie globalne, które wpływa na wszystkie kanały.

Kompromis: użycie "main" umożliwia automatyczne wczytywanie plików inicjalizacyjnych (USER.md, SOUL.md, MEMORY.md), ale oznacza, że wszystkie wiadomości prywatne we wszystkich kanałach korzystają z tego samego wzorca klucza sesji. W przypadku publicznych botów dla wielu użytkowników, w których izolacja jest ważniejsza niż automatyczne wczytywanie plików inicjalizacyjnych, warto rozważyć "per-channel-peer" i zarządzać plikami inicjalizacyjnymi ręcznie.

Typowe wdrożenie dla wielu użytkowników

{  channels: {    feishu: {      appId: "cli_xxx",      appSecret: "xxx",      dmPolicy: "open",      allowFrom: ["*"],      groupPolicy: "open",      requireMention: true,      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Wybierz dmScope zgodnie z potrzebami dotyczącymi izolacji:    // "main" zapewnia automatyczne wczytywanie plików inicjalizacyjnych, a "per-channel-peer" silniejszą izolację    dmScope: "main",  },  bindings: [], // Puste — dynamiczni agenci tworzą powiązania automatycznie}

Weryfikacja

Należy sprawdzić dzienniki Gateway, aby potwierdzić, że dynamiczne tworzenie działa:

feishu: tworzenie dynamicznego agenta "feishu-ou_xxxxxx" dla użytkownika ou_xxxxxx  przestrzeń robocza: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  katalog agenta: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Wyświetlenie wszystkich utworzonych przestrzeni roboczych:

ls -la ~/.openclaw/workspace-*

Uwagi

• Izolacja przestrzeni roboczej: każdy użytkownik otrzymuje własny katalog przestrzeni roboczej i instancję agenta. W normalnym przepływie wiadomości użytkownicy nie mogą przeglądać historii rozmów ani plików innych użytkowników.
• Granica bezpieczeństwa: jest to mechanizm izolacji kontekstu wiadomości, a nie granica bezpieczeństwa chroniąca przed wrogimi współdzierżawcami. Proces agenta i środowisko hosta są współdzielone.
• Zapisywanie konfiguracji musi pozostać włączone: dynamiczne tworzenie agentów zapisuje agentów i powiązania w konfiguracji; jest pomijane, gdy channels.feishu.configWrites ma wartość false (domyślnie: włączone).
• bindings powinno być puste: dynamiczni agenci automatycznie rejestrują własne powiązania
• Ścieżka uaktualnienia: istniejące ręczne powiązania nadal działają równolegle z dynamicznymi agentami
• session.dmScope jest globalne: wpływa to na wszystkie kanały, nie tylko Feishu

Dokumentacja konfiguracji

Pełna konfiguracja: Konfiguracja Gateway

Obsługiwane typy wiadomości

Odbieranie

• ✅ Tekst
• ✅ Tekst sformatowany (post)
• ✅ Obrazy
• ✅ Pliki
• ✅ Dźwięk
• ✅ Wideo/multimedia
• ✅ Naklejki

Przychodzące wiadomości dźwiękowe Feishu/Lark są normalizowane jako symbole zastępcze multimediów zamiast surowych danych JSON file_key. Gdy skonfigurowano tools.media.audio, OpenClaw pobiera zasób notatki głosowej i przed turą agenta uruchamia współdzieloną transkrypcję dźwięku, dzięki czemu agent otrzymuje transkrypcję wypowiedzi. Jeśli Feishu umieszcza tekst transkrypcji bezpośrednio w ładunku dźwiękowym, jest on używany bez kolejnego wywołania ASR. Bez dostawcy transkrypcji dźwięku agent nadal otrzymuje symbol zastępczy <media:audio> wraz z zapisanym załącznikiem, a nie surowy ładunek zasobu Feishu.

Wysyłanie

• ✅ Tekst
• ✅ Obrazy
• ✅ Pliki
• ✅ Dźwięk
• ✅ Wideo/multimedia
• ✅ Karty interaktywne (w tym aktualizacje strumieniowe)
• ⚠️ Tekst sformatowany (formatowanie w stylu postu; nie obsługuje wszystkich możliwości tworzenia treści Feishu/Lark)

Natywne dymki dźwiękowe Feishu/Lark używają typu wiadomości Feishu audio i wymagają przesłania multimediów Ogg/Opus (file_type: "opus"). Istniejące multimedia .opus i .ogg są wysyłane bezpośrednio jako natywny dźwięk. Pliki MP3/WAV/M4A i inne prawdopodobne formaty dźwiękowe są transkodowane do Ogg/Opus 48 kHz za pomocą ffmpeg tylko wtedy, gdy odpowiedź wymaga dostarczenia głosowego (audioAsVoice / narzędzie wiadomości asVoice, w tym odpowiedzi TTS jako notatki głosowe). Zwykłe załączniki MP3 pozostają zwykłymi plikami. Jeśli brakuje ffmpeg lub konwersja się nie powiedzie, OpenClaw używa załącznika plikowego i zapisuje przyczynę w dzienniku.

Wątki i odpowiedzi

• ✅ Odpowiedzi w tekście
• ✅ Odpowiedzi w wątkach
• ✅ Odpowiedzi multimedialne zachowują powiązanie z wątkiem podczas odpowiadania na wiadomość w wątku

Routing sesji grup tematycznych opisano w sekcji Zakres sesji grupowej i wątki tematyczne.

Powiązane materiały

• Przegląd kanałów - wszystkie obsługiwane kanały
• Parowanie - uwierzytelnianie wiadomości prywatnych i proces parowania
• Grupy - zachowanie czatu grupowego i wymaganie wzmianek
• Routing kanałów - routing sesji dla wiadomości
• Bezpieczeństwo - model dostępu i wzmacnianie zabezpieczeń