mimiclaw/docs/tool-setup/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.