Feishu Bot mit OpenClaw verbinden

Integriertes Plugin

Feishu wird mit den aktuellen OpenClaw-Releases direkt mitgeliefert, du musst also kein separates Plugin installieren.

Falls du eine ältere Version oder eine eigene Installation nutzt, die Feishu nicht enthält, installiere es manuell:

openclaw plugins install @openclaw/feishu

---

Schnellstart

Es gibt zwei Möglichkeiten, den Feishu-Channel hinzuzufügen:

Methode 1: Onboarding (empfohlen)

Wenn du OpenClaw gerade erst installiert hast, starte das Onboarding:

openclaw onboard

Der Wizard führt dich durch diese Schritte:

1. Eine Feishu-App erstellen und Credentials sammeln
2. Die App-Credentials in OpenClaw konfigurieren
3. Das Gateway starten
4. Die Verbindung überprüfen

✅ Nach der Konfiguration kannst du den Gateway-Status prüfen:

• openclaw gateway status
• openclaw logs --follow

Methode 2: CLI-Setup

Falls du die Ersteinrichtung schon hinter dir hast, füge den Channel über die CLI hinzu:

openclaw channels add

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

✅ Nach der Konfiguration kannst du das Gateway verwalten:

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

---

Schritt 1: Eine Feishu-App erstellen

1. Feishu Open Platform öffnen

Besuche die Feishu Open Platform und melde dich an.

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

2. Eine App erstellen

1. Klicke auf Create enterprise app
2. Gib den App-Namen und eine Beschreibung ein
3. Wähle ein passendes App-Icon aus
4. Bestätige die Erstellung der App

3. Credentials kopieren

Kopiere unter Credentials & Basic Info folgende Daten:

• App ID (Format: cli_xxx)
• App Secret

❗ Wichtig: Behandle das App Secret vertraulich und gib es nicht weiter.

4. Berechtigungen konfigurieren

1. Klicke unter Permissions auf Batch import
2. Füge den folgenden JSON-Code 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-Funktion aktivieren

Unter App Capability > Bot:

1. Aktiviere die Bot-Funktion
2. Lege den Bot-Namen fest

6. Event-Subscription konfigurieren

⚠️ Wichtig: Bevor du die Event-Subscription einrichtest, stelle sicher, dass:

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

Unter Event Subscription:

1. Wähle Use long connection to receive events (WebSocket)
2. Füge das Event hinzu: im.message.receive_v1
3. Füge optional für Drive-Kommentar-Workflows hinzu: drive.notice.comment_add_v1
4. Speichere die vorgenommenen Einstellungen

⚠️ Wenn das Gateway nicht läuft, lässt sich die Long-Connection-Einstellung eventuell nicht speichern.

7. App veröffentlichen

1. Erstelle eine neue Version unter Version Management & Release
2. Reiche die App zur Prüfung ein
3. Schließe die Veröffentlichung ab
4. Warte auf die Freigabe durch den Admin (Enterprise-Apps werden oft automatisch genehmigt)

---

Schritt 2: OpenClaw konfigurieren

Konfiguration mit dem Wizard (empfohlen)

openclaw channels add

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

Konfiguration über die Config-Datei

Bearbeite die Datei ~/.openclaw/openclaw.json:

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

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

Verification Token und Encrypt Key (Webhook-Modus)

Wenn du den Webhook-Modus nutzt, trage channels.feishu.verificationToken und channels.feishu.encryptKey in deine Konfiguration ein. So findest du die Werte:

1. Öffne deine App in der Feishu Open Platform
2. Gehe zu Development → Events & Callbacks (开发配置 → 事件与回调)
3. Öffne den Tab Encryption (加密策略)
4. Kopiere den Verification Token und den Encrypt Key

Der Screenshot unten zeigt, wo du den Verification Token findest. Der Encrypt Key steht im selben Bereich.

Konfiguration über Umgebungsvariablen

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

Lark (global) Domain

Falls dein Tenant auf Lark (international) läuft, setze die Domain auf lark (oder einen vollständigen Domain-String). Du kannst dies unter channels.feishu.domain oder pro Account (channels.feishu.accounts.<id>.domain) festlegen.

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

Flags zur Quota-Optimierung

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

• typingIndicator (Standard: true): Bei false werden keine “schreibt…”-Statusmeldungen gesendet.
• resolveSenderNames (Standard: true): Bei false wird die Abfrage von Absenderprofilen übersprungen.

Setze diese auf der obersten Ebene oder pro Account:

{
  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

Such deinen Bot in Feishu und schick ihm eine Nachricht.

3. Pairing bestätigen

Standardmäßig antwortet der Bot mit einem Pairing-Code. Bestätige ihn so:

openclaw pairing approve feishu <CODE>

Nach der Bestätigung kannst du ganz normal chatten.

---

Übersicht

• Feishu Bot Channel: Dein Feishu-Bot wird direkt vom Gateway verwaltet.
• Deterministisches Routing: Antworten gehen immer zuverlässig an Feishu zurück.
• Session-Isolierung: DMs teilen sich eine Haupt-Session; Gruppen sind voneinander isoliert.
• WebSocket-Verbindung: Nutzt eine dauerhafte Verbindung über das Feishu SDK, du brauchst also keine öffentliche URL.

---

Zugriffskontrolle

Direktnachrichten

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

• Pairing bestätigen:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

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

Gruppen-Chats

1. Gruppen-Policy (channels.feishu.groupPolicy):

• "open" = erlaubt jeden in Gruppen.
• "allowlist" = erlaubt nur IDs in groupAllowFrom.
• "disabled" = deaktiviert Gruppennachrichten.

Standard: allowlist

2. Mention-Pflicht (channels.feishu.requireMention, überschreibbar via channels.feishu.groups.<chat_id>.requireMention):

• Explizit true = @mention ist zwingend erforderlich.
• Explizit false = antwortet auch ohne Mentions.
• Wenn nicht gesetzt und groupPolicy: "open" = Standard ist false.
• Wenn nicht gesetzt und groupPolicy nicht "open" ist = Standard ist true.

---

Beispiele für die Gruppenkonfiguration

Alle Gruppen erlauben, keine @mention nötig (Standard für offene Gruppen)

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

Alle Gruppen erlauben, aber @mention trotzdem erzwingen

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

Nur spezifische Gruppen erlauben

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Einschränken, welche Absender in einer Gruppe schreiben dürfen (Sender Allowlist)

Zusätzlich zur Freigabe der Gruppe selbst werden alle Nachrichten in dieser Gruppe durch die open_id des Absenders gefiltert: Nur User, die in groups.<chat_id>.allowFrom stehen, werden verarbeitet. Nachrichten von anderen Mitgliedern ignoriert das System komplett (das ist ein echtes Gating auf Absender-Ebene, nicht nur für Befehle wie /reset oder /new).

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

Gruppen- und User-IDs finden

Gruppen-IDs (chat_id)

Gruppen-IDs erkennst du am Format oc_xxx.

Methode 1 (empfohlen)

1. Starte das Gateway und markiere den Bot mit einem @mention in der Gruppe.
2. Führe openclaw logs --follow aus und suche nach der chat_id.

Methode 2

Nutze den Feishu API Debugger, um deine Gruppen-Chats aufzulisten.

User-IDs (open_id)

User-IDs erkennst du am Format ou_xxx.

Methode 1 (empfohlen)

1. Starte das Gateway und schicke dem Bot eine Direktnachricht (DM).
2. Führe openclaw logs --follow aus und suche nach der open_id.

Methode 2

Prüfe die Pairing-Anfragen für User Open IDs:

openclaw pairing list feishu

---

Häufige Befehle

Befehl	Beschreibung
/status	Bot-Status anzeigen
/reset	Session zurücksetzen
/model	Modell anzeigen/wechseln

Hinweis: Feishu unterstützt aktuell noch keine nativen Befehlsmenüs. Du musst die Befehle daher als normalen Text senden.

Gateway-Management-Befehle

Hier findest du die wichtigsten Befehle, um dein Gateway zu steuern und den Status zu prüfen.

Befehl	Beschreibung
openclaw gateway status	Gateway-Status anzeigen
openclaw gateway install	Gateway-Service installieren/starten
openclaw gateway stop	Gateway-Service stoppen
openclaw gateway restart	Gateway-Service neustarten
openclaw logs --follow	Gateway-Logs in Echtzeit verfolgen

---

Fehlerbehebung

Wenn etwas nicht wie geplant läuft, helfen dir diese Schritte weiter. Meistens liegt es an fehlenden Berechtigungen oder einer falschen Konfiguration.

Bot antwortet nicht in Gruppen-Chats

1. Stell sicher, dass der Bot zur Gruppe hinzugefügt wurde
2. Du musst den Bot mit @ erwähnen (Standardverhalten)
3. Prüfe, ob groupPolicy nicht auf "disabled" gesetzt ist
4. Check die Logs: openclaw logs --follow

Bot empfängt keine Nachrichten

1. Die App muss veröffentlicht und freigegeben sein
2. Das Event-Abonnement muss im.message.receive_v1 enthalten
3. Die Long Connection muss aktiviert sein
4. Die App-Berechtigungen müssen vollständig sein
5. Prüfe, ob das Gateway läuft: openclaw gateway status
6. Check die Logs: openclaw logs --follow

App Secret Leak

1. Setze das App Secret in der Feishu Open Platform zurück
2. Aktualisiere das App Secret in deiner Konfiguration
3. Starte das Gateway neu

Fehler beim Senden von Nachrichten

1. Die App braucht die Berechtigung im:message:send_as_bot
2. Die App muss veröffentlicht sein
3. Check die Logs für detaillierte Fehlermeldungen

AI Setup Assistant

Fortgeschrittene Konfiguration

Mehrere Accounts

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

defaultAccount steuert, welcher Feishu-Account verwendet wird, wenn ausgehende APIs keine accountId explizit angeben.

Nachrichtengrenzen

• textChunkLimit: Größe der ausgehenden Text-Chunks (Standard: 2000 Zeichen)
• mediaMaxMb: Limit für Media-Uploads und Downloads (Standard: 30MB)

Streaming

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

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

Setze streaming: false, wenn du auf die vollständige Antwort warten möchtest, bevor sie gesendet wird.

ACP-Sessions

Feishu unterstützt ACP für:

• DMs
• Group Topic Konversationen

Feishu ACP wird über Textbefehle gesteuert. Da es keine nativen Slash-Command-Menüs gibt, solltest du /acp ... Nachrichten direkt in der Konversation verwenden.

Persistente ACP-Bindings

Verwende Top-Level typed ACP-Bindings, um eine Feishu DM oder eine Topic-Konversation fest an eine persistente ACP-Session zu binden.

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

Thread-gebundener ACP-Spawn aus dem Chat

In einer Feishu DM oder Topic-Konversation kannst du eine ACP-Session direkt an Ort und Stelle erstellen und binden:

/acp spawn codex --thread here

Hinweise:

• --thread here funktioniert für DMs und Feishu Topics.
• Folgenachrichten in der gebundenen DM oder dem Topic werden direkt an diese ACP-Session geleitet.
• v1 unterstützt keine generischen Gruppen-Chats ohne Topics.
• Die Bindung bleibt für die Dauer der Session aktiv.

Multi-Agent Routing

Nutze bindings, um Feishu DMs oder Gruppen an verschiedene Agents zu leiten.

{
  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: User Open ID (ou_xxx) oder Group ID (oc_xxx)
• Weitere Details findest du unter Get group/user IDs.

---

Konfigurationsreferenz

Vollständige Konfiguration: Gateway configuration

Wichtige Optionen:

Einstellung	Beschreibung	Standard
channels.feishu.enabled	Kanal aktivieren/deaktivieren	true
channels.feishu.domain	API-Domain (feishu oder lark)	feishu
channels.feishu.connectionMode	Event-Transport-Modus	websocket
channels.feishu.defaultAccount	Standard-Account-ID für Routing	default
channels.feishu.verificationToken	Erforderlich für Webhook-Modus	-
channels.feishu.encryptKey	Erforderlich für Webhook-Modus	-
channels.feishu.webhookPath	Webhook-Pfad	/feishu/events
channels.feishu.webhookHost	Webhook-Host	127.0.0.1
channels.feishu.webhookPort	Webhook-Port	3000
channels.feishu.accounts.<id>.appId	App ID	-
channels.feishu.accounts.<id>.appSecret	App Secret	-
channels.feishu.accounts.<id>.domain	API-Domain-Override pro Account	feishu
channels.feishu.dmPolicy	DM-Policy	pairing
channels.feishu.allowFrom	DM-Allowlist (Liste von open_ids)	-
channels.feishu.groupPolicy	Gruppen-Policy	allowlist
channels.feishu.groupAllowFrom	Gruppen-Allowlist	-
channels.feishu.requireMention	Standardmäßig @Erwähnung erforderlich	bedingt
channels.feishu.groups.<chat_id>.requireMention	@Erwähnung-Override pro Gruppe	vererbt
channels.feishu.groups.<chat_id>.enabled	Gruppe aktivieren	true
channels.feishu.textChunkLimit	Größe der Nachrichten-Chunks	2000
channels.feishu.mediaMaxMb	Media-Größenlimit	30
channels.feishu.streaming	Streaming-Karten-Output aktivieren	true
channels.feishu.blockStreaming	Block-Streaming aktivieren	true

AI Setup Assistant

Nächste Schritte

• Get group/user IDs
• Gateway configuration

dmPolicy Referenz

Hier kannst du festlegen, wie dein Gateway mit eingehenden Direktnachrichten (DMs) umgeht. Ich empfehle dir die Einstellung "pairing", da sie die beste Balance zwischen Sicherheit und Flexibilität bietet.

Wert	Verhalten
"pairing"	Standard. Unbekannte Nutzer erhalten einen Pairing-Code; dieser muss genehmigt werden
"allowlist"	Nur Nutzer in allowFrom können chatten
"open"	Erlaubt allen Nutzern den Chat (erfordert "*" in allowFrom)
"disabled"	Deaktiviert DMs

---

Unterstützte Nachrichtentypen

Hier siehst du, welche Nachrichtentypen das System verarbeiten kann.

Receive

• ✅ Text
• ✅ Rich text (post)
• ✅ Images
• ✅ Files
• ✅ Audio
• ✅ Video/media
• ✅ Stickers

Send

• ✅ Text
• ✅ Images
• ✅ Files
• ✅ Audio
• ✅ Video/media
• ✅ Interactive cards
• ⚠️ Rich text (Formatierung im Post-Stil und Cards, keine beliebigen Feishu Authoring-Features)

Threads und Replies

• ✅ Inline replies
• ✅ Topic-thread replies, sofern Feishu reply_in_thread bereitstellt
• ✅ Media replies bleiben thread-aware, wenn auf eine Thread- oder Topic-Nachricht geantwortet wird

Drive Kommentare

Feishu kann den Agent triggern, wenn jemand einen Kommentar in einem Feishu Drive Dokument (Docs, Sheets usw.) erstellt. Der Agent erhält den Kommentartext, den Dokument-Kontext und den Thread, damit er direkt im Thread antworten oder Änderungen am Dokument vornehmen kann.

Voraussetzungen:

• Abonniere drive.notice.comment_add_v1 in den Event-Einstellungen deiner Feishu App (zusätzlich zum bestehenden im.message.receive_v1)
• Das Drive Tool ist standardmäßig aktiviert; du kannst es mit channels.feishu.tools.drive: false deaktivieren

Das feishu_drive Tool bietet diese Aktionen für Kommentare:

Aktion	Beschreibung
list_comments	Listet Kommentare in einem Dokument auf
list_comment_replies	Listet Antworten in einem Thread auf
add_comment	Fügt einen neuen Hauptkommentar hinzu
reply_comment	Antwortet auf einen bestehenden Thread

Wenn der Agent ein Drive-Kommentar-Event verarbeitet, erhält er:

• den Kommentartext samt Absender und die zugehörigen Metadaten des Dokuments (Titel, Typ, URL)
• den Kontext des Kommentar-Threads für Antworten direkt im Thread

Nachdem der Agent Änderungen am Dokument vorgenommen hat, sollte er feishu_drive.reply_comment nutzen, um die Person zu benachrichtigen, und anschließend NO_REPLY ausgeben, um doppelte Nachrichten zu vermeiden.

Runtime Action Surface

Feishu stellt aktuell diese Runtime Actions bereit:

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react und reactions (wenn Reactions in der Config aktiviert sind)
• feishu_drive Kommentar-Aktionen: list_comments, list_comment_replies, add_comment, reply_comment

Verwandte Themen

• Channels Overview — alle unterstützten Channels
• Pairing — DM-Authentifizierung und Pairing-Flow
• Groups — Verhalten in Gruppen-Chats und Mention-Gating
• Channel Routing — Session-Routing für Nachrichten
• Security — Zugriffsmodell und Hardening