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.