Feishu-Bot

Feishu (Lark) ist eine Team-Chat-Plattform für Messaging und Zusammenarbeit in Unternehmen. Dieses Plugin verbindet OpenClaw mit einem Feishu/Lark-Bot über die WebSocket-Event-Subscription der Plattform, sodass Nachrichten empfangen werden können, ohne eine öffentliche Webhook-URL zu exponieren.

Mitgeliefertes Plugin

Feishu wird mit aktuellen OpenClaw-Releases mitgeliefert, sodass keine separate Plugin-Installation erforderlich ist.

Wenn du einen älteren Build oder eine benutzerdefinierte Installation ohne gebündeltes Feishu verwendest, installiere es manuell:

openclaw plugins install @openclaw/feishu

Schnellstart

Es gibt zwei Wege, den Feishu-Kanal hinzuzufügen:

Methode 1: Onboarding-Assistent (empfohlen)

Wenn du OpenClaw gerade installiert hast, starte den Assistenten:

openclaw onboard

Der Assistent führt dich durch:

1. Erstellen einer Feishu-App und Sammeln der Zugangsdaten
2. Konfiguration der App-Zugangsdaten in OpenClaw
3. Starten des Gateways

Nach der Konfiguration den Gateway-Status prüfen:

• openclaw gateway status
• openclaw logs --follow

Methode 2: CLI-Einrichtung

Wenn du die Erstinstallation bereits abgeschlossen hast, füge den Kanal über CLI hinzu:

openclaw channels add

Wähle Feishu und gib dann App ID und App Secret ein.

Nach der Konfiguration das Gateway verwalten:

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

Schritt 1: Feishu-App erstellen

1. Feishu Open Platform öffnen

Besuche Feishu Open Platform und melde dich an.

Lark (global) Tenants sollten https://open.larksuite.com/app verwenden und domain: "lark" in der Feishu-Konfiguration setzen.

2. App erstellen

1. Klicke auf Create enterprise app
2. Fülle App-Name + Beschreibung aus
3. Wähle ein App-Symbol

3. Zugangsdaten kopieren

Unter Credentials & Basic Info kopiere:

• App ID (Format: cli_xxx)
• App Secret

Warnung: Halte das App Secret privat.

4. Berechtigungen konfigurieren

Unter Permissions klicke auf Batch import und füge ein:

{
  "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. Bot-Fähigkeit aktivieren

In App Capability > Bot:

1. Bot-Fähigkeit aktivieren
2. Bot-Namen setzen

6. Event-Subscription konfigurieren

Warnung: Stelle vor dem Setzen der Event-Subscription sicher, dass:

1. Du bereits openclaw channels add für Feishu ausgeführt hast
2. Das Gateway läuft (openclaw gateway status)

In Event Subscription:

1. Wähle Use long connection to receive events (WebSocket)
2. Füge das Event hinzu: im.message.receive_v1

Wenn das Gateway nicht läuft, kann das Speichern der Long-Connection-Einrichtung fehlschlagen.

7. App veröffentlichen

1. Erstelle eine Version in Version Management & Release
2. Zur Prüfung einreichen und veröffentlichen
3. Auf Admin-Genehmigung warten (Enterprise-Apps werden normalerweise automatisch genehmigt)

Schritt 2: OpenClaw konfigurieren

Mit dem Assistenten konfigurieren (empfohlen)

openclaw channels add

Wähle Feishu und füge deine App ID + App Secret ein.

Über Konfigurationsdatei

Bearbeite ~/.openclaw/openclaw.json:

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

Wenn du connectionMode: "webhook" verwendest, setze sowohl verificationToken als auch encryptKey. Der Feishu-Webhook-Server bindet standardmäßig an 127.0.0.1; setze webhookHost nur, wenn du absichtlich eine andere Bind-Adresse benötigst.

Verification Token und Encrypt Key (Webhook-Modus)

Bei Verwendung des Webhook-Modus setze sowohl channels.feishu.verificationToken als auch channels.feishu.encryptKey in deiner Konfiguration. Um die Werte zu erhalten:

1. Öffne auf der Feishu Open Platform deine App
2. Gehe zu Development -> Events & Callbacks (Entwicklungskonfiguration -> Events & Callbacks)
3. Öffne den Tab Encryption (Verschlüsselungsstrategie)
4. Kopiere Verification Token und Encrypt Key

Der Screenshot unten zeigt, wo der Verification Token zu finden ist. Der Encrypt Key steht im selben Encryption-Abschnitt.

Über Umgebungsvariablen

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

Lark (global) Domain

Wenn dein Tenant auf Lark (international) ist, setze die Domain auf lark (oder einen vollständigen Domain-String). Du kannst sie unter channels.feishu.domain oder pro Konto (channels.feishu.accounts.<id>.domain) setzen.

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

Quota-Optimierungs-Flags

Du kannst die Feishu-API-Nutzung mit zwei optionalen Flags reduzieren:

• typingIndicator (Standard true): Bei false werden Tipp-Reaktionsaufrufe übersprungen.
• resolveSenderNames (Standard true): Bei false werden Absenderprofil-Abfrageaufrufe übersprungen.

Setze sie auf Top-Level oder pro Konto:

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

Schritt 3: Starten + Testen

1. Gateway starten

openclaw gateway

2. Testnachricht senden

Finde in Feishu deinen Bot und sende eine Nachricht.

3. Pairing genehmigen

Standardmäßig antwortet der Bot mit einem Pairing-Code. Genehmige ihn:

openclaw pairing approve feishu <CODE>

Nach der Genehmigung kannst du normal chatten.

Überblick

• Feishu-Bot-Kanal: Feishu-Bot, verwaltet vom Gateway
• Deterministisches Routing: Antworten gehen immer zurück zu Feishu
• Session-Isolation: DMs teilen eine Haupt-Session; Gruppen sind isoliert
• WebSocket-Verbindung: Long Connection via Feishu SDK, keine öffentliche URL nötig

Zugriffssteuerung

Direktnachrichten

• Standard: dmPolicy: "pairing" (unbekannte Benutzer erhalten einen Pairing-Code)

• Pairing genehmigen:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Allowlist-Modus: Setze channels.feishu.allowFrom mit erlaubten Open IDs

Gruppenchats

1. Gruppenrichtlinie (channels.feishu.groupPolicy):

• "open" = jeden in Gruppen erlauben (Standard)
• "allowlist" = nur groupAllowFrom erlauben
• "disabled" = Gruppennachrichten deaktivieren

2. Mention-Anforderung (channels.feishu.groups.<chat_id>.requireMention):

• true = @Mention erforderlich (Standard)
• false = ohne Mention antworten

Gruppen-Konfigurationsbeispiele

Alle Gruppen erlauben, @Mention erforderlich (Standard)

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

Alle Gruppen erlauben, kein @Mention erforderlich

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

Nur bestimmte Gruppen erlauben

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu Gruppen-IDs (chat_id) sehen so aus: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Absender in einer Gruppe einschränken (Absender-Allowlist)

Zusätzlich zum Erlauben der Gruppe selbst werden alle Nachrichten in dieser Gruppe nach der Absender-open_id gefiltert: Nur Benutzer in groups.<chat_id>.allowFrom werden verarbeitet; Nachrichten anderer Mitglieder werden ignoriert (dies ist vollständiges Absender-Gating, nicht nur für Steuerbefehle wie /reset oder /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu Benutzer-IDs (open_id) sehen so aus: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Gruppen-/Benutzer-IDs ermitteln

Gruppen-IDs (chat_id)

Gruppen-IDs sehen so aus: oc_xxx.

Methode 1 (empfohlen)

1. Starte das Gateway und @erwähne den Bot in der Gruppe
2. Führe openclaw logs --follow aus und suche nach chat_id

Methode 2

Verwende den Feishu-API-Debugger, um Gruppenchats aufzulisten.

Benutzer-IDs (open_id)

Benutzer-IDs sehen so aus: ou_xxx.

Methode 1 (empfohlen)

1. Starte das Gateway und sende dem Bot eine DM
2. Führe openclaw logs --follow aus und suche nach open_id

Methode 2

Prüfe Pairing-Anfragen auf Benutzer-Open-IDs:

openclaw pairing list feishu

Häufige Befehle

Hinweis: Feishu unterstützt noch keine nativen Befehlsmenüs, Befehle müssen als Text gesendet werden.

Gateway-Verwaltungsbefehle

Fehlerbehebung

Bot antwortet nicht in Gruppenchats

1. Stelle sicher, dass der Bot der Gruppe hinzugefügt ist
2. Stelle sicher, dass du den Bot @erwähnst (Standardverhalten)
3. Prüfe, ob groupPolicy nicht auf "disabled" gesetzt ist
4. Prüfe die Logs: openclaw logs --follow

Bot empfängt keine Nachrichten

1. Stelle sicher, dass die App veröffentlicht und genehmigt ist
2. Stelle sicher, dass die Event-Subscription im.message.receive_v1 enthält
3. Stelle sicher, dass Long Connection aktiviert ist
4. Stelle sicher, dass die App-Berechtigungen vollständig sind
5. Stelle sicher, dass das Gateway läuft: openclaw gateway status
6. Prüfe die Logs: openclaw logs --follow

App-Secret-Leak

1. App Secret auf der Feishu Open Platform zurücksetzen
2. App Secret in deiner Konfiguration aktualisieren
3. Gateway neustarten

Fehler beim Nachrichtenversand

1. Stelle sicher, dass die App die Berechtigung im:message:send_as_bot hat
2. Stelle sicher, dass die App veröffentlicht ist
3. Prüfe die Logs auf detaillierte Fehler

Erweiterte Konfiguration

Mehrere Konten

{
  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 steuert, welches Feishu-Konto verwendet wird, wenn ausgehende APIs keine accountId explizit angeben.

Nachrichtenlimits

• textChunkLimit: Ausgehende Textblockgröße (Standard: 2000 Zeichen)
• mediaMaxMb: Medien-Upload/Download-Limit (Standard: 30MB)

Streaming

Feishu unterstützt Streaming-Antworten über interaktive Karten. Wenn aktiviert, aktualisiert der Bot eine Karte, während er Text generiert.

{
  channels: {
    feishu: {
      streaming: true, // Streaming-Kartenausgabe aktivieren (Standard true)
      blockStreaming: true, // Block-Level-Streaming aktivieren (Standard true)
    },
  },
}

Setze streaming: false, um auf die vollständige Antwort vor dem Senden zu warten.

Multi-Agent-Routing

Verwende bindings, um Feishu-DMs oder -Gruppen verschiedenen Agenten zuzuordnen.

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

Routing-Felder:

• match.channel: "feishu"
• match.peer.kind: "direct" oder "group"
• match.peer.id: Benutzer-Open-ID (ou_xxx) oder Gruppen-ID (oc_xxx)

Siehe Gruppen-/Benutzer-IDs ermitteln für Suchtipps.

Konfigurationsreferenz

Vollständige Konfiguration: Gateway configuration

Wichtige Optionen:

dmPolicy-Referenz

Unterstützte Nachrichtentypen

Empfangen

• Text
• Rich Text (Post)
• Bilder
• Dateien
• Audio
• Video
• Sticker

Senden

• Text
• Bilder
• Dateien
• Audio
• Rich Text (teilweise Unterstützung)