Feishu Channel Plugin for Clawdbot – Fast & Feature‑Rich

Clawdbot is a lightweight yet powerful chatbot framework, and its plugin ecosystem lets you connect it to a variety of platforms. One of the newest additions is the Feishu (Lark) channel plugin (@m1heng-clawd/feishu). It turns Clawdbot into a fully‑featured Feishu bot capable of:

Sending & receiving messages in direct chats and group channels
Uploading & downloading images, PDFs, Excel sheets, and other files
Rendering responses as plain text, Markdown cards, or raw messages
Supporting media‑heavy contexts (images + embedded text)
Managing permissions, event subscriptions, and DM pairing flows via the Feishu Open Platform

Below is a step‑by‑step guide to getting this plugin up and running, followed by a quick reference to its most useful configuration options and FAQs.

1. Prerequisites

Item	Details
Node.js	v20+ (npm or pnpm)
Clawdbot	v0.1.x or newer
Feishu App	A self‑built application on the Feishu Open Platform with the required permissions

Make sure you have admin access on the Feishu Open Platform to create a new app and grant the necessary scopes.

2. Install the Plugin

You can install the plugin directly through Clawdbot’s plugin manager or by using npm.

A. Clawdbot Plugin Manager

clawdbot plugins install @m1heng-clawd/feishu

This fetches the latest version from npm, installs it, and registers the plugin.

B. Manual NPM Install

If the above command fails due to environment issues, download the tarball and install locally:

curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
clawdbot plugins install ./feishu-0.1.1.tgz

3. Create & Configure a Feishu App

Go to the Feishu Open Platform and create a new Self‑built App.
On the Credentials page, note the App ID and App Secret.

Enable Permissions as shown below:

Required

Permission	Scope	Description
`contact:user.base:readonly`	User info	Retrieve basic user info
`im:message`	Messaging	Send and receive messages
`im:message.p2p_msg:readonly`	DM	Read private messages
`im:message.group_at_msg:readonly`	Group	Receive @mentions
`im:message:send_as_bot`	Send	Send messages as the bot
`im:resource`	Media	Upload/download images/files

Optional (enable if you need extended access)

Permission	Scope	Description
`im:message.group_msg`	Group	Read all group messages
`im:message:readonly`	Read	Get message history
`im:message:update`	Edit	Edit sent messages
`im:message:recall`	Recall	Recall sent messages
`im:message.reactions:read`	Reactions	View reactions

Configure Event Subscriptions:
- Choose Long Connection (recommended).
- Subscribe to the following events:
  - im.message.receive_v1 – mandatory for receiving messages.
  - im.message.message_read_v1 – read receipts (optional).
  - im.chat.member.bot.added_v1 – bot added to a group.
  - im.chat.member.bot.deleted_v1 – bot removed from a group.
- Ensure all event permissions have been approved by Feishu’s review process.
Publish the App – At least to the Test realm so you can add the bot to chats.

4. Configure the Plugin in Clawdbot

Open your Clawdbot configuration file (usually clawdbot.yml or equivalent) and add:

channels:
  feishu:
    enabled: true
    appId: "cli_xxxxx"
    appSecret: "your_app_secret"
    domain: "feishu"          # use "lark" for the international domain
    connectionMode: "websocket"  # "websocket" or "webhook"
    dmPolicy: "pairing"         # "pairing", "open", or "allowlist"
    groupPolicy: "allowlist"    # "open", "allowlist", or "disabled"
    requireMention: true
    mediaMaxMb: 30
    renderMode: "auto"          # "auto", "raw", or "card"

Tip – The dmPolicy pairing flow requires the user to approve direct messages. If you want instant DM access, use open.

5. Key Features & How They Work

Feature	What it Does	Configuration
WebSocket vs Webhook	WebSocket gives low‑latency, real‑time events; webhook is push‑based but easier to set up.	`connectionMode`
DM & Group Policies	Control who can talk to the bot.	`dmPolicy` & `groupPolicy`
Media Support	The bot can see images, PDFs, Excel files, etc., and can upload/download them.	`mediaMaxMb`
Typing Indicator	Uses emoji reactions to hint the bot is processing.	Built‑in – no config needed
Card Rendering	Optional rich‑formatted responses (syntax highlighting, tables, links).	`renderMode`
Event Subscriptions	Receive message events, read receipts, and bot lifecycle events.	Feishu Open Platform → Events & Callbacks

6. Common Issues & Troubleshooting

Symptom	Likely Cause	Fix
Bot cannot receive messages	Event subscriptions not set or connection mode incorrect.	Verify Long Connection is selected and `im.message.receive_v1` is subscribed.
403 on sending messages	Missing `im:message:send_as_bot` permission approval.	Request approval in the Feishu console.
Output is not streamed	Feishu API rate limits block streaming.	Use the built‑in complete‑then‑send approach (default).
Installation error: ENOENT	npm spawn path issue on Windows.	Use the manual package download method from Section 2B.
Bot not found in Feishu	App not published or visibility scope issue.	Publish to “Test” and add your account to the app’s visibility.

7. Quick Reference Commands

# Check plugin status
clawdbot plugins list

# Uninstall the plugin
clawdbot plugins uninstall @m1heng-clawd/feishu

# Restart Clawdbot to apply config changes
clawdbot restart

# Reset conversation history in a chat
/new

8. Extending the Plugin

The plugin exposes a simple TypeScript API through clawdbot.plugin. For advanced use cases, fork the repo, add custom message handlers, or integrate other Feishu SDK features. Contributions are welcome via pull requests!

9. Summary

The Feishu channel plugin for Clawdbot bridges powerful AI capabilities with Feishu’s collaborative ecosystem. With straightforward installation, robust configuration options, and rich media handling, you can quickly deploy a chatbot that feels native to Feishu. Whether you're building a team helper, a learning assistant, or just experimenting, this plugin gives you a solid foundation to start building intelligent conversations.

Happy coding—and may your bots never crash on message receipts!