openclaw/extensions/feishu

Feishu Extension for Clawdbot

This extension allows Clawdbot to integrate with Feishu (Lark), enabling it to send and receive messages within your Feishu organization.

Configuration

To use this extension, you need to configure it with credentials from the Feishu Open Platform.

Prerequisites

1. A Feishu (Lark) account and an organization.
2. Access to the Feishu Open Platform.

Quick Start

You can interactively configure this extension using the CLI:

pnpm clawdbot channels add feishu

This wizard will guide you through entering the required credentials.

Features

• Send & Receive Messages: Supports sending and receiving Text messages in direct chats and group chats.
  • Note: Other message types (images, files, etc.) may be displayed as generic placeholders.
• Multi-Account Support: Configure multiple Feishu bots/accounts.

Step-by-Step Configuration Guide

1. Create a Feishu Application:

   • Log in to the Feishu Open Platform.
   • Create a specific "Enterprise Self-Built App" for your bot.

2. Get App Credentials:

   • Navigate to Credentials & Basic Info.
   • Copy the App ID and App Secret. These correspond to appId and appSecret in the configuration.

3. Configure Event Subscriptions:

   • Navigate to Event Subscriptions.
   • Set the Encrypt Key (Optional, but recommended).
   • Set the Verification Token (Optional).
   • Set the Request URL to your bot's endpoint (e.g., https://your-bot-domain.com/api/feishu).
   • Add Events: Search for and add the following event:
     • im.message.receive_v1 (Receive messages)

4. Add Permissions:

   • Navigate to Permissions & Scopes.
   • Add the necessary permissions:
     • im:message (Access messages)
     • im:message:send_as_bot (Send messages as bot)
     • im:chat (Access group chats)
   • Important: Create and publish a version of your app to apply these permissions.

5. Enable Bot Capability:

   • Navigate to App Capabilities -> Bot.
   • Enable the bot capability.

Configuration Example

Add the following to your clawdbot configuration (e.g., in clawdbot.config.json or via environment variables):

{
  "extensions": {
    "feishu": {
      "appId": "cli_...",
      "appSecret": "...",
      "encryptKey": "...",        // Optional: Required if encryption is enabled
      "verificationToken": "..."  // Optional: Required for event verification
    }
  }
}

Note

encryptKey and verificationToken are optional for basic bot functionality (sending messages). However, they are required if you want to:

• Receive events securely (verify the source).
• Have enabled Encrypt Key in the Feishu Event Subscriptions settings.

Multi-Account Configuration

If you need to configure multiple Feishu bots, you can use the accounts structure:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "accounts": {
        "default": {
          "enabled": true,
          "appId": "cli_xxx",
          "appSecret": "xxx",
          "encryptKey": "xxx",
          "verificationToken": "xxx"
        },
        "team-bot": {
          "enabled": true,
          "name": "Team Bot",
          "appId": "cli_yyy",
          "appSecret": "yyy",
          "encryptKey": "yyy",
          "verificationToken": "yyy"
        }
      }
    }
  }
}

Troubleshooting

Bot not receiving messages

1. Check Event Subscription URL: Ensure the Request URL is correctly configured and accessible from Feishu servers.
2. Verify Event Subscription: Make sure im.message.receive_v1 event is added and the app version is published.
3. Check Permissions: Ensure all required permissions are granted and the app version is published.
4. Review Logs: Check Clawdbot logs for connection errors or event processing issues.

Authentication errors

1. Verify Credentials: Double-check that appId and appSecret are correct.
2. Check App Status: Ensure the app is enabled and not suspended in Feishu Open Platform.

Encryption/Verification errors

1. Match Configuration: Ensure encryptKey and verificationToken in your config match exactly what's set in Feishu Event Subscriptions.
2. Optional Fields: If you haven't enabled encryption in Feishu, you can leave these fields empty.

Current Limitations

• Message Types: Currently only text messages are fully supported. Other types (images, files, cards) will be displayed as generic placeholders.
• Reactions: Message reactions are not yet supported.
• Threads: Message threads are not yet supported.
• Media Upload: Sending images/files is not yet implemented.

Resources

• Feishu Open Platform Documentation
• Feishu Bot Development Guide