​

Bot Feishu

​

Dołączony plugin

openclaw plugins install @openclaw/feishu

​

Szybki start

​

Metoda 1: onboarding (zalecane)

openclaw onboard

1. Utworzenie aplikacji Feishu i zebranie danych uwierzytelniających
2. Skonfigurowanie danych uwierzytelniających aplikacji w OpenClaw
3. Uruchomienie gateway

• openclaw gateway status
• openclaw logs --follow

​

Metoda 2: konfiguracja przez CLI

openclaw channels add

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

​

Krok 1: Utwórz aplikację Feishu

​

1. Otwórz Feishu Open Platform

​

2. Utwórz aplikację

1. Kliknij Create enterprise app
2. Wypełnij nazwę i opis aplikacji
3. Wybierz ikonę aplikacji

​

3. Skopiuj dane uwierzytelniające

• App ID (format: cli_xxx)
• App Secret

​

4. Skonfiguruj uprawnienia

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card: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

1. Włącz możliwości bota
2. Ustaw nazwę bota

​

6. Skonfiguruj subskrypcję zdarzeń

1. openclaw channels add zostało już uruchomione dla Feishu
2. Gateway jest uruchomiony (openclaw gateway status)

1. Wybierz Use long connection to receive events (WebSocket)
2. Dodaj zdarzenie: im.message.receive_v1
3. (Opcjonalnie) Dla workflow komentarzy Drive dodaj też: drive.notice.comment_add_v1

​

7. Opublikuj aplikację

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

​

Krok 2: Skonfiguruj OpenClaw

​

Skonfiguruj za pomocą kreatora (zalecane)

openclaw channels add

​

Skonfiguruj przez plik config

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Mój asystent AI",
        },
      },
    },
  },
}

​

Verification Token i Encrypt Key (tryb webhook)

1. W Feishu Open Platform otwórz swoją aplikację
2. Przejdź do Development → Events & Callbacks (开发配置 → 事件与回调)
3. Otwórz kartę Encryption (加密策略)
4. Skopiuj Verification Token i Encrypt Key

​

Skonfiguruj przez zmienne środowiskowe

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

​

Domena Lark (globalna)

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

​

Flagi optymalizacji limitów

• typingIndicator (domyślnie true): gdy ustawione na false, pomija wywołania reakcji wpisywania.
• resolveSenderNames (domyślnie true): gdy ustawione na false, pomija wywołania wyszukiwania profilu nadawcy.

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

​

Krok 3: Uruchom + przetestuj

​

1. Uruchom gateway

openclaw gateway

​

2. Wyślij wiadomość testową

​

3. Zatwierdź parowanie

openclaw pairing approve feishu <CODE>

​

Przegląd

• Kanał bota Feishu: bot Feishu zarządzany przez gateway
• Deterministyczne routowanie: odpowiedzi zawsze wracają do Feishu
• Izolacja sesji: wiadomości prywatne współdzielą główną sesję; grupy są izolowane
• Połączenie WebSocket: long connection przez SDK Feishu, bez potrzeby używania publicznego URL

​

Kontrola dostępu

​

Wiadomości prywatne

• Domyślnie: dmPolicy: "pairing" (nieznani użytkownicy otrzymują kod parowania)
• Zatwierdź parowanie:
  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  
• Tryb allowlist: ustaw channels.feishu.allowFrom z dozwolonymi Open ID

​

Czaty grupowe

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

• jawne true = wymagaj @wzmianki
• jawne false = odpowiadaj bez wzmianek
• gdy nieustawione i groupPolicy: "open" = domyślnie false
• gdy nieustawione i groupPolicy nie jest "open" = domyślnie true

​

Przykłady konfiguracji grup

​

Zezwól na wszystkie grupy, bez wymagania @wzmianki (domyślnie dla otwartych grup)

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

​

Zezwól na wszystkie grupy, ale nadal wymagaj @wzmianki

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

​

Zezwól tylko na określone grupy

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Identyfikatory grup Feishu (chat_id) wyglądają tak: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

​

Ogranicz, którzy nadawcy mogą wysyłać wiadomości w grupie (allowlist nadawców)

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Identyfikatory użytkowników Feishu (open_id) wyglądają tak: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

​

Pobieranie identyfikatorów grup/użytkowników

​

Identyfikatory grup (chat_id)

1. Uruchom gateway i użyj @wzmianki bota w grupie
2. Uruchom openclaw logs --follow i poszukaj chat_id

​

Identyfikatory użytkowników (open_id)

1. Uruchom gateway i wyślij wiadomość prywatną do bota
2. Uruchom openclaw logs --follow i poszukaj open_id

openclaw pairing list feishu

​

Typowe polecenia

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

​

Polecenia zarządzania gateway

​

Rozwiązywanie problemów

​

Bot nie odpowiada w czatach grupowych

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

​

Bot nie odbiera wiadomości

1. Upewnij się, że aplikacja została opublikowana i zatwierdzona
2. Upewnij się, że subskrypcja zdarzeń zawiera im.message.receive_v1
3. Upewnij się, że long connection jest włączone
4. Upewnij się, że uprawnienia aplikacji są kompletne
5. Upewnij się, że gateway jest uruchomiony: openclaw gateway status
6. Sprawdź logi: openclaw logs --follow

​

Wyciek App Secret

1. Zresetuj App Secret w Feishu Open Platform
2. Zaktualizuj App Secret w swojej konfiguracji
3. Uruchom ponownie gateway

​

Błędy wysyłania wiadomości

1. Upewnij się, że aplikacja ma uprawnienie im:message:send_as_bot
2. Upewnij się, że aplikacja została opublikowana
3. Sprawdź logi pod kątem szczegółowych błędów

​

Zaawansowana konfiguracja

​

Wiele kont

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Podstawowy bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Zapasowy bot",
          enabled: false,
        },
      },
    },
  },
}

​

Limity wiadomości

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

​

Streaming

{
  channels: {
    feishu: {
      streaming: true, // włącz wyjście strumieniowe kart (domyślnie true)
      blockStreaming: true, // włącz streaming na poziomie bloków (domyślnie true)
    },
  },
}

​

Sesje ACP

• wiadomości prywatnych
• rozmów grupowych w wątkach tematycznych

​

Trwałe powiązania 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 powiązanego z wątkiem z czatu

/acp spawn codex --thread here

• --thread here działa dla wiadomości prywatnych i tematów Feishu.
• Kolejne wiadomości w powiązanej wiadomości prywatnej/temacie są routowane bezpośrednio do tej sesji ACP.
• Wersja v1 nie obsługuje ogólnych czatów grupowych bez tematów.

​

Routowanie wielu 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" },
      },
    },
  ],
}

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

​

Odniesienie do konfiguracji

​

Odniesienie do dmPolicy

​

Obsługiwane typy wiadomości

​

Odbieranie

• ✅ Tekst
• ✅ Tekst sformatowany (post)
• ✅ Obrazy
• ✅ Pliki
• ✅ Audio
• ✅ Wideo/media
• ✅ Naklejki

​

Wysyłanie

• ✅ Tekst
• ✅ Obrazy
• ✅ Pliki
• ✅ Audio
• ✅ Wideo/media
• ✅ Karty interaktywne
• ⚠️ Tekst sformatowany (formatowanie w stylu post i karty, ale nie dowolne funkcje autorskie Feishu)

​

Wątki i odpowiedzi

• ✅ Odpowiedzi inline
• ✅ Odpowiedzi w wątkach tematycznych, gdy Feishu udostępnia reply_in_thread
• ✅ Odpowiedzi multimedialne zachowują świadomość wątku podczas odpowiadania na wiadomość w wątku/temacie

​

Komentarze Drive

• Subskrybuj drive.notice.comment_add_v1 w ustawieniach subskrypcji zdarzeń aplikacji Feishu (obok istniejącego im.message.receive_v1)
• Narzędzie Drive jest domyślnie włączone; wyłącz je przez channels.feishu.tools.drive: false

• treść komentarza i nadawcę
• metadane dokumentu (tytuł, typ, URL)
• kontekst wątku komentarzy do odpowiedzi w wątku

​

Powierzchnia akcji runtime

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react i reactions, gdy reakcje są włączone w konfiguracji
• akcje komentarzy feishu_drive: list_comments, list_comment_replies, add_comment, reply_comment

​

Powiązane

• Przegląd kanałów — wszystkie obsługiwane kanały
• Pairing — uwierzytelnianie wiadomości prywatnych i przepływ parowania
• Grupy — zachowanie czatów grupowych i filtrowanie wzmiankami
• Routowanie kanałów — routowanie sesji dla wiadomości
• Bezpieczeństwo — model dostępu i wzmacnianie zabezpieczeń