OpenClaw Feishu/Lark Plugin

中文版 | English

The official Feishu/Lark plugin for OpenClaw, developed and maintained by the Lark Open Platform team. It seamlessly connects your OpenClaw Agent to your Feishu/Lark workspace, empowering it to directly read from and write to messages, documents, sheets, calendars, tasks, and more.

Features

This plugin provides comprehensive Feishu/Lark integration for OpenClaw, including:

| Category | Capabilities | |----------|--------------| | 💬 Messages | Message reading (group/DM history, topic replies), message sending, message replies, message search, image/file download | | 📄 Docs | Create cloud docs, update cloud docs, read cloud doc content | | 📊 Bitable | Create/manage bitables, data tables, fields, records (CRUD, batch operations, advanced filtering), views | | 📅 Calendar | Calendar management, event management (create/query/update/delete/search), attendee management, free/busy lookup | | ✅ Tasks | Task management (create/query/update/complete), tasklist management, subtasks, comments |

Additionally, the plugin supports:

• 📱 Interactive Cards: Real-time status updates (thinking/streaming/complete states), confirmation buttons for sensitive operations
• 🌊 Streaming Replies: Real-time streaming responses in message cards (both DMs and group chats)
• 🧠 Thinking Display: Preserves and displays AI thinking/thought process in real-time, helping users understand the AI's reasoning
• 🔒 Permission Policies: Flexible access control policies for DMs and group chats
• ⚙️ Advanced Group Configuration: Per-group settings including whitelists, skill bindings, and custom system prompts

For a complete list of features, please see FEATURES.md.

Requirements & Installation

Before you start, please ensure you have the following:

• Node.js: v22 or higher.
• OpenClaw: A working installation of OpenClaw. For details, visit the OpenClaw official website.

Note: OpenClaw version must be 2026.2.26 or higher. Check with openclaw -v. If below this version, upgrade with:

npm install -g openclaw

Create Feishu Application

1. Log in to Feishu Open Platform, click "Create Enterprise Self-built App".
2. Configure app name, description, and icon, then click "Create".
3. Add Bot capability: In the left navigation, go to "App Capabilities > Add App Capability", select "Add by Capability" tab, click "Add" on the "Bot" capability card.
4. Import required permissions: In the left navigation, go to "Development Config > Permission Management", click "Batch Import/Export Permissions", and import the complete permission list.

Note: Importing the complete permission list is very important for full functionality!

5. Publish and approve the app: Click "Create Version", configure version number and update notes, click "Save", then click "Confirm Publish".
6. Get app credentials: In the left navigation, go to "Basic Info > Credentials and Basic Info", get App ID and App Secret.

Install Feishu Plugin

Execute the following commands in your terminal:

# Set npm registry
npm config set registry https://registry.npmjs.org

# Download plugin installer
curl -o /tmp/feishu-openclaw-plugin-onboard-cli.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz

# Install plugin
npm install /tmp/feishu-openclaw-plugin-onboard-cli.tgz -g

# Clean up installer
rm /tmp/feishu-openclaw-plugin-onboard-cli.tgz

# Run installation wizard
feishu-plugin-onboard install

During installation:

• If you previously linked a Feishu app, you can choose to use the existing app or create a new one
• If no Feishu app is linked, enter the appId and appSecret created in the previous steps

Start the plugin:

openclaw gateway run

Verify success:

• After running the above command, if you see "started listening to Feishu events" in the logs, the plugin has started successfully
• Run openclaw plugins list, if feishu-openclaw-plugin Status is loaded and feishu Status is disabled, the plugin is successfully enabled

Quick Start

1. Configure openclaw.json

   After installation, edit your OpenClaw configuration file (~/.openclaw/openclaw.json) to enable the feishu-streamable channel and add your app credentials.

   Here is a minimal configuration example:

   {
     "channels": {
       "feishu-streamable": {
         "enabled": true,
         "appId": "cli_xxxxxxxxxxxxxx",
         "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
       }
     }
   }

   Make sure to replace appId and appSecret with your own app credentials.

2. Run the OpenClaw Gateway

   Save the configuration and start the OpenClaw gateway:

   openclaw gateway run

3. Pair the Bot

   • Send any message to the bot in Feishu, and the system will generate a pairing code (letters + numbers)
   • The pairing code is valid for 5 minutes; if it expires, trigger again
   • Run the following command on the server to complete the binding:

     openclaw pairing approve feishu <pairing_code> --notify

4. Complete Authorization

   Follow the prompts in Feishu to complete authorization, so OpenClaw can perform tasks like reading messages, docs, bitables, and calendars on your behalf.

   If you don't want to authorize now, you can start the conversation directly and enter /feishu auth later to complete batch authorization.

5. Start Chatting

   Your bot is now ready. To verify installation, enter /feishu start in the dialog; if it returns version info, the installation is successful.

   To teach the bot new skills, tell it: "Learn about my new Feishu plugin, list what capabilities it has"

Configuration

The plugin offers several configuration options to tailor its behavior. All settings are located under the channels.feishu-streamable key in your openclaw.json.

Basic Configuration

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | false | Enable/disable the channel | | appId | string | - | Feishu App ID | | appSecret | string | - | Feishu App Secret | | domain | string | "feishu" | API domain (feishu or lark) | | connectionMode | string | "websocket" | Connection mode (websocket or polling) |

Thinking Display Options

| Field | Type | Default | Description | |-------|------|---------|-------------| | thinkingAccumulateEnabled | boolean | false | Enable thinking accumulation (show thinking in real-time) | | thinkingRolloverChars | number | 20000 | Character threshold to start a new card when thinking is too long | | thinkingAbortFinalize | boolean | true | Whether to finalize thinking card when user sends /stop |

Reply & Streaming Options

| Field | Type | Default | Description | |-------|------|---------|-------------| | replyMode | string | "auto" | Reply mode: auto, streaming, or static | | streaming | boolean | true | Enable streaming replies | | groupStreaming | boolean | false | Enable streaming in group chats | | instantCard | boolean | false | Instantly show "processing" card before AI starts responding | | streamingBatchMs | number | 300 | Delay before sending first batch (ms). Lower = faster first response | | streamingThrottleMs | number | 1500 | Minimum interval between card updates (ms). Lower = more updates but more API calls | | footer.elapsed | boolean | true | Show elapsed time in streaming | | footer.status | boolean | true | Show status in streaming |

Access Control

| Field | Type | Default | Description | |-------|------|---------|-------------| | dmPolicy | string | "pairing" | DM policy: open, pairing, or allowlist | | groupPolicy | string | "allowlist" | Group policy: open, allowlist, or disabled | | requireMention | boolean | true | Require @mention in group chats | | groupAllowFrom | string[] | [] | Allowed group IDs |

Example Configuration

{
  "channels": {
    "feishu-streamable": {
      "enabled": true,
      "appId": "cli_xxxxxxxxxxxxxx",
      "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "streaming": true,
      "groupStreaming": true,
      "instantCard": false,
      "streamingBatchMs": 50,
      "streamingThrottleMs": 1500,
      "thinkingAccumulateEnabled": true,
      "thinkingRolloverChars": 20000,
      "thinkingAbortFinalize": true,
      "footer": {
        "elapsed": true,
        "status": true
      }
    }
  }
}

For more detailed configuration options, see FEATURES.md.

Common Commands

# View current configuration
openclaw config get channels.feishu-streamable

# Set to require @ mention to reply
openclaw config set channels.feishu-streamable.requireMention true --json

# Set to reply to all messages
openclaw config set channels.feishu-streamable.requireMention open --json

# Set specific group to require @ mention
openclaw config set channels.feishu-streamable.groups.群ID.requireMention true --json

# Enable streaming output
openclaw config set channels.feishu-streamable.streaming true

# Enable elapsed time display in streaming
openclaw config set channels.feishu-streamable.footer.elapsed true

# Enable status display in streaming
openclaw config set channels.feishu-streamable.footer.status true

# View channel status
openclaw channels status

# Upgrade plugin
feishu-plugin-onboard update

# Diagnose issues
feishu-plugin-onboard doctor

# Fix issues
feishu-plugin-onboard doctor --fix

# View version info
feishu-plugin-onboard info

# View detailed config info
feishu-plugin-onboard info --all

Group Chat Reply Modes

Mode 1: Only reply when @ mentioned (default)

openclaw config set channels.feishu-streamable.requireMention true --json

Mode 2: Reply to all messages

openclaw config set channels.feishu-streamable.requireMention false --json

Note: This mode can spam in large groups, use with caution!

Mode 3: Only specific groups require @ mention (advanced)

# First set default to not require @ for all groups
openclaw config set channels.feishu-streamable.requireMention open --json
# Then set specific group to require @
openclaw config set channels.feishu-streamable.groups.oc_xxxxxxxx.requireMention true --json

FAQ

1. Why isn't Windows supported?

   • This is a known issue in the OpenClaw core. You can track its progress at openclaw/openclaw#7631.

2. I see a Cannot find module 'xxx' error on startup.

   • This usually means the plugin's dependencies were not installed correctly. Navigate to the plugin directory at ~/.openclaw/extensions/feishu-openclaw-plugin and run npm install --production to manually install them.

3. The bot reports "insufficient permissions" when trying to read a doc or send a message.

   • Log in to the Feishu/Lark Developer Console and ensure your application has been granted the necessary API permissions. For example, reading a document requires the docx:document:readonly scope, and sending messages requires im:message:send_as_bot permission.

4. How to quickly complete user authorization?

   • Tell the AI: "I want to grant all user permissions" to complete batch authorization.
   • Or enter /feishu auth to complete batch user authorization.

5. How to verify installation success?

   • Enter /feishu start in the dialog; if it returns version info, installation is successful.
   • Enter /feishu doctor to check if configuration is normal.

6. How to update the plugin?

   • Run the following command:

   feishu-plugin-onboard update

   • If you cannot find this command, you need to install the installer first (see installation steps).

Contributing

Contributions from the community are welcome! If you find a bug or have a feature request, please open an Issue or submit a Pull Request.

For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License. See the LICENSE file for details.