Integration OpenClaw avec Feishu/Lark : Guide Complet de Configuration

Feishu et Lark : deux plateformes, une seule integration

Feishu et Lark sont les plateformes de messagerie d'entreprise de ByteDance. Feishu est destine au marche chinois, tandis que Lark couvre le reste du monde. Les deux partagent la meme architecture technique, ce qui signifie que le processus d'integration est quasiment identique, quelle que soit la version utilisee par votre organisation.

OpenClaw propose deux methodes pour se connecter a Feishu/Lark :

Ce guide se concentre sur le plugin integre, qui couvre environ 90 % des cas d'utilisation. Si vous avez besoin d'une integration complete avec l'espace de travail (lecture de documents, gestion de calendriers, creation de taches), consultez la section Plugin officiel Feishu en fin de guide.

Prerequis pour configurer OpenClaw avec Feishu

Avant de commencer, assurez-vous d'avoir :

• OpenClaw installe et operationnel (version ≥ 2026.2). Si ce n'est pas encore fait, suivez le guide d'installation.
• Un compte developpeur Feishu sur open.feishu.cn (ou open.larksuite.com pour Lark).
• La passerelle accessible — verifiez avec :

openclaw gateway status

Aucune IP publique ni nom de domaine requis. Le plugin integre utilise le mode WebSocket par defaut, qui etablit une connexion sortante vers les serveurs Feishu. Cela fonctionne derriere les NAT, pare-feux et la plupart des reseaux d'entreprise sans configuration de redirection de ports.

Etape 1 : Creer une application bot Feishu/Lark

Ouvrir la console developpeur

Rendez-vous sur le portail developpeur de votre plateforme :

• Feishu (Chine) : open.feishu.cn → Console developpeur
• Lark (International) : open.larksuite.com → Developer Console

Creer l'application

1. Cliquez sur Create Custom App (ou "Application d'entreprise auto-construite" selon la langue de votre interface)
2. Renseignez le nom de l'application — quelque chose de descriptif comme "OpenClaw Assistant"
3. Vous pouvez ajouter une icone et une description (c'est ce que verront les utilisateurs dans le repertoire des bots)

Copier vos identifiants

1. Allez dans Credentials & Basic Info dans le menu lateral
2. Copiez l'App ID (format : cli_a5xxxxxxxxxxxxx)
3. Copiez l'App Secret

⚠️ Gardez votre App Secret en securite. Ne le versionnez jamais dans votre code source, ne le collez pas dans un chat et ne l'incluez pas dans des captures d'ecran. En cas de fuite, regenerez-le immediatement depuis la console developpeur.

Etape 2 : Configurer les permissions du bot Feishu

Votre application a besoin de permissions (scopes) specifiques pour envoyer et recevoir des messages. Deux options s'offrent a vous.

Option A : Import par lot (recommande)

C'est l'approche la plus rapide — collez un bloc JSON et toutes les permissions sont activees d'un coup.

1. Dans les parametres de votre application, allez dans Development Settings → Permission Management
2. Cliquez sur Batch Enable (ou "Import par lot des scopes")
3. Collez le JSON suivant :

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4. Cliquez sur Confirm pour appliquer

Option B : Selection manuelle

Si l'import par lot n'est pas disponible dans votre version de la console, activez ces permissions individuellement sous Permission Management :

• im:message — Envoyer et recevoir des messages
• im:message:send_as_bot — Envoyer des messages en tant que bot
• im:message.p2p_msg:readonly — Lire les messages directs
• im:message.group_at_msg:readonly — Lire les messages @mention dans les groupes
• im:message.group_msg — Lire tous les messages de groupe
• im:resource — Acceder aux ressources des messages (images, fichiers)
• im:chat — Acceder aux metadonnees du chat
• im:chat.members:bot_access — Verifier l'appartenance du bot au chat
• contact:user.employee_id:readonly — Lire les identifiants utilisateur
• docs:document.content:read — Lire le contenu des documents (optionnel, pour les resumes)
• sheets:spreadsheet — Acceder aux tableurs (optionnel)
• wiki:wiki:readonly — Lire les pages wiki (optionnel)

Les permissions pour les documents, tableurs et wikis sont optionnelles. Activez-les uniquement si vous souhaitez que le bot puisse lire et resumer les documents partages dans le chat.

Etape 3 : Activer le bot Feishu et les abonnements aux evenements

Activer la fonctionnalite bot

1. Dans le menu lateral, allez dans App Capabilities → Bot
2. Activez la fonctionnalite bot
3. Vous pouvez ajouter une description et un texte d'aide pour le bot

Configurer les abonnements aux evenements

C'est l'etape decisive qui indique a Feishu de transmettre les messages a votre instance OpenClaw.

1. Allez dans Events & Callbacks → Event Subscriptions
2. Pour le mode de connexion, selectionnez Long Connection (WebSocket)
3. Ajoutez les evenements suivants :

L'evenement im.message.receive_v1 est le seul strictement necessaire — sans lui, votre bot ne recevra aucun message. Les evenements de reaction sont utiles si vous souhaitez declencher des actions en fonction des emojis (par exemple, un pouce leve pour confirmer une action).

⚠️ Sans abonnement aux evenements, la zone de saisie n'apparaitra pas lorsque les utilisateurs ouvrent une conversation avec votre bot dans Feishu/Lark. Si les utilisateurs voient le profil du bot mais ne peuvent rien taper, c'est presque certainement la cause.

⚠️ C'est la cause numero 1 de l'erreur "app has not established a long connection". Si vous voyez cette erreur dans vos logs, verifiez que vous avez bien ajoute au minimum l'evenement im.message.receive_v1 et selectionne le mode Long Connection.

Etape 4 : Publier l'application Feishu

Votre application ne sera visible par les utilisateurs qu'apres publication.

1. Allez dans Version Management dans le menu lateral
2. Cliquez sur Create Version
3. Renseignez un numero de version (par exemple 1.0.0) et des notes de version
4. Cliquez sur Submit for Review

Pour les applications d'entreprise internes, l'approbation est generalement automatique si vous etes administrateur du tenant (ou un admin avec acces complet). Si vous etes un developpeur regulier, l'application peut passer par le processus de validation de votre organisation — consultez votre administrateur.

Une fois publiee :

1. Ouvrez Feishu (ou Lark) sur desktop ou mobile
2. Allez dans le repertoire des applications ou la barre de recherche
3. Recherchez le nom de votre application
4. Le bot devrait apparaitre — mais ne lui envoyez pas encore de message. Configurez d'abord OpenClaw.

Etape 5 : Configurer le canal Feishu dans OpenClaw

Configuration rapide via CLI

La methode la plus rapide pour connecter :

openclaw channels add    # Selectionnez "Feishu", puis collez votre App ID et Secret
openclaw gateway restart

Le CLI vous guide a travers les parametres essentiels de maniere interactive.

Configuration manuelle

Pour un controle plus fin, modifiez directement ~/.openclaw/openclaw.json :

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Utilisez "lark" pour Lark international
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_a5xxxxxxxxxxxxx",
          appSecret: "your-app-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}

Reference de configuration

Feishu vs Lark : la seule difference de configuration est le champ domain. Definissez-le sur "feishu" si votre organisation utilise Feishu (Chine), ou "lark" si vous etes sur Lark (international). Tout le reste — identifiants, permissions, evenements — fonctionne de la meme maniere.

Etape 6 : Lancer la passerelle OpenClaw et associer Feishu

Demarrer la passerelle

openclaw gateway           # Demarre la passerelle (premier plan)

Dans un second terminal, suivez les logs :

openclaw logs --follow     # Diffuse les logs en temps reel

Vous devriez voir une sortie comme celle-ci :

[feishu] WebSocket connected to wss://open.feishu.cn/...
[feishu] Bot "AI Assistant" is online

Associer votre compte

La politique DM par defaut est pairing, ce qui signifie que les nouveaux utilisateurs doivent etre approuves avant de pouvoir discuter avec le bot. Cela empeche les acces non autorises.

1. Ouvrez Feishu (ou Lark) et trouvez votre bot
2. Envoyez n'importe quel message — "bonjour" fera l'affaire
3. Verifiez votre terminal. Vous verrez une demande d'association avec un code :

[feishu] New pairing request from user_xxxxx (Code: ABC123)

4. Approuvez l'association :

openclaw pairing approve feishu ABC123

5. Retournez dans Feishu/Lark et envoyez un autre message
6. L'IA devrait repondre

Verifier la connexion

openclaw gateway status

Resultat attendu :

Feishu: connected (websocket)
  Account: main
  Bot: AI Assistant
  Paired users: 1
  Active groups: 0

Si le statut affiche disconnected, consultez la section Depannage ci-dessous.

Configuration des groupes Feishu avec OpenClaw

Par defaut, groupPolicy: "open" permet au bot de rejoindre n'importe quel groupe ou il est ajoute. Pour un controle plus strict, utilisez une liste autorisee :

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "oc_xxxxxxxxx": {           // ID du chat Feishu
          agentId: "main",
          requireMention: false      // Exception : repondre a tous les messages dans ce groupe
        },
        "oc_yyyyyyyyy": {
          agentId: "support",        // Acheminer vers un agent different
          requireMention: true
        }
      }
    }
  }
}

Pour trouver l'identifiant d'un groupe, ajoutez le bot au groupe et consultez les logs — l'ID est affiche lorsque le bot rejoint le groupe.

Conseil : Definissez requireMention: true globalement et creez des exceptions par groupe. Cela evite que le bot soit envahissant dans les grands canaux tout en permettant une conversation libre dans les groupes dedies a l'IA.

Configuration du mode webhook Feishu

Le WebSocket est le mode de connexion recommande, mais certains reseaux d'entreprise bloquent les connexions WebSocket sortantes persistantes. Dans ce cas, passez en mode webhook :

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "from-feishu-console",
      encryptKey: "from-feishu-console",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

Pour obtenir le jeton de verification et la cle de chiffrement :

1. Dans les parametres de votre application Feishu, allez dans Events & Callbacks → Encryption Strategy
2. Copiez le Verification Token et l'Encrypt Key

Ensuite, configurez l'URL de requete dans la console Feishu :

1. Sous Events & Callbacks → Event Subscriptions, passez en mode Push to URL
2. Definissez l'URL sur https://votre-domaine.com/feishu/events
3. Cliquez sur Verify — Feishu envoie une requete de verification, et OpenClaw y repond automatiquement

⚠️ Le mode webhook necessite une URL accessible publiquement. Vous aurez besoin d'un nom de domaine, d'un certificat TLS et de regles de pare-feu appropriees. Pour la plupart des configurations, le WebSocket est bien plus simple.

Routage multi-agents pour Feishu avec OpenClaw

Si vous utilisez plusieurs agents IA, vous pouvez acheminer differentes conversations vers differents agents :

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

Par defaut, les messages directs (DM) sont achemines vers l'agent principal (main). Vous pouvez rediriger des utilisateurs specifiques ou des groupes vers des agents differents en ajoutant des regles de correspondance avec l'identifiant de l'utilisateur ou du groupe.

C'est particulierement utile pour les organisations qui souhaitent disposer d'un assistant polyvalent, d'un agent de support client et d'un agent d'outillage developpeur — tous fonctionnant via le meme bot Feishu mais alimentes par des modeles et des prompts differents.

Plugin officiel Feishu pour OpenClaw

Le plugin officiel Feishu est maintenu par l'equipe Feishu/Lark de ByteDance. Contrairement au plugin integre (qui opere en tant que bot), le plugin officiel utilise OAuth pour agir au nom d'un utilisateur. Cela lui donne acces a l'ensemble de l'espace de travail : documents, calendriers, taches, tableurs et wikis.

Prerequis

• OpenClaw ≥ 2026.2.26 (Linux/macOS) ou ≥ 2026.3.2 (Windows)
• Node.js ≥ 22
• npm disponible dans le PATH

Installation

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

La commande feishu-plugin-onboard install lance un assistant de configuration interactif. Il va :

1. Vous demander votre App ID et App Secret Feishu
2. Ouvrir une fenetre de navigateur pour l'autorisation OAuth
3. Generer un fichier de configuration dans ~/.openclaw/plugins/feishu/config.json
4. Enregistrer le plugin aupres de votre instance OpenClaw

Apres l'installation

Une fois installe, verifiez que le plugin est bien charge :

openclaw plugins list

Vous devriez voir feishu-official dans la liste. Testez-le en demandant au bot d'effectuer une action dans l'espace de travail :

@Bot Resume le dernier document dans l'espace wiki "Engineering"

Diagnostics

Si le plugin ne fonctionne pas :

feishu-plugin-onboard doctor           # Verifier les problemes courants
feishu-plugin-onboard doctor --fix     # Corriger automatiquement les problemes detectes
feishu-plugin-onboard info --all       # Afficher les informations completes du plugin

⚠️ Consideration de securite : le plugin officiel accede aux donnees de votre espace de travail via votre jeton OAuth personnel. Cela signifie que le bot peut lire tout document, evenement de calendrier ou tache auquel vous avez acces. N'utilisez pas le plugin officiel sur des bots ou machines partages — reservez-le a des instances personnelles et securisees.

Utiliser les deux plugins simultanement

Vous pouvez executer le plugin integre et le plugin officiel en parallele. Le plugin integre gere la messagerie, tandis que le plugin officiel prend en charge les actions dans l'espace de travail. OpenClaw achemine automatiquement les requetes vers le plugin approprie.

Pour desactiver le plugin officiel sans le desinstaller :

feishu-plugin-onboard disable

Depannage des problemes d'integration Feishu avec OpenClaw

"Pas de zone de saisie" — les utilisateurs ne peuvent pas ecrire au bot

Cause : les abonnements aux evenements sont manquants ou l'application n'est pas publiee.

Solution :

1. Confirmez que im.message.receive_v1 est bien ajoute sous Events & Callbacks
2. Confirmez que le mode de connexion est defini sur Long Connection
3. Confirmez que l'application est publiee (Version Management → verifiez la presence d'une version active)
4. Redemarrez la passerelle : openclaw gateway restart

Erreur "App has not established a long connection"

Cause : l'abonnement aux evenements Feishu attend une connexion WebSocket, mais OpenClaw n'est pas encore connecte.

Solution :

1. Verifiez que connectionMode est bien "websocket" dans votre configuration
2. Redemarrez la passerelle : openclaw gateway restart
3. Consultez les logs : openclaw logs --follow — cherchez les messages de connexion WebSocket
4. Si vous etes derriere un proxy strict, verifiez si les connexions WebSocket sortantes sont bloquees

Le bot est en ligne mais ne repond pas aux messages

Cause : generalement un probleme d'association ou une politique DM mal configuree.

Solution :

1. Verifiez si l'utilisateur est associe : openclaw pairing list feishu
2. En mode pairing, approuvez l'utilisateur : openclaw pairing approve feishu <CODE>
3. Si vous souhaitez que tout le monde puisse discuter sans association, definissez dmPolicy: "open"
4. Consultez les logs pour les erreurs : openclaw logs --follow

Le bot ne repond pas dans les groupes

Cause : le bot necessite une @mention mais n'a pas ete mentionne, ou la politique de groupe bloque le groupe.

Solution :

1. Verifiez que groupPolicy est "open" ou que le groupe figure dans la liste autorisee
2. Si requireMention est active, les utilisateurs doivent mentionner le bot avec @
3. Verifiez que le bot est bien membre du groupe
4. Confirmez que la permission im:message.group_msg est activee

Erreurs "Message send failed" ou "send_as_bot"

Cause : la permission im:message:send_as_bot est manquante, ou l'application n'a pas ete republiee apres l'ajout de permissions.

Solution :

1. Confirmez que la permission est activee dans la console developpeur
2. Creez une nouvelle version et publiez-la — les modifications de permissions necessitent une nouvelle publication
3. Redemarrez la passerelle

Conflit entre les plugins integre et officiel

Cause : les deux plugins tentent de traiter le meme evenement.

Solution :

1. C'est generalement sans gravite — OpenClaw deduplique les evenements. Si vous constatez des reponses en double, desactivez l'un des deux :

feishu-plugin-onboard disable    # Desactiver le plugin officiel
# OU
openclaw channels disable feishu  # Desactiver le plugin integre

2. Determinez quel plugin vous avez reellement besoin — la plupart des utilisateurs n'ont besoin que du plugin integre

Windows : erreur ENOENT lors de l'installation du plugin officiel

Cause : npm ne trouve pas le fichier .tgz telecharge, generalement un probleme de chemin sous Windows.

Solution :

1. Utilisez un chemin absolu complet :

npm install C:\Users\VotreNom\Downloads\feishu-plugin.tgz -g

2. Assurez-vous d'executer le terminal en tant qu'administrateur
3. Verifiez que Node.js ≥ 22 : node --version

Reference des commandes OpenClaw pour Feishu

FAQ

Ai-je besoin d'une IP publique ou d'un nom de domaine ?

Non. Le mode WebSocket (par defaut) etablit une connexion sortante depuis votre machine vers les serveurs Feishu. Pas de trafic entrant, pas de redirection de ports, pas d'enregistrement DNS. La seule exception est le mode webhook, qui necessite effectivement une URL accessible publiquement.

Quelle est la difference entre Feishu et Lark ?

Feishu est destine a la Chine continentale. Lark est la version internationale. Ils fonctionnent sur des infrastructures separees mais disposent des memes fonctionnalites et des memes APIs. La seule difference de configuration est le champ domain — definissez-le sur "feishu" ou "lark". Votre App ID et votre Secret fonctionnent sur la plateforme ou vous les avez crees.

Faut-il utiliser le plugin integre ou le plugin officiel ?

Pour la messagerie — envoyer et recevoir des messages, lire le contenu partage dans le chat — le plugin integre suffit amplement. Pour les actions dans l'espace de travail — lecture de documents, gestion de calendriers, creation de taches, interrogation de tableurs — utilisez le plugin officiel. Vous pouvez les executer simultanement.

Peut-on utiliser Feishu en parallele avec d'autres canaux ?

Oui. OpenClaw prend en charge plusieurs canaux simultanement. Vous pouvez avoir Feishu, Telegram, Discord, WhatsApp et d'autres canaux actifs en meme temps, chacun connecte au meme agent ou a des agents differents. Ajoutez-les avec openclaw channels add.

Les reponses sont lentes — comment accelerer ?

1. Activez le streaming (streaming: true) — cela affiche les reponses partielles au fur et a mesure de leur generation, permettant aux utilisateurs de voir le texte apparaitre immediatement
2. Verifiez votre modele — les modeles plus volumineux sont plus lents. Essayez un modele plus rapide pour les requetes courantes
3. Verifiez la latence reseau — si votre instance OpenClaw est eloignee des serveurs Feishu, les reponses paraitront plus lentes
4. Revoyez votre prompt — les prompts systeme longs augmentent le temps de traitement

Mon App Secret a ete compromis — que faire ?

1. Rendez-vous immediatement sur la console developpeur Feishu
2. Allez dans Credentials & Basic Info
3. Cliquez sur Reset a cote de l'App Secret
4. Copiez le nouveau secret
5. Mettez a jour ~/.openclaw/openclaw.json avec la nouvelle valeur
6. Redemarrez la passerelle : openclaw gateway restart
7. L'ancien secret est invalide instantanement — pas besoin de revoquer les sessions individuelles

Prochaines etapes apres la configuration Feishu

Maintenant que votre integration Feishu/Lark est operationnelle, decouvrez ce qu'OpenClaw peut faire d'autre :

• Parcourir les 50+ canaux supportes — connectez d'autres plateformes
• Repertoire des skills — decouvrez ce que votre assistant IA peut faire
• Guide de depannage — resolvez les problemes courants sur tous les canaux
• Guide complet pour debutants — apprenez OpenClaw depuis zero
• Integration Telegram — ajoutez Telegram comme canal supplementaire
• Integration Discord — configurez Discord avec les Gateway Intents