Bot Feishu

Feishu (Lark) est une plateforme de messagerie d’equipe utilisee par les entreprises pour la communication et la collaboration. Ce plugin connecte OpenClaw a un bot Feishu/Lark via l’abonnement aux evenements par WebSocket, ce qui permet de recevoir les messages sans exposer une URL de webhook publique.

Plugin integre

Feishu est fourni avec les versions actuelles d’OpenClaw, aucune installation de plugin supplementaire n’est necessaire.

Si vous utilisez un build ancien ou une installation personnalisee qui n’inclut pas Feishu en integre, installez-le manuellement :

openclaw plugins install @openclaw/feishu

Demarrage rapide

Il existe deux facons d’ajouter le canal Feishu :

Methode 1 : assistant d’installation (recommandee)

Si vous venez d’installer OpenClaw, lancez l’assistant :

openclaw onboard

L’assistant vous guide pour :

1. Creer une application Feishu et collecter les identifiants
2. Configurer les identifiants de l’application dans OpenClaw
3. Demarrer la gateway

Apres la configuration, verifiez l’etat de la gateway :

• openclaw gateway status
• openclaw logs --follow

Methode 2 : configuration par CLI

Si vous avez deja termine l’installation initiale, ajoutez le canal via la CLI :

openclaw channels add

Choisissez Feishu, puis entrez l’App ID et l’App Secret.

Apres la configuration, gerez la gateway :

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

Etape 1 : creer une application Feishu

1. Ouvrir Feishu Open Platform

Rendez-vous sur Feishu Open Platform et connectez-vous.

Les tenants Lark (international) doivent utiliser https://open.larksuite.com/app et definir domain: "lark" dans la configuration Feishu.

2. Creer une application

1. Cliquez sur Create enterprise app
2. Remplissez le nom + la description de l’application
3. Choisissez une icone

3. Copier les identifiants

Depuis Credentials & Basic Info, copiez :

• App ID (format : cli_xxx)
• App Secret

Avertissement : Gardez l’App Secret confidentiel.

4. Configurer les permissions

Dans Permissions, cliquez sur Batch import et collez :

{
  "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. Activer la capacite bot

Dans App Capability > Bot :

1. Activez la capacite bot
2. Definissez le nom du bot

6. Configurer l’abonnement aux evenements

Avertissement : Avant de configurer l’abonnement aux evenements, assurez-vous que :

1. Vous avez deja execute openclaw channels add pour Feishu
2. La gateway est en cours d’execution (openclaw gateway status)

Dans Event Subscription :

1. Choisissez Use long connection to receive events (WebSocket)
2. Ajoutez l’evenement : im.message.receive_v1

Avertissement : Si la gateway n’est pas en cours d’execution, la configuration de la connexion longue peut echouer a l’enregistrement.

7. Publier l’application

1. Creez une version dans Version Management & Release
2. Soumettez pour examen et publiez
3. Attendez l’approbation de l’administrateur (les applications d’entreprise sont generalement approuvees automatiquement)

Etape 2 : configurer OpenClaw

Configuration avec l’assistant (recommandee)

openclaw channels add

Choisissez Feishu et collez votre App ID + App Secret.

Configuration par fichier

Editez ~/.openclaw/openclaw.json :

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

Si vous utilisez connectionMode: "webhook", definissez verificationToken et encryptKey. Le serveur webhook Feishu se lie a 127.0.0.1 par defaut ; ne definissez webhookHost que si vous avez intentionnellement besoin d’une autre adresse de liaison.

Verification Token et Encrypt Key (mode webhook)

En mode webhook, definissez channels.feishu.verificationToken et channels.feishu.encryptKey dans votre configuration. Pour obtenir les valeurs :

1. Sur Feishu Open Platform, ouvrez votre application
2. Allez dans Development → Events & Callbacks
3. Ouvrez l’onglet Encryption
4. Copiez le Verification Token et l’Encrypt Key

La capture d’ecran ci-dessous montre ou trouver le Verification Token. L’Encrypt Key se trouve dans la meme section Encryption.

Configuration par variables d’environnement

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

Domaine Lark (international)

Si votre tenant est sur Lark (international), definissez le domaine sur lark (ou une chaine de domaine complete). Vous pouvez le definir au niveau channels.feishu.domain ou par compte (channels.feishu.accounts.<id>.domain).

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

Options d’optimisation des quotas

Vous pouvez reduire l’utilisation de l’API Feishu avec deux options facultatives :

• typingIndicator (par defaut true) : lorsque false, ignore les appels de reaction de saisie.
• resolveSenderNames (par defaut true) : lorsque false, ignore les appels de recherche de profil d’expediteur.

Definissez-les au niveau global ou par compte :

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

Etape 3 : demarrage + test

1. Demarrer la gateway

openclaw gateway

2. Envoyer un message de test

Dans Feishu, trouvez votre bot et envoyez-lui un message.

3. Approuver l’appairage

Par defaut, le bot repond avec un code d’appairage. Approuvez-le :

openclaw pairing approve feishu <CODE>

Apres approbation, vous pouvez discuter normalement.

Presentation

• Canal bot Feishu : bot Feishu gere par la gateway
• Routage deterministe : les reponses retournent toujours a Feishu
• Isolation des sessions : les DMs partagent une session principale ; les groupes sont isoles
• Connexion WebSocket : connexion longue via le SDK Feishu, aucune URL publique necessaire

Controle d’acces

Messages directs

• Par defaut : dmPolicy: "pairing" (les utilisateurs inconnus recoivent un code d’appairage)

• Approuver l’appairage :

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Mode liste d’autorisation : definissez channels.feishu.allowFrom avec les Open ID autorises

Conversations de groupe

1. Politique de groupe (channels.feishu.groupPolicy) :

• "open" = autoriser tout le monde dans les groupes (par defaut)
• "allowlist" = n’autoriser que groupAllowFrom
• "disabled" = desactiver les messages de groupe

2. Exigence de mention (channels.feishu.groups.<chat_id>.requireMention) :

• true = mention @ requise (par defaut)
• false = repondre sans mention

Exemples de configuration de groupe

Autoriser tous les groupes, mention @ requise (par defaut)

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

Autoriser tous les groupes, mention @ non requise

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

Autoriser uniquement des groupes specifiques

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Les identifiants de groupe Feishu (chat_id) ressemblent a : oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Restreindre les expediteurs autorises dans un groupe (liste d’autorisation par expediteur)

En plus d’autoriser le groupe lui-meme, tous les messages dans ce groupe sont filtres par l’open_id de l’expediteur : seuls les utilisateurs listes dans groups.<chat_id>.allowFrom voient leurs messages traites ; les messages des autres membres sont ignores (il s’agit d’un filtrage complet au niveau expediteur, pas uniquement pour les commandes de controle comme /reset ou /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Les identifiants utilisateur Feishu (open_id) ressemblent a : ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Obtenir les identifiants de groupe/utilisateur

Identifiants de groupe (chat_id)

Les identifiants de groupe ressemblent a oc_xxx.

Methode 1 (recommandee)

1. Demarrez la gateway et mentionnez le bot avec @ dans le groupe
2. Executez openclaw logs --follow et recherchez chat_id

Methode 2

Utilisez le debogueur d’API Feishu pour lister les conversations de groupe.

Identifiants utilisateur (open_id)

Les identifiants utilisateur ressemblent a ou_xxx.

Methode 1 (recommandee)

1. Demarrez la gateway et envoyez un DM au bot
2. Executez openclaw logs --follow et recherchez open_id

Methode 2

Verifiez les requetes d’appairage pour les Open ID utilisateur :

openclaw pairing list feishu

Commandes courantes

Remarque : Feishu ne prend pas encore en charge les menus de commandes natifs, les commandes doivent donc etre envoyees sous forme de texte.

Commandes de gestion de la gateway

Depannage

Le bot ne repond pas dans les conversations de groupe

1. Assurez-vous que le bot est ajoute au groupe
2. Assurez-vous de mentionner le bot avec @ (comportement par defaut)
3. Verifiez que groupPolicy n’est pas defini sur "disabled"
4. Consultez les logs : openclaw logs --follow

Le bot ne recoit pas de messages

1. Assurez-vous que l’application est publiee et approuvee
2. Assurez-vous que l’abonnement aux evenements inclut im.message.receive_v1
3. Assurez-vous que la connexion longue est activee
4. Assurez-vous que les permissions de l’application sont completes
5. Assurez-vous que la gateway est en cours d’execution : openclaw gateway status
6. Consultez les logs : openclaw logs --follow

Fuite de l’App Secret

1. Reinitialiser l’App Secret sur Feishu Open Platform
2. Mettre a jour l’App Secret dans votre configuration
3. Redemarrer la gateway

Echecs d’envoi de messages

1. Assurez-vous que l’application a la permission im:message:send_as_bot
2. Assurez-vous que l’application est publiee
3. Consultez les logs pour les erreurs detaillees

Configuration avancee

Comptes multiples

{
  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 controle quel compte Feishu est utilise lorsque les API sortantes ne specifient pas de accountId explicitement.

Limites de messages

• textChunkLimit : taille des morceaux de texte sortant (par defaut : 2000 caracteres)
• mediaMaxMb : limite d’upload/telechargement media (par defaut : 30 Mo)

Streaming

Feishu prend en charge les reponses en streaming via des cartes interactives. Lorsque c’est active, le bot met a jour une carte au fur et a mesure qu’il genere le texte.

{
  channels: {
    feishu: {
      streaming: true, // activer la sortie en streaming par carte (par defaut true)
      blockStreaming: true, // activer le streaming par blocs (par defaut true)
    },
  },
}

Definissez streaming: false pour attendre la reponse complete avant l’envoi.

Routage multi-agents

Utilisez bindings pour router les DMs ou groupes Feishu vers differents agents.

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

Champs de routage :

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

Voir Obtenir les identifiants de groupe/utilisateur pour les conseils de recherche.

Reference de configuration

Configuration complete : Configuration de la gateway

Options principales :

Reference dmPolicy

Types de messages pris en charge

Reception

• Texte
• Texte enrichi (post)
• Images
• Fichiers
• Audio
• Video
• Stickers

Envoi

• Texte
• Images
• Fichiers
• Audio
• Texte enrichi (support partiel)