OpenClaw Feishu: Get the Message Loop Working

The Common Mistake: Doing Too Much at Once

The most common Feishu integration failure is stacking initialization, skills, and workflows before the basic message loop works. Get one thing right first: receive a message and send a reply. Only then add skills, routing, and automation.

Step 1: Install the Official Plugin

openclaw plugins install @openclaw/feishu

Verify the plugin is installed:

openclaw plugins list

You should see @openclaw/feishu in the list.

Step 2: Create a Feishu App

1. Go to open.feishu.cn
2. Create an application (or use an existing one)
3. Record the App ID and App Secret — you will need these for openclaw channels add

Do not enable extra capabilities yet. Keep the app minimal until the message loop works.

Step 3: Add the Feishu Channel via Wizard

Run the channel wizard:

openclaw channels add

Select Feishu and follow the prompts. You will be asked for:

• App ID
• App Secret
• Verification token (optional for some setups)

The wizard configures the channel and webhook/WebSocket endpoints.

Step 4: Required Permissions

Your Feishu app needs these permissions:

Permission	Purpose
im:message	Read messages
im:message:send	Send messages
im:chat	Access chat context

In the Feishu Developer Console:

1. Open Permissions for your app
2. Add im:message, im:message:send, im:chat
3. Publish the app so permissions take effect

Permissions often require admin approval for tenant apps. Request approval in the Feishu admin console if needed.

Step 5: WebSocket Event Subscription

For real-time message handling, subscribe to:

• im.message.receive_v1 — Receives incoming messages

In the Feishu Developer Console:

1. Go to Event Subscriptions
2. Add im.message.receive_v1
3. Set the request URL to your OpenClaw gateway endpoint (e.g., https://your-openclaw-domain.com/feishu/events)

OpenClaw provides the exact URL during openclaw channels add. Use HTTPS in production.

Step 6: Version Publishing

Feishu apps often require version publishing before permissions and events work:

1. In the Developer Console, go to Version Management
2. Create a new version
3. Submit for review (or publish directly if you have permissions)
4. Ensure the version is published and effective

Unpublished apps may not receive events or send messages correctly.

Step 7: Verify the Minimal Message Loop

Test with the simplest possible flow:

1. Open a chat where the bot is added
2. Send: Hello
3. Check that OpenClaw receives the message (inspect logs: openclaw gateway logs or journalctl -u openclaw)
4. Check that a reply appears in the chat

If that works, the message loop is validated. If not, troubleshoot before adding skills.

Common Pitfalls

1. Forgetting to Publish the App

Unpublished apps do not get events. Always publish a version after changing permissions or event subscriptions.

2. Wrong Event Subscription URL

The URL must be your OpenClaw gateway URL with the Feishu webhook path. Check the exact path in openclaw channels add output.

3. Missing Permissions

im:message, im:message:send, and im:chat are required. Missing any one breaks receive or send.

4. Adding Skills Before the Loop Works

If the loop fails, adding skills only makes debugging harder. Isolate: get receive → process → send working first.

5. Bot Not Added to the Chat

The bot must be a member of the chat or group. Add it via the Feishu client before testing.

6. HTTPS and Verification

Production webhooks require HTTPS. Feishu may send a verification request; OpenClaw handles it if configured correctly. Ensure your gateway is reachable from the internet.

Minimal Validation Checklist

• Plugin @openclaw/feishu installed
• Feishu app created with App ID and App Secret
• Channel added via openclaw channels add
• Permissions im:message, im:message:send, im:chat granted
• Event im.message.receive_v1 subscribed with correct URL
• App version published
• Bot added to a test chat
• Message sent → reply received

Once the loop works, add skills and workflows one at a time.