diff --git a/README.md b/README.md index d46d2a8..371c957 100644 --- a/README.md +++ b/README.md @@ -291,6 +291,7 @@ Technical details live in the `docs/` folder: - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — system design, module map, task layout, memory budget, protocols, flash partitions - **[docs/TODO.md](docs/TODO.md)** — feature gap tracker and roadmap +- **[docs/im-integration/](docs/im-integration/README.md)** — IM channel integration guides (Feishu, etc.) ## Contributing diff --git a/README_CN.md b/README_CN.md index 572905c..8395afe 100644 --- a/README_CN.md +++ b/README_CN.md @@ -306,6 +306,7 @@ MimiClaw 内置 cron 调度器，让 AI 可以自主安排任务。LLM 可以通 - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 系统设计、模块划分、任务布局、内存分配、协议、Flash 分区 - **[docs/TODO.md](docs/TODO.md)** — 功能差距和路线图 +- **[docs/im-integration/](docs/im-integration/README.md)** — IM 通道集成指南（飞书等） ## 贡献 diff --git a/README_JA.md b/README_JA.md index 4ba5777..90b328a 100644 --- a/README_JA.md +++ b/README_JA.md @@ -291,6 +291,7 @@ MimiClawにはcronスケジューラが内蔵されており、AIが自律的に - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — システム設計、モジュール構成、タスクレイアウト、メモリバジェット、プロトコル、Flashパーティション - **[docs/TODO.md](docs/TODO.md)** — 機能ギャップとロードマップ +- **[docs/im-integration/](docs/im-integration/README.md)** — IMチャネル統合ガイド（Feishuなど） ## 貢献 diff --git a/docs/im-integration/FEISHU_SETUP.md b/docs/im-integration/FEISHU_SETUP.md new file mode 100644 index 0000000..076a403 --- /dev/null +++ b/docs/im-integration/FEISHU_SETUP.md @@ -0,0 +1,318 @@ +# 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://:18790/feishu/events +``` + +Replace `` 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://: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 `: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 :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. + +## 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 ` | 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](https://open.feishu.cn/document/home/index) +- [Feishu Bot Development Guide](https://open.feishu.cn/document/client-docs/bot-v3/bot-overview) +- [Feishu Message API](https://open.feishu.cn/document/server-docs/im-v1/message/create) +- [Feishu Event Subscription Guide](https://open.feishu.cn/document/server-docs/event-subscription/event-subscription-guide) +- [Lark Developer Documentation](https://open.larksuite.com/document/home/index) (international version) +- [Volcengine OpenClaw Deployment Guide](https://www.volcengine.com/docs/6396/2189942) (Chinese) diff --git a/docs/im-integration/README.md b/docs/im-integration/README.md new file mode 100644 index 0000000..052bd5a --- /dev/null +++ b/docs/im-integration/README.md @@ -0,0 +1,20 @@ +# IM Integration Guides + +Configuration guides for MimiClaw's instant messaging channel integrations. + +## Guides + +| Guide | Service | Description | +|-------|---------|-------------| +| [Feishu Setup](FEISHU_SETUP.md) | [Feishu / Lark](https://open.feishu.cn/) | Feishu bot channel — receive and send messages via Feishu | + +## Overview + +MimiClaw supports multiple IM channels for interacting with the AI agent. Each guide below walks through obtaining API credentials, configuring MimiClaw (build-time or runtime), and verifying the integration. + +All credentials can be set in two ways: + +1. **Build-time** — define in `main/mimi_secrets.h` and rebuild +2. **Runtime** — use serial CLI commands (saved to NVS flash, no rebuild needed) + +See [mimi_secrets.h.example](../../main/mimi_secrets.h.example) for the full list of configurable secrets.