Feishu-bot

Feishu (Lark) is een teamchatplatform dat door bedrijven wordt gebruikt voor berichtenverkeer en samenwerking. Deze plugin verbindt OpenClaw met een Feishu/Lark-bot via het WebSocket-eventabonnement van het platform, zodat berichten kunnen worden ontvangen zonder een publieke webhook-URL bloot te stellen.

Gebundelde plugin

Feishu wordt meegeleverd met huidige OpenClaw-releases, dus er is geen aparte plugin-installatie nodig.

Als je een oudere build of een aangepaste installatie gebruikt die geen gebundelde Feishu bevat, installeer deze dan handmatig:

openclaw plugins install @openclaw/feishu

Snelstart

Er zijn twee manieren om het Feishu-kanaal toe te voegen:

Methode 1: onboardingwizard (aanbevolen)

Als je net OpenClaw hebt geïnstalleerd, voer de wizard uit:

openclaw onboard

De wizard leidt je door:

1. Het aanmaken van een Feishu-app en het verzamelen van credentials
2. Het configureren van app-credentials in OpenClaw
3. Het starten van de gateway

Na configuratie, controleer de gatewaystatus:

• openclaw gateway status
• openclaw logs --follow

Methode 2: CLI-setup

Als je de initiële installatie al hebt voltooid, voeg het kanaal toe via CLI:

openclaw channels add

Kies Feishu en voer vervolgens de App ID en App Secret in.

Na configuratie, beheer de gateway:

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

Stap 1: Maak een Feishu-app aan

1. Open Feishu Open Platform

Ga naar Feishu Open Platform en log in.

Lark (globale) tenants moeten https://open.larksuite.com/app gebruiken en domain: "lark" instellen in de Feishu-configuratie.

2. Maak een app aan

1. Klik op Create enterprise app
2. Vul de appnaam + beschrijving in
3. Kies een app-icoon

3. Kopieer credentials

Uit Credentials & Basic Info, kopieer:

• App ID (formaat: cli_xxx)
• App Secret

Waarschuwing: houd de App Secret privé.

4. Configureer machtigingen

Op Permissions, klik op Batch import en plak:

{
  "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. Schakel botmogelijkheid in

In App Capability > Bot:

1. Schakel botmogelijkheid in
2. Stel de botnaam in

6. Configureer eventabonnement

Waarschuwing: voordat je het eventabonnement instelt, zorg ervoor dat:

1. Je al openclaw channels add hebt uitgevoerd voor Feishu
2. De gateway draait (openclaw gateway status)

In Event Subscription:

1. Kies Use long connection to receive events (WebSocket)
2. Voeg het event toe: im.message.receive_v1

Als de gateway niet draait, kan het opslaan van de long-connection-instelling mislukken.

7. Publiceer de app

1. Maak een versie aan in Version Management & Release
2. Dien in voor review en publiceer
3. Wacht op goedkeuring door de beheerder (bedrijfsapps worden meestal automatisch goedgekeurd)

Stap 2: Configureer OpenClaw

Configureer met de wizard (aanbevolen)

openclaw channels add

Kies Feishu en plak je App ID + App Secret.

Configureer via configuratiebestand

Bewerk ~/.openclaw/openclaw.json:

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

Als je connectionMode: "webhook" gebruikt, stel dan zowel verificationToken als encryptKey in. De Feishu-webhookserver bindt standaard aan 127.0.0.1; stel webhookHost alleen in als je bewust een ander bind-adres nodig hebt.

Verification Token en Encrypt Key (webhookmodus)

Bij gebruik van webhookmodus stel je zowel channels.feishu.verificationToken als channels.feishu.encryptKey in je configuratie in. Om de waarden te verkrijgen:

1. Open je app in Feishu Open Platform
2. Ga naar Development → Events & Callbacks (开发配置 → 事件与回调)
3. Open het tabblad Encryption (加密策略)
4. Kopieer Verification Token en Encrypt Key

De onderstaande schermafbeelding toont waar je het Verification Token kunt vinden. De Encrypt Key staat in dezelfde Encryption-sectie.

Configureer via omgevingsvariabelen

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

Lark (globaal) domein

Als je tenant op Lark (internationaal) zit, stel het domein in op lark (of een volledig domeinstring). Je kunt het instellen op channels.feishu.domain of per account (channels.feishu.accounts.<id>.domain).

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

Quotaoptimalisatievlaggen

Je kunt het Feishu-API-gebruik verminderen met twee optionele vlaggen:

• typingIndicator (standaard true): bij false worden typereactie-oproepen overgeslagen.
• resolveSenderNames (standaard true): bij false worden afzenderprofielzoekopdrachten overgeslagen.

Stel ze in op het hoogste niveau of per account:

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

Stap 3: Start + test

1. Start de gateway

openclaw gateway

2. Stuur een testbericht

Zoek je bot in Feishu en stuur een bericht.

3. Keur koppeling goed

Standaard antwoordt de bot met een koppelingscode. Keur deze goed:

openclaw pairing approve feishu <CODE>

Na goedkeuring kun je normaal chatten.

Overzicht

• Feishu-botkanaal: Feishu-bot beheerd door de gateway
• Deterministische routering: antwoorden gaan altijd terug naar Feishu
• Sessie-isolatie: DM’s delen een hoofdsessie; groepen zijn geïsoleerd
• WebSocket-verbinding: langverbinding via Feishu SDK, geen publieke URL nodig

Toegangscontrole

Directe berichten

• Standaard: dmPolicy: "pairing" (onbekende gebruikers krijgen een koppelingscode)

• Koppeling goedkeuren:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Allowlistmodus: stel channels.feishu.allowFrom in met toegestane Open ID’s

Groepschats

1. Groepsbeleid (channels.feishu.groupPolicy):

• "open" = iedereen toestaan in groepen (standaard)
• "allowlist" = alleen groupAllowFrom toestaan
• "disabled" = groepsberichten uitschakelen

2. Vermeldingsvereiste (channels.feishu.groups.<chat_id>.requireMention):

• true = @vermelding vereist (standaard)
• false = antwoorden zonder vermeldingen

Groepsconfiguratie-voorbeelden

Alle groepen toestaan, @vermelding vereist (standaard)

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

Alle groepen toestaan, geen @vermelding vereist

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

Alleen specifieke groepen toestaan

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu groeps-ID's (chat_id) zien eruit als: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Beperk welke afzenders berichten mogen sturen in een groep (afzender-allowlist)

Naast het toestaan van de groep zelf, worden alle berichten in die groep gefilterd op de open_id van de afzender: alleen gebruikers in groups.<chat_id>.allowFrom worden verwerkt; berichten van andere leden worden genegeerd (dit is volledige afzenderniveau-filtering, niet alleen voor besturingscommando’s zoals /reset of /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu gebruikers-ID's (open_id) zien eruit als: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Groeps-/gebruikers-ID’s opzoeken

Groeps-ID’s (chat_id)

Groeps-ID’s zien eruit als oc_xxx.

Methode 1 (aanbevolen)

1. Start de gateway en @vermeld de bot in de groep
2. Voer openclaw logs --follow uit en zoek naar chat_id

Methode 2

Gebruik de Feishu API-debugger om groepschats op te vragen.

Gebruikers-ID’s (open_id)

Gebruikers-ID’s zien eruit als ou_xxx.

Methode 1 (aanbevolen)

1. Start de gateway en DM de bot
2. Voer openclaw logs --follow uit en zoek naar open_id

Methode 2

Controleer koppelingsverzoeken voor gebruikers-Open ID’s:

openclaw pairing list feishu

Veelgebruikte commando’s

Opmerking: Feishu ondersteunt nog geen native commandomenu’s, dus commando’s moeten als tekst worden verstuurd.

Gatewaybeheercommando’s

Probleemoplossing

Bot reageert niet in groepschats

1. Zorg ervoor dat de bot is toegevoegd aan de groep
2. Zorg ervoor dat je de bot @vermeldt (standaardgedrag)
3. Controleer of groupPolicy niet op "disabled" staat
4. Controleer logs: openclaw logs --follow

Bot ontvangt geen berichten

1. Zorg ervoor dat de app is gepubliceerd en goedgekeurd
2. Zorg ervoor dat het eventabonnement im.message.receive_v1 bevat
3. Zorg ervoor dat langverbinding is ingeschakeld
4. Zorg ervoor dat de app-machtigingen compleet zijn
5. Zorg ervoor dat de gateway draait: openclaw gateway status
6. Controleer logs: openclaw logs --follow

App Secret gelekt

1. Reset de App Secret in Feishu Open Platform
2. Werk de App Secret bij in je configuratie
3. Herstart de gateway

Berichtverzendingsfouten

1. Zorg ervoor dat de app de machtiging im:message:send_as_bot heeft
2. Zorg ervoor dat de app is gepubliceerd
3. Controleer logs voor gedetailleerde fouten

Geavanceerde configuratie

Meerdere accounts

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

defaultAccount bepaalt welk Feishu-account wordt gebruikt wanneer uitgaande API’s niet expliciet een accountId specificeren.

Berichtlimieten

• textChunkLimit: uitgaande tekstchunkgrootte (standaard: 2000 tekens)
• mediaMaxMb: media-upload-/downloadlimiet (standaard: 30 MB)

Streaming

Feishu ondersteunt streaming-antwoorden via interactieve kaarten. Wanneer ingeschakeld, werkt de bot een kaart bij terwijl tekst wordt gegenereerd.

{
  channels: {
    feishu: {
      streaming: true, // streaming-kaartuitvoer inschakelen (standaard true)
      blockStreaming: true, // blokstreaming inschakelen (standaard true)
    },
  },
}

Stel streaming: false in om te wachten op het volledige antwoord voordat het wordt verstuurd.

Multi-agent-routering

Gebruik bindings om Feishu-DM’s of -groepen naar verschillende agents te routeren.

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

Routeringsvelden:

• match.channel: "feishu"
• match.peer.kind: "direct" of "group"
• match.peer.id: gebruikers-Open ID (ou_xxx) of groeps-ID (oc_xxx)

Zie Groeps-/gebruikers-ID’s opzoeken voor opzoektips.

Configuratiereferentie

Volledige configuratie: Gateway-configuratie

Belangrijke opties:

dmPolicy-referentie

Ondersteunde berichttypen

Ontvangen

• Tekst
• Rich text (post)
• Afbeeldingen
• Bestanden
• Audio
• Video
• Stickers

Versturen

• Tekst
• Afbeeldingen
• Bestanden
• Audio
• Rich text (gedeeltelijke ondersteuning)