Why Feishu?
Feishu (飞书), known internationally as Lark, is ByteDance's enterprise collaboration platform — widely used across Chinese tech companies, startups, and increasingly in Southeast Asia. With OpenClaw v2026.2.2, Feishu became the platform's first officially supported Chinese chat client.
- •No public URL required — no ngrok, no domain, no webhook server
- •Works behind firewalls — the connection is outbound from your machine
- •Low latency — real-time bidirectional messaging
- •Rich content support — text, images, files, audio, video, and stickers
Prerequisites
- •OpenClaw v2026.2.2 or later
- •A Feishu/Lark enterprise account (free tier works)
- •Admin access to create apps on the Feishu Open Platform
Step 1: Create a Feishu App
- 1.Go to the Feishu Open Platform (or Lark Developer Console for international tenants)
- 2.Click Create Custom App
- 3.Set the app name (e.g., "OpenClaw Agent") and description
- 4.Upload an icon (the OpenClaw lobster logo works well)
- 5.Copy the App ID (format:
cli_xxx) and App Secret from the Credentials page
Step 2: Configure App Permissions
In your app's permission settings, enable these scopes:
| Permission | Purpose |
|---|---|
im:message | Send and receive messages |
im:message.group_at_msg | Receive @mentions in group chats |
im:resource | Access images and files |
contact:user.id:readonly | Identify users |
After adding permissions, click Publish to submit for review. In most enterprise tenants, self-built apps are auto-approved.
Step 3: Enable Event Subscription
- 1.In the app settings, go to Event Subscriptions
- 2.Select WebSocket Mode (long connection) — this is critical. Do NOT use the webhook mode, as it requires a public URL.
- 3.Subscribe to these events:
Step 4: Configure OpenClaw
Add the Feishu credentials to your OpenClaw configuration. Edit ~/.openclaw/.env:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
Or if using the OpenClaw config file (~/.openclaw/config.yaml):
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
Restart OpenClaw:
openclaw restart
You should see a log message confirming the Feishu WebSocket connection is established.
Step 5: Test the Connection
Open Feishu and find your app in the chat list (search for the app name you set in Step 1). Send a message:
> Hello!
- •Text messages
- •Images (the agent can analyze them if using a vision-capable model)
- •Files (the agent can read documents)
- •Voice messages (transcribed and processed as text)
Group Chat Configuration
OpenClaw supports Feishu group chats with three access modes:
| Mode | Behavior |
|---|---|
open (default) | Any group member can trigger the bot when @mentioned |
allowlist | Only approved users can interact, even with @mention |
disabled | Group messages are completely ignored |
Configure in config.yaml:
channels:
feishu:
groupAccess: open # or "allowlist" or "disabled"
allowedUsers: # only used with "allowlist" mode
- user_id_1
- user_id_2
In group chats, the agent only responds when @mentioned, preventing noise in busy channels.
Streaming Responses
OpenClaw supports streaming AI responses in Feishu using interactive cards. Instead of waiting for the full response, the agent sends an initial card and updates it in real time as the AI generates text. This provides a much better user experience for long responses.
Streaming is enabled by default. To disable it:
channels:
feishu:
streaming: false
Message Types Supported
| Direction | Supported Types |
|---|---|
| Inbound (user → agent) | Text, rich text (post), images, files, audio, video, stickers |
| Outbound (agent → user) | Text, images, files, audio, interactive cards |
Troubleshooting
"App not found" error: Make sure the app is published and approved in your Feishu tenant. Self-built apps in enterprise tenants usually auto-approve, but some organizations require admin approval.
No response from agent: Check OpenClaw logs (openclaw logs) for WebSocket connection errors. Verify that the App ID and App Secret are correct.
Messages not arriving in group chats: Ensure the bot is added to the group, and that the user is @mentioning the bot correctly. Check the groupAccess setting.
Connection drops: The WebSocket connection auto-reconnects. If drops are frequent, check your network stability or firewall settings.
Using the Community Bridge (Alternative)
If you need features beyond the native integration, the community-maintained feishu-openclaw bridge by AlexAnys offers additional capabilities like custom message formatting and advanced group management. It takes about 5 minutes to set up and requires no public server.
For complete documentation, see the official Feishu channel guide.