mimiclaw/docs/im-integration/FEISHU_SETUP.md

Feishu / Lark Bot Configuration Guide

This guide walks through setting up a Feishu (or Lark) bot to work with MimiClaw, turning your ESP32-S3 into a Feishu-connected AI assistant.

Table of Contents

• Overview
• Prerequisites
• Step 1: Create a Feishu App
• Step 2: Configure App Permissions
• Step 3: Set Up Event Subscription
• Step 4: Configure MimiClaw
• Step 5: Network Setup
• Step 6: Publish and Test
• Architecture
• CLI Commands
• Troubleshooting
• References

Overview

MimiClaw supports Feishu as a messaging channel alongside Telegram and WebSocket. The Feishu integration uses:

• Webhook receiver — the ESP32 runs an HTTP server on port 18790 to receive messages from Feishu
• Send API — MimiClaw sends replies via Feishu's REST API (/im/v1/messages)
• Tenant access token — automatic token management with background refresh

Both direct messages (P2P) and group chats are supported.

Prerequisites

• A Feishu account (sign up at feishu.cn) or a Lark account (larksuite.com)
• Admin access to create apps on Feishu Open Platform (or Lark Developer)
• MimiClaw flashed on an ESP32-S3 with network access
• The ESP32 must be reachable from the internet (see Network Setup)

Step 1: Create a Feishu App

1. Go to Feishu Open Platform and sign in
2. Click Create Custom App (or "Create App" on Lark)
3. Fill in the app details:
   • App Name: Choose a name (e.g., "MimiClaw Bot")
   • App Description: Brief description of your bot
   • App Icon: Upload an icon (optional)
4. After creation, you will see your App ID and App Secret on the app's Credentials & Basic Info page

Important: Save the App ID (cli_xxxxxxxxxxxxxx) and App Secret (xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). You will need these to configure MimiClaw.

Step 2: Configure App Permissions

In your app's settings, go to Permissions & Scopes and add these required permissions:

Permission	Scope ID	Description
Read/Send messages	im:message	Receive and send messages
Send messages as bot	im:message:send_as_bot	Send messages as the bot identity

To add permissions:

1. Navigate to Permissions & Scopes in the left sidebar
2. Search for each scope ID listed above
3. Click Add next to each permission
4. The permissions will take effect after you publish or update the app version

Note: On Lark (international version), the permission names may differ slightly, but the scope IDs are the same.

Step 3: Set Up Event Subscription

Event subscription allows Feishu to push new messages to your ESP32 in real-time.

Configure the Webhook URL

1. In your app settings, go to Event Subscriptions (or "Events & Callbacks")
2. Set the Request URL to:

http://<ESP32_IP>:18790/feishu/events

Replace <ESP32_IP> with your ESP32's public IP or domain name.

3. Click Save — Feishu will send a verification challenge to the URL
4. MimiClaw automatically responds to the URL verification challenge, so this should succeed if the ESP32 is reachable

Subscribe to Events

Add the following event:

Event	Event ID	Description
Receive messages	im.message.receive_v1	Triggered when users send messages to the bot

To add events:

1. In the Event Subscriptions page, click Add Event
2. Search for im.message.receive_v1
3. Select it and click Confirm

Encryption Settings (Optional)

In the event subscription settings, you can optionally configure:

• Verification Token — used to verify that events come from Feishu
• Encrypt Key — encrypts event payloads

MimiClaw currently does not verify these tokens, so you can leave them empty for simplicity. For production use, consider implementing verification.

Step 4: Configure MimiClaw

You need to provide the App ID and App Secret to MimiClaw.

Option 1: Build-time Configuration

1. Copy the secrets template if you haven't already:

cp main/mimi_secrets.h.example main/mimi_secrets.h

2. Edit main/mimi_secrets.h:

#define MIMI_SECRET_FEISHU_APP_ID     "cli_xxxxxxxxxxxxxx"
#define MIMI_SECRET_FEISHU_APP_SECRET "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. Rebuild and flash:

idf.py fullclean && idf.py build
idf.py -p PORT flash monitor

Option 2: Runtime Configuration via Serial CLI

Connect to the UART (COM) port and run:

mimi> set_feishu_creds cli_xxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This saves credentials to NVS flash immediately — no rebuild needed.

Verify Configuration

mimi> config_show

You should see feishu_app_id: cli_**** and feishu_app_secret: **** in the output.

Step 5: Network Setup

Feishu's servers need to reach your ESP32's webhook endpoint. There are several approaches:

Option A: Direct Public IP

If your ESP32 is directly accessible from the internet:

Webhook URL: http://<PUBLIC_IP>:18790/feishu/events

Option B: Port Forwarding

If the ESP32 is behind a router:

1. Log into your router's admin panel
2. Forward external port (e.g., 18790) to <ESP32_LOCAL_IP>:18790
3. Use your router's public IP in the webhook URL

Option C: Reverse Proxy / Tunnel

For development or when port forwarding isn't possible:

• ngrok: ngrok http <ESP32_IP>:18790
• frp: Configure frpc.toml to proxy to the ESP32
• Cloudflare Tunnel: Route traffic through Cloudflare

Example with ngrok:

ngrok http 192.168.1.100:18790
# Use the generated URL: https://xxxx.ngrok.io/feishu/events

Option D: Cloud Server Relay (Production)

For reliable production setups, deploy a lightweight reverse proxy on a cloud server (e.g., Volcengine ECS, AWS EC2) that forwards requests to your ESP32 via a VPN or WireGuard tunnel. This is the approach described in the Volcengine OpenClaw deployment guide.

Note: Feishu requires the webhook URL to be accessible and respond within 3 seconds. Ensure your network path has low latency.

Step 6: Publish and Test

Enable the Bot

1. In your app settings, go to Bot in the left sidebar
2. Toggle Enable Bot to ON

Publish the App

1. Go to App Release (or "Version Management & Release")
2. Click Create Version
3. Set a version number and description
4. Click Submit for Review (for enterprise apps) or Publish (for personal testing apps)

Tip: For testing, you can use the app in "development mode" without publishing — just add yourself as a test user.

Test the Bot

1. Open Feishu and search for your bot by name
2. Send a message to the bot in a direct chat
3. Check the ESP32 serial output — you should see the message being received and processed
4. The bot should reply through Feishu

For group chats:

1. Add the bot to a group
2. Mention the bot with @BotName followed by your message
3. The bot will process and reply in the group

Architecture

Feishu Cloud
    |
    |  HTTP POST /feishu/events
    |  (im.message.receive_v1)
    v
[ESP32 Webhook Server :18790]
    |
    |  message_bus_push_inbound()
    v
[Message Bus] ──> [Agent Loop] ──> [Message Bus]
                   (Claude/GPT)         |
                                        |  outbound dispatch
                                        v
                              [feishu_send_message()]
                                        |
                                        |  POST /im/v1/messages
                                        v
                                   Feishu API

Key Components

Component	Description
Webhook Server	HTTP server on port 18790, handles event callbacks
Token Manager	Manages tenant access tokens, auto-refreshes before expiry
Message Sender	Sends text messages via Feishu REST API with auto-chunking
Deduplication	Prevents processing duplicate events from Feishu retries

Configuration Constants

These can be found in main/mimi_config.h:

Constant	Default	Description
MIMI_FEISHU_MAX_MSG_LEN	4096	Max message length per chunk
MIMI_FEISHU_WEBHOOK_PORT	18790	Webhook HTTP server port
MIMI_FEISHU_WEBHOOK_PATH	/feishu/events	Webhook endpoint path
MIMI_FEISHU_WEBHOOK_MAX_BODY	16 KB	Max webhook request body size

CLI Commands

Command	Description
set_feishu_creds <app_id> <app_secret>	Save Feishu credentials to NVS
config_show	Show all configuration (including Feishu, masked)
config_reset	Clear all NVS config, revert to build-time defaults

Troubleshooting

Webhook URL verification fails

• Ensure the ESP32 is running and connected to WiFi: wifi_status
• Verify the webhook URL is reachable from the internet
• Check that port 18790 is not blocked by firewalls
• Look at ESP32 serial output for incoming HTTP requests

Bot doesn't respond to messages

1. Check credentials: config_show should show Feishu app_id and app_secret
2. Check event subscription: Ensure im.message.receive_v1 is subscribed in the Feishu app settings
3. Check permissions: Both im:message and im:message:send_as_bot must be granted
4. Check serial output: Look for message processing logs on the ESP32

"Tenant access token" errors

• Verify your App ID and App Secret are correct
• The token auto-refreshes every 2 hours — if you just set credentials, wait a moment for the first token fetch
• Ensure the ESP32 can reach https://open.feishu.cn (check proxy settings if needed)

Messages are truncated

Feishu has a 4096-character limit per message. MimiClaw automatically chunks long messages, but if you see issues, check the serial output for chunking errors.

Bot works in DM but not in groups

• Ensure the bot is added to the group
• Users must @mention the bot in group chats for it to receive messages
• Check that group messaging permissions are enabled in the Feishu app settings

Event subscription shows errors in Feishu console

• Feishu retries failed events up to 5 times with exponential backoff
• MimiClaw deduplicates retried events, so duplicate processing is not a concern
• If events consistently fail, check the ESP32's network connectivity

References

• Feishu Open Platform Documentation
• Feishu Bot Development Guide
• Feishu Message API
• Feishu Event Subscription Guide
• Lark Developer Documentation (international version)
• Volcengine OpenClaw Deployment Guide (Chinese)