Feishu

Feishu/Lark est une plateforme de collaboration tout-en-un où les équipes discutent, partagent des documents, gèrent des calendriers et travaillent ensemble.

État : prêt pour la production pour les DM de bot + les discussions de groupe. WebSocket est le mode par défaut ; le mode Webhook est facultatif.

Démarrage rapide

openclaw channels login --channel feishu

openclaw gateway restart

Contrôle d’accès

Messages directs

Configurez dmPolicy pour contrôler qui peut envoyer des DM au bot :

• "pairing" - les utilisateurs inconnus reçoivent un code d’appairage ; approuvez via la CLI
• "allowlist" - seuls les utilisateurs listés dans allowFrom peuvent discuter
• "open" - autorise les DM publics uniquement lorsque allowFrom inclut "*" ; avec des entrées restrictives, seuls les utilisateurs correspondants peuvent discuter

Approuver une demande d’appairage :

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Discussions de groupe

Politique de groupe (channels.feishu.groupPolicy) :

Par défaut : allowlist

Exigence de mention (channels.feishu.requireMention) :

• true - exiger une @mention (par défaut)
• false - répondre sans @mention
• Remplacement par groupe : channels.feishu.groups.<chat_id>.requireMention
• Les mentions de diffusion uniquement @all et @_all ne sont pas traitées comme des mentions du bot. Un message qui mentionne à la fois @all et le bot directement compte tout de même comme une mention du bot.

Exemples de configuration de groupe

Autoriser tous les groupes, sans @mention requise

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

Autoriser tous les groupes, tout en exigeant @mention

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

Autoriser uniquement des groupes précis

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

En mode allowlist, vous pouvez également admettre un groupe en ajoutant une entrée explicite groups.<chat_id>. Les entrées explicites ne remplacent pas groupPolicy: "disabled". Les valeurs par défaut génériques sous groups.* configurent les groupes correspondants, mais ne les admettent pas à elles seules.

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

Restreindre les expéditeurs au sein d’un groupe

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

Obtenir les ID de groupe/utilisateur

ID de groupe (chat_id, format : oc_xxx)

Ouvrez le groupe dans Feishu/Lark, cliquez sur l’icône de menu dans l’angle supérieur droit, puis accédez à Paramètres. L’ID de groupe (chat_id) est indiqué sur la page des paramètres.

ID utilisateur (open_id, format : ou_xxx)

Démarrez le Gateway, envoyez un DM au bot, puis consultez les journaux :

openclaw logs --follow

Recherchez open_id dans la sortie du journal. Vous pouvez aussi consulter les demandes d’appairage en attente :

openclaw pairing list feishu

Commandes courantes

Dépannage

Le bot ne répond pas dans les discussions de groupe

1. Assurez-vous que le bot est ajouté au groupe
2. Assurez-vous de @mentionner le bot (requis par défaut)
3. Vérifiez que groupPolicy n’est pas "disabled"
4. Consultez les journaux : openclaw logs --follow

Le bot ne reçoit pas les messages

1. Assurez-vous que le bot est publié et approuvé dans Feishu Open Platform / Lark Developer
2. Assurez-vous que l’abonnement aux événements inclut im.message.receive_v1
3. Assurez-vous que la connexion persistante (WebSocket) est sélectionnée
4. Assurez-vous que toutes les portées d’autorisation requises sont accordées
5. Assurez-vous que le Gateway est en cours d’exécution : openclaw gateway status
6. Consultez les journaux : openclaw logs --follow

La configuration par QR ne réagit pas dans l’application mobile Feishu

1. Relancez la configuration : openclaw channels login --channel feishu
2. Choisissez la configuration manuelle
3. Dans Feishu Open Platform, créez une application auto-construite et copiez son App ID et son App Secret
4. Collez ces identifiants dans l’assistant de configuration

App Secret divulgué

1. Réinitialisez l’App Secret dans Feishu Open Platform / Lark Developer
2. Mettez à jour la valeur dans votre configuration
3. Redémarrez le Gateway : openclaw gateway restart

Configuration avancée

Comptes multiples

{  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 contrôle quel compte est utilisé lorsque les API sortantes ne spécifient pas d’accountId. accounts.<id>.tts utilise la même forme que messages.tts et effectue une fusion profonde par-dessus la configuration TTS globale, afin que les configurations Feishu multi-bots puissent conserver les identifiants de fournisseur partagés globalement tout en remplaçant uniquement la voix, le modèle, la persona ou le mode automatique par compte.

Limites de messages

• textChunkLimit - taille des segments de texte sortants (par défaut : 2000 caractères)
• mediaMaxMb - limite d’envoi/téléchargement de médias (par défaut : 30 Mo)

Streaming

Feishu/Lark prend en charge les réponses en streaming via des cartes interactives. Lorsqu’il est activé, le bot met à jour la carte en temps réel pendant qu’il génère le texte.

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

Définissez streaming: false pour envoyer la réponse complète dans un seul message. blockStreaming est désactivé par défaut ; activez-le uniquement lorsque vous voulez que les blocs d’assistant terminés soient envoyés avant la réponse finale.

Optimisation du quota

Réduisez le nombre d’appels à l’API Feishu/Lark avec deux indicateurs facultatifs :

• typingIndicator (par défaut true) : définissez false pour ignorer les appels de réaction de saisie
• resolveSenderNames (par défaut true) : définissez false pour ignorer les recherches de profil d’expéditeur

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

Sessions ACP

Feishu/Lark prend en charge ACP pour les DM et les messages de fil de groupe. ACP Feishu/Lark est piloté par commandes texte - il n’y a pas de menus natifs de commandes slash ; utilisez donc les messages /acp ... directement dans la conversation.

Liaison ACP persistante

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

Lancer ACP depuis la discussion

Dans un DM ou un fil Feishu/Lark :

/acp spawn codex --thread here

--thread here fonctionne pour les DM et les messages de fil Feishu/Lark. Les messages suivants dans la conversation liée sont acheminés directement vers cette session ACP.

Routage multi-agent

Utilisez bindings pour acheminer les DM ou groupes Feishu/Lark vers différents agents.

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

Champs de routage :

• match.channel : "feishu"
• match.peer.kind : "direct" (DM) ou "group" (discussion de groupe)
• match.peer.id : Open ID utilisateur (ou_xxx) ou ID de groupe (oc_xxx)

Voir Obtenir les ID de groupe/utilisateur pour des conseils de recherche.

Isolation d’agent par utilisateur (création dynamique d’agent)

Activez dynamicAgentCreation pour créer automatiquement des instances d’agent isolées pour chaque utilisateur de DM. Chaque utilisateur obtient ses propres éléments :

• Répertoire d’espace de travail indépendant
• USER.md / SOUL.md / MEMORY.md séparés
• Historique de conversation privé
• Skills et état isolés

C’est essentiel pour les bots publics lorsque vous voulez offrir à chaque utilisateur sa propre expérience privée d’assistant IA.

Configuration rapide

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

Fonctionnement

Lorsqu’un nouvel utilisateur envoie son premier DM :

1. Le canal génère un agentId unique : feishu-{user_open_id} pour le compte par défaut, ou un condensat d’identité borné et préfixé par le compte pour un compte nommé
2. Crée un nouvel espace de travail au chemin workspaceTemplate
3. Enregistre l’agent et crée une liaison pour cet utilisateur
4. L’assistant d’espace de travail garantit les fichiers d’amorçage (AGENTS.md, SOUL.md, USER.md, etc.) lors du premier accès
5. Achemine tous les futurs messages de cet utilisateur vers son agent dédié

Options de configuration

Variables de modèle :

• {agentId} - l’ID d’agent généré (par exemple, feishu-ou_xxxxxx ou feishu-support-<identity_digest>)
• {userId} - le Feishu open_id de l’expéditeur (par exemple, ou_xxxxxx)

Portée de session

session.dmScope contrôle la façon dont les messages directs sont associés aux sessions d’agent. Il s’agit d’un paramètre global qui affecte tous les canaux.

Compromis : l’utilisation de "main" active le chargement automatique des fichiers d’amorçage (USER.md, SOUL.md, MEMORY.md), mais signifie que tous les DM sur tous les canaux partagent le même schéma de clé de session. Pour les bots publics multi-utilisateurs où l’isolation compte plus que le chargement automatique de l’amorçage, envisagez "per-channel-peer" et gérez les fichiers d’amorçage manuellement.

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

Déploiement multi-utilisateurs typique

{  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}

Vérification

Consultez les journaux du Gateway pour confirmer que la création dynamique fonctionne :

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

Lister tous les espaces de travail créés :

ls -la ~/.openclaw/workspace-*

Notes

• Isolation de l’espace de travail : chaque utilisateur obtient son propre répertoire d’espace de travail et sa propre instance d’agent. Les utilisateurs ne peuvent pas voir l’historique des conversations ni les fichiers des autres dans le flux de messagerie normal.
• Limite de sécurité : il s’agit d’un mécanisme d’isolation du contexte de messagerie, pas d’une limite de sécurité contre un colocataire hostile. Le processus d’agent et l’environnement hôte sont partagés.
• bindings doit être vide : les agents dynamiques enregistrent automatiquement leurs propres liaisons
• Chemin de mise à niveau : les liaisons manuelles existantes continuent de fonctionner avec les agents dynamiques
• session.dmScope est global : cela affecte tous les canaux, pas seulement Feishu

Référence de configuration

Configuration complète : Configuration du Gateway

Types de messages pris en charge

Recevoir

• ✅ Texte
• ✅ Texte enrichi (publication)
• ✅ Images
• ✅ Fichiers
• ✅ Audio
• ✅ Vidéo/média
• ✅ Autocollants

Les messages audio Feishu/Lark entrants sont normalisés comme espaces réservés de média plutôt que comme JSON file_key brut. Lorsque tools.media.audio est configuré, OpenClaw télécharge la ressource de note vocale et exécute la transcription audio partagée avant le tour de l’agent, afin que l’agent reçoive la transcription orale. Si Feishu inclut directement le texte de transcription dans la charge utile audio, ce texte est utilisé sans autre appel ASR. Sans fournisseur de transcription audio, l’agent reçoit tout de même un espace réservé <media:audio> ainsi que la pièce jointe enregistrée, et non la charge utile brute de la ressource Feishu.

Envoyer

• ✅ Texte
• ✅ Images
• ✅ Fichiers
• ✅ Audio
• ✅ Vidéo/médias
• ✅ Cartes interactives (y compris les mises à jour en streaming)
• ⚠️ Texte enrichi (mise en forme de type publication ; ne prend pas en charge toutes les fonctionnalités de création Feishu/Lark)

Les bulles audio natives Feishu/Lark utilisent le type de message Feishu audio et nécessitent un média téléversé en Ogg/Opus (file_type: "opus"). Les médias .opus et .ogg existants sont envoyés directement comme audio natif. Les formats MP3/WAV/M4A et les autres formats probablement audio sont transcodés en Ogg/Opus 48 kHz avec ffmpeg uniquement lorsque la réponse demande une livraison vocale (audioAsVoice / outil de message asVoice, y compris les réponses de note vocale TTS). Les pièces jointes MP3 ordinaires restent des fichiers classiques. Si ffmpeg est manquant ou si la conversion échoue, OpenClaw se rabat sur une pièce jointe de fichier et journalise la raison.

Fils et réponses

• ✅ Réponses en ligne
• ✅ Réponses dans les fils
• ✅ Les réponses multimédias restent compatibles avec les fils lorsqu’elles répondent à un message de fil

Pour groupSessionScope: "group_topic" et "group_topic_sender", les groupes de sujets Feishu/Lark natifs utilisent le thread_id de l’événement (omt_*) comme clé canonique de session de sujet. Si un événement natif de démarrage de sujet omet thread_id, OpenClaw le récupère depuis Feishu avant de router le tour. Les réponses de groupe normales qu’ OpenClaw transforme en fils continuent d’utiliser l’ID du message racine de réponse (om_*) afin que le premier tour et le tour de suivi restent dans la même session.

Connexe

• Vue d’ensemble des canaux - tous les canaux pris en charge
• Association - authentification par DM et flux d’association
• Groupes - comportement des discussions de groupe et filtrage par mention
• Routage des canaux - routage de session pour les messages
• Sécurité - modèle d’accès et renforcement