3e66c8ee64
Cover webhook URL configuration, event subscription for im.message.receive_v1, build-time and runtime credential setup, and network options (direct IP, port forwarding, ngrok, cloud relay).
192 lines
6.4 KiB
Markdown
192 lines
6.4 KiB
Markdown
# 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](#overview)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Step 1: Create a Feishu App](#step-1-create-a-feishu-app)
|
|
- [Step 2: Configure App Permissions](#step-2-configure-app-permissions)
|
|
- [Step 3: Set Up Event Subscription](#step-3-set-up-event-subscription)
|
|
- [Step 4: Configure MimiClaw](#step-4-configure-mimiclaw)
|
|
- [Step 5: Network Setup](#step-5-network-setup)
|
|
- [Step 6: Publish and Test](#step-6-publish-and-test)
|
|
- [Architecture](#architecture)
|
|
- [CLI Commands](#cli-commands)
|
|
- [Troubleshooting](#troubleshooting)
|
|
- [References](#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](https://www.feishu.cn)) or a Lark account ([larksuite.com](https://www.larksuite.com))
|
|
- Admin access to create apps on [Feishu Open Platform](https://open.feishu.cn/) (or [Lark Developer](https://open.larksuite.com/))
|
|
- MimiClaw flashed on an ESP32-S3 with network access
|
|
- The ESP32 must be reachable from the internet (see [Network Setup](#step-5-network-setup))
|
|
|
|
## Step 1: Create a Feishu App
|
|
|
|
1. Go to [Feishu Open Platform](https://open.feishu.cn/) 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:
|
|
|
|
```bash
|
|
cp main/mimi_secrets.h.example main/mimi_secrets.h
|
|
```
|
|
|
|
2. Edit `main/mimi_secrets.h`:
|
|
|
|
```c
|
|
#define MIMI_SECRET_FEISHU_APP_ID "cli_xxxxxxxxxxxxxx"
|
|
#define MIMI_SECRET_FEISHU_APP_SECRET "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
```
|
|
|
|
3. Rebuild and flash:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](https://www.volcengine.com/docs/6396/2189942).
|
|
|
|
> **Note:** Feishu requires the webhook URL to be accessible and respond within 3 seconds. Ensure your network path has low latency.
|