Feishu

Feishu/Lark ist eine All-in-one-Kollaborationsplattform, auf der Teams chatten, Dokumente teilen, Kalender verwalten und gemeinsam Arbeit erledigen.

Status: produktionsreif für Bot-Direktnachrichten und Gruppenchats. WebSocket ist der Standardmodus; Webhook-Modus ist optional.

Schnellstart

openclaw channels login --channel feishu

openclaw gateway restart

Zugriffskontrolle

Direktnachrichten

Konfigurieren Sie dmPolicy, um zu steuern, wer dem Bot Direktnachrichten senden kann:

• "pairing" - unbekannte Benutzer erhalten einen Kopplungscode; Genehmigung per CLI
• "allowlist" - nur in allowFrom aufgeführte Benutzer können chatten
• "open" - öffentliche Direktnachrichten nur zulassen, wenn allowFrom "*" enthält; bei einschränkenden Einträgen können nur passende Benutzer chatten

Eine Kopplungsanfrage genehmigen:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Gruppenchats

Gruppenrichtlinie (channels.feishu.groupPolicy):

Standard: allowlist

Erwähnungsanforderung (channels.feishu.requireMention):

• true - @-Erwähnung erforderlich (Standard)
• false - ohne @-Erwähnung antworten
• Überschreibung pro Gruppe: channels.feishu.groups.<chat_id>.requireMention
• Reine Broadcast-Erwähnungen @all und @_all werden nicht als Bot-Erwähnungen behandelt. Eine Nachricht, die sowohl @all als auch den Bot direkt erwähnt, zählt dennoch als Bot-Erwähnung.

Beispiele für Gruppenkonfiguration

Alle Gruppen zulassen, keine @-Erwähnung erforderlich

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

Alle Gruppen zulassen, @-Erwähnung weiterhin erforderlich

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

Nur bestimmte Gruppen zulassen

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Group IDs look like: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

Im Modus allowlist können Sie eine Gruppe auch zulassen, indem Sie einen expliziten groups.<chat_id>-Eintrag hinzufügen. Explizite Einträge überschreiben groupPolicy: "disabled" nicht. Platzhalter-Standards unter groups.* konfigurieren passende Gruppen, lassen Gruppen aber nicht eigenständig zu.

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

Absender innerhalb einer Gruppe einschränken

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // User open_ids look like: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

Gruppen-/Benutzer-IDs abrufen

Gruppen-IDs (chat_id, Format: oc_xxx)

Öffnen Sie die Gruppe in Feishu/Lark, klicken Sie oben rechts auf das Menüsymbol und gehen Sie zu Einstellungen. Die Gruppen-ID (chat_id) ist auf der Einstellungsseite aufgeführt.

Benutzer-IDs (open_id, Format: ou_xxx)

Starten Sie den Gateway, senden Sie dem Bot eine Direktnachricht und prüfen Sie anschließend die Logs:

openclaw logs --follow

Suchen Sie in der Log-Ausgabe nach open_id. Sie können auch ausstehende Kopplungsanfragen prüfen:

openclaw pairing list feishu

Häufige Befehle

Fehlerbehebung

Bot antwortet nicht in Gruppenchats

1. Stellen Sie sicher, dass der Bot zur Gruppe hinzugefügt wurde
2. Stellen Sie sicher, dass Sie den Bot @-erwähnen (standardmäßig erforderlich)
3. Prüfen Sie, dass groupPolicy nicht "disabled" ist
4. Logs prüfen: openclaw logs --follow

Bot empfängt keine Nachrichten

1. Stellen Sie sicher, dass der Bot in Feishu Open Platform / Lark Developer veröffentlicht und genehmigt ist
2. Stellen Sie sicher, dass das Ereignisabonnement im.message.receive_v1 enthält
3. Stellen Sie sicher, dass persistente Verbindung (WebSocket) ausgewählt ist
4. Stellen Sie sicher, dass alle erforderlichen Berechtigungsbereiche gewährt sind
5. Stellen Sie sicher, dass der Gateway ausgeführt wird: openclaw gateway status
6. Logs prüfen: openclaw logs --follow

QR-Einrichtung reagiert in der Feishu-Mobile-App nicht

1. Einrichtung erneut ausführen: openclaw channels login --channel feishu
2. Manuelle Einrichtung wählen
3. Erstellen Sie in Feishu Open Platform eine selbst erstellte App und kopieren Sie deren App ID und App Secret
4. Fügen Sie diese Anmeldedaten in den Einrichtungsassistenten ein

App Secret offengelegt

1. Setzen Sie das App Secret in Feishu Open Platform / Lark Developer zurück
2. Aktualisieren Sie den Wert in Ihrer Konfiguration
3. Starten Sie den Gateway neu: openclaw gateway restart

Erweiterte Konfiguration

Mehrere Konten

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

defaultAccount steuert, welches Konto verwendet wird, wenn ausgehende APIs kein accountId angeben. accounts.<id>.tts verwendet dieselbe Struktur wie messages.tts und wird per Deep-Merge über die globale TTS-Konfiguration gelegt. Dadurch können Feishu-Setups mit mehreren Bots gemeinsame Provider- Anmeldedaten global halten und nur Stimme, Modell, Persona oder Automodus pro Konto überschreiben.

Nachrichtenlimits

• textChunkLimit - Größe ausgehender Textabschnitte (Standard: 2000 Zeichen)
• mediaMaxMb - Upload-/Download-Limit für Medien (Standard: 30 MB)

Streaming

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

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

Setzen Sie streaming: false, um die vollständige Antwort in einer Nachricht zu senden. blockStreaming ist standardmäßig deaktiviert; aktivieren Sie es nur, wenn Sie abgeschlossene Assistentenblöcke vor der endgültigen Antwort ausgeben möchten.

Kontingentoptimierung

Reduzieren Sie die Anzahl der Feishu/Lark-API-Aufrufe mit zwei optionalen Flags:

• typingIndicator (Standard true): auf false setzen, um Aufrufe für Tippreaktionen zu überspringen
• resolveSenderNames (Standard true): auf false setzen, um Abfragen von Absenderprofilen zu überspringen

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

ACP-Sitzungen

Feishu/Lark unterstützt ACP für Direktnachrichten und Gruppen-Thread-Nachrichten. Feishu/Lark-ACP ist textbefehlsbasiert - es gibt keine nativen Slash-Befehlsmenüs. Verwenden Sie daher /acp ...-Nachrichten direkt in der Unterhaltung.

Persistente ACP-Bindung

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

ACP aus dem Chat starten

In einer Feishu/Lark-Direktnachricht oder einem Thread:

/acp spawn codex --thread here

--thread here funktioniert für Direktnachrichten und Feishu/Lark-Thread-Nachrichten. Folgenachrichten in der gebundenen Unterhaltung werden direkt an diese ACP-Sitzung geleitet.

Routing mit mehreren Agenten

Verwenden Sie bindings, um Feishu/Lark-Direktnachrichten oder -Gruppen an verschiedene Agenten zu leiten.

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

Routing-Felder:

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

Siehe Gruppen-/Benutzer-IDs abrufen für Hinweise zum Nachschlagen.

Agent-Isolierung pro Benutzer (dynamische Agentenerstellung)

Aktivieren Sie dynamicAgentCreation, um für jeden Direktnachrichtenbenutzer automatisch isolierte Agenteninstanzen zu erstellen. Jeder Benutzer erhält eigene:

• Unabhängiges Arbeitsverzeichnis
• Separate USER.md / SOUL.md / MEMORY.md
• Privater Unterhaltungsverlauf
• Isolierte Skills und isolierter Status

Dies ist wesentlich für öffentliche Bots, wenn jeder Benutzer eine eigene private KI-Assistentenerfahrung haben soll.

Schnelleinrichtung

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Critical: makes each user's DM their "main session"    // Automatically loads USER.md / SOUL.md / MEMORY.md    // For stronger isolation, use "per-channel-peer" instead    dmScope: "main",  },}

Funktionsweise

Wenn ein neuer Benutzer seine erste Direktnachricht sendet:

1. Der Kanal generiert eine eindeutige agentId: feishu-{user_open_id} für das Standardkonto oder einen begrenzten, kontopräfixierten Identitäts-Digest für ein benanntes Konto
2. Erstellt einen neuen Arbeitsbereich am Pfad workspaceTemplate
3. Registriert den Agenten und erstellt eine Bindung für diesen Benutzer
4. Der Arbeitsbereichshelfer stellt Bootstrap-Dateien (AGENTS.md, SOUL.md, USER.md usw.) beim ersten Zugriff sicher
5. Leitet alle zukünftigen Nachrichten dieses Benutzers an seinen dedizierten Agenten weiter

Konfigurationsoptionen

Template-Variablen:

• {agentId} - die generierte Agent-ID (z. B. feishu-ou_xxxxxx oder feishu-support-<identity_digest>)
• {userId} - die Feishu-open_id des Absenders (z. B. ou_xxxxxx)

Sitzungsbereich

session.dmScope steuert, wie Direktnachrichten Agent-Sitzungen zugeordnet werden. Dies ist eine globale Einstellung, die alle Kanäle betrifft.

Abwägung: Die Verwendung von "main" aktiviert das automatische Laden von Bootstrap-Dateien (USER.md, SOUL.md, MEMORY.md), bedeutet aber, dass alle DMs über alle Kanäle hinweg dasselbe Muster für Sitzungsschlüssel teilen. Für öffentliche Mehrbenutzer-Bots, bei denen Isolation wichtiger ist als automatisches Bootstrap-Laden, sollten Sie "per-channel-peer" in Betracht ziehen und Bootstrap-Dateien manuell verwalten.

{  session: {    // For single-user personal bots: enables auto bootstrap loading    dmScope: "main",     // For public multi-user bots: stronger isolation    // dmScope: "per-channel-peer",  },}

Typische Mehrbenutzer-Bereitstellung

{  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: {    // Choose dmScope based on your isolation needs:    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation    dmScope: "main",  },  bindings: [], // Empty - dynamic agents auto-bind}

Verifizierung

Prüfen Sie die Gateway-Logs, um zu bestätigen, dass die dynamische Erstellung funktioniert:

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxxworkspace: /Users/you/.openclaw/workspace-feishu-ou_xxxxxxfeishu: dynamic agent created, new route: agent:feishu-ou_xxxxxx:main

Alle erstellten Workspaces auflisten:

ls -la ~/.openclaw/workspace-*

Hinweise

• Workspace-Isolation: Jeder Benutzer erhält sein eigenes Workspace-Verzeichnis und eine eigene Agent-Instanz. Benutzer können im normalen Nachrichtenfluss den Gesprächsverlauf oder die Dateien anderer Benutzer nicht sehen.
• Sicherheitsgrenze: Dies ist ein Isolationsmechanismus für den Nachrichtenkontext, keine Sicherheitsgrenze gegen feindliche Co-Tenants. Der Agent-Prozess und die Host-Umgebung werden gemeinsam genutzt.
• bindings sollte leer sein: Dynamische Agents registrieren automatisch ihre eigenen Bindings
• Upgrade-Pfad: Bestehende manuelle Bindings funktionieren weiterhin parallel zu dynamischen Agents
• session.dmScope ist global: Dies betrifft alle Kanäle, nicht nur Feishu

Konfigurationsreferenz

Vollständige Konfiguration: Gateway-Konfiguration

Unterstützte Nachrichtentypen

Empfangen

• ✅ Text
• ✅ Rich Text (Post)
• ✅ Bilder
• ✅ Dateien
• ✅ Audio
• ✅ Video/Medien
• ✅ Sticker

Eingehende Feishu/Lark-Audionachrichten werden als Medienplatzhalter statt als rohes file_key-JSON normalisiert. Wenn tools.media.audio konfiguriert ist, lädt OpenClaw die Sprachnotiz-Ressource herunter und führt vor dem Agent-Turn die gemeinsame Audiotranskription aus, sodass der Agent das gesprochene Transkript erhält. Wenn Feishu Transkripttext direkt in der Audio-Payload enthält, wird dieser Text ohne weiteren ASR-Aufruf verwendet. Ohne Audio-Transcription-Provider erhält der Agent weiterhin einen <media:audio>-Platzhalter plus den gespeicherten Anhang, nicht die rohe Feishu-Ressourcen-Payload.

Senden

• ✅ Text
• ✅ Bilder
• ✅ Dateien
• ✅ Audio
• ✅ Video/Medien
• ✅ Interaktive Karten (einschließlich Streaming-Aktualisierungen)
• ⚠️ Rich Text (postartige Formatierung; unterstützt nicht die vollständigen Feishu/Lark-Autorenfunktionen)

Native Feishu/Lark-Audio-Bubbles verwenden den Feishu-Nachrichtentyp audio und erfordern Ogg/Opus-Upload-Medien (file_type: "opus"). Vorhandene .opus- und .ogg-Medien werden direkt als natives Audio gesendet. MP3/WAV/M4A und andere wahrscheinliche Audioformate werden nur dann mit ffmpeg in 48 kHz Ogg/Opus transkodiert, wenn die Antwort eine Zustellung als Sprachnachricht anfordert (audioAsVoice / Nachrichtentool asVoice, einschließlich TTS-Sprachnotiz- Antworten). Gewöhnliche MP3-Anhänge bleiben reguläre Dateien. Wenn ffmpeg fehlt oder die Konvertierung fehlschlägt, fällt OpenClaw auf einen Dateianhang zurück und protokolliert den Grund.

Threads und Antworten

• ✅ Inline-Antworten
• ✅ Thread-Antworten
• ✅ Medienantworten bleiben threadbezogen, wenn auf eine Thread-Nachricht geantwortet wird

Für groupSessionScope: "group_topic" und "group_topic_sender" verwenden native Feishu/Lark-Themengruppen die Event-thread_id (omt_*) als kanonischen Sitzungsschlüssel für das Thema. Wenn ein natives Thema-Starter-Event thread_id auslässt, hydratisiert OpenClaw sie vor dem Routing des Turns aus Feishu. Normale Gruppenantworten, die OpenClaw in Threads umwandelt, verwenden weiterhin die Nachrichten-ID der Antwortwurzel (om_*), sodass der erste Turn und der Folge-Turn in derselben Sitzung bleiben.

Verwandt

• Kanalübersicht - alle unterstützten Kanäle
• Koppeln - DM-Authentifizierung und Kopplungsablauf
• Gruppen - Gruppenchat-Verhalten und Mention-Gating
• Kanal-Routing - Sitzungs-Routing für Nachrichten
• Sicherheit - Zugriffsmodell und Härtung