MimiClaw 基于 ESP32 扩展飞书与 GLM 集成方案详解

3. 工具调用

• 🌐 网页搜索 - Brave Search API
• 📅 定时任务 - AI 自主创建 cron 任务
• 💾 记忆管理 - 读写长期记忆
• ⏰ 时间获取 - HTTP 获取当前时间

工作原理

消息处理流程

┌─────────────┐ │ 用户消息 │ │ (飞书/Telegram)│ └──────┬──────┘ │ ↓ ┌─────────────────────────────────┐ │ 消息接收层 │ │ - Telegram Bot API │ │ - 飞书 WebSocket (小智) │ └──────┬──────────────────────┘ │ ↓ ┌─────────────────────────────────┐ │ 消息路由层 │ │ - 统一消息格式 │ │ - 通道识别 │ └──────┬──────────────────────┘ │ ↓ ┌─────────────────────────────────┐ │ Agent 核心 (大脑) │ │ - 会话管理 │ │ - 上下文构建 │ │ - LLM 调用 │ │ - 工具编排 │ └──────┬──────────────────────┘ │ ↓ ┌─────────────────────────────────┐ │ 工具执行层 │ │ - 网页搜索 │ │ - 记忆读写 │ │ - 定时任务 │ └──────┬──────────────────────┘ │ ↓ ┌─────────────────────────────────┐ │ 回复生成层 │ │ - LLM 生成回复 │ │ - 格式化输出 │ └──────┬──────────────────────┘ │ ↓ ┌─────────────────────────────────┐ │ 消息发送层 │ │ - Telegram Bot API │ │ - 飞书 API (小智) │ └──────┬──────────────────────┘ │ ↓ ┌─────────────┐ │ 用户收到 │ └───────────┘ 

核心组件

Agent 核心（大脑）

会话管理 ├── 会话创建/切换 ├── 会话历史维护 └── 上下文窗口管理 LLM 调用层 ├── OpenAI 接口适配 ├── Anthropic Claude 接口适配 ├── 智谱 AI 接口适配 ├── 模型选择与切换 └── API 密钥管理 工具调用编排 ├── 工具注册管理 ├── 工具参数解析 ├── 工具执行调度 └── 执行结果反馈 

快速开始

硬件需求

软件需求

安装步骤

# 1. 克隆项目
git clone https://github.com/memovai/mimiclaw.git
cd mimiclaw

# 2. 设置目标芯片
idf.py set-target esp32s3

# 3. 配置密钥（复制模板）
cp main/mimi_secrets.h.example main/mimi_secrets.h

# 4. 编辑配置文件
# 编辑 main/mimi_secrets.h，填入你的密钥

# 5. 编译
idf.py fullclean && idf.py build

# 6. 烧录
# 查找串口
ls /dev/cu.usb* # macOS
ls /dev/ttyACM* # Linux

# 烧录并监控
idf.py -p PORT flash monitor

⚠️ 重要提示

USB 接口选择：

• ✅ 使用标有 USB 的接口（原生 USB Serial/JTAG）
• ❌ 不要使用标有 COM 的接口（外部 UART 桥接）
• 插错接口会导致烧录/监控失败

配置说明

配置层次

优先级（从高到低）：
1. 运行时配置（NVS Flash） - CLI 命令设置
2. 编译时配置（mimi_secrets.h）- 编译时默认值

配置文件

mimi_secrets.h（编译时配置）

/* WiFi 配置 */
#define MIMI_SECRET_WIFI_SSID "你的 WiFi 名"
#define MIMI_SECRET_WIFI_PASS "你的 WiFi 密码"

/* Telegram Bot */
#define MIMI_SECRET_TG_TOKEN "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

/* 飞书机器人 */
#define MIMI_SECRET_FEISHU_APP_ID "cli_xxxxxxxxxxxxxx"
#define MIMI_SECRET_FEISHU_APP_SECRET "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

/* LLM 配置 */
#define MIMI_SECRET_API_KEY "sk-ant-api03-xxxxx"
#define MIMI_SECRET_MODEL "claude-opus-4-5"
#define MIMI_SECRET_MODEL_PROVIDER "anthropic" // "anthropic" | "openai" | "zhipu"

/* 搜索 API（可选） */
#define MIMI_SECRET_SEARCH_KEY "tvly-dev-xxxxx"
#define MIMI_SECRET_SEARCH_PROVIDER "tavily"

/* 代理配置（国内用户） */
#define MIMI_SECRET_PROXY_HOST "192.168.1.83"
#define MIMI_SECRET_PROXY_PORT "7897"
#define MIMI_SECRET_PROXY_TYPE "http" // "http" | "socks5"

CLI 命令详解

配置命令（运行时修改）

调试命令（系统运维）

使用场景

场景 1：更换 WiFi

mimi> wifi_set NewWiFi NewPassword
WiFi connecting...
WiFi connected!
IP: 192.168.1.100

场景 2：切换 LLM 提供商

mimi> set_model_provider openai
Provider switched to OpenAI
mimi> set_model gpt-4o
Model set to gpt-4o

场景 3：配置代理

mimi> set_proxy 192.168.1.83 7897
Proxy configured: 192.168.1.83:7897
mimi> wifi_status
Connected to MySSID via proxy

记忆系统

存储结构

文件内容示例

SOUL.md（机器人人设）

I am MimiClaw, a personal AI assistant running on an ESP32-S3 microcontroller.
Personality:
- Helpful and friendly
- Concise and to the point
- Curious and eager to learn
Values:
- Accuracy over speed
- User privacy and safety
- Transparency in actions

USER.md（用户信息）

# User Profile
- Name: 张三
- Language: Chinese
- Timezone: Asia/Shanghai

MEMORY.md（长期记忆）

# Long-term Memory
- 用户喜欢喝咖啡
- 用户的工作时间是 9:00-18:00
- 用户有一个 5 岁的孩子

记忆操作

写入记忆：

mimi> memory_write "记住：用户生日是 5 月 20 日"
Memory written to MEMORY.md

读取记忆：

mimi> memory_read
# Long-term Memory
- 用户生日是 5 月 20 日
- 用户喜欢喝咖啡

工具系统

工具列表

工具调用流程

用户消息
↓
Agent 解析意图
↓
判断是否需要工具
↓
调用工具（如 web_search）
↓
工具执行并返回结果
↓
Agent 整合结果
↓
生成回复
↓
发送给用户

工具示例

网页搜索：

用户：今天北京天气怎么样？
↓ Agent 调用 web_search("北京天气")
↓ 返回：北京今天晴，气温 15-25℃
↓ Agent 生成回复：北京今天天气不错，晴，气温在 15 到 25 度之间。

定时任务：

用户：每天早上 8 点提醒我喝水
↓ Agent 调用 cron_add("0 8 * * *", "提醒用户喝水")
↓ 任务保存到 cron.json
↓ 每天 8 点自动触发

定时任务

Cron 表达式

* * * * * *
│ │ │ │ │ │
│ │ │ │ │ └───── 星期几 (0-6, 0=周日)
│ │ │ └─────── 月份 (1-12)
│ │ └───────── 日期 (1-31)
│ └─────────── 小时 (0-23)
└───────────── 分钟 (0-59)

常用示例

Cron 命令

心跳服务

工作原理

每 30 分钟
↓
读取 HEARTBEAT.md
↓
检查待办事项
↓
发现未完成任务
↓
注入到 Agent 循环
↓
AI 自动处理

HEARTBEAT.md 格式

# 待办清单
- [ ] 回复客户邮件
- [ ] 准备周报
- [x] 已完成：购买咖啡豆

规则：

• - [ ] - 未完成任务，会触发 AI 处理
• - [x] - 已完成任务，忽略
• 空行或标题 - 忽略

使用场景

场景：定期提醒

# HEARTBEAT.md
- [ ] 每周一提醒我准备周报
- [ ] 每天 9 点提醒我喝水
- [ ] 每月 1 号提醒我交房租

效果：

• 心跳服务每 30 分钟检查一次
• 发现未完成任务时，自动通知 AI
• AI 会主动提醒用户

其他功能

1. WebSocket 网关

使用场景：

• Web 界面控制
• 第三方应用集成
• 调试和监控

2. OTA 更新

更新流程：

新固件上传到服务器
↓
ESP32 检测到更新
↓
下载固件
↓
验证签名
↓
写入 Flash
↓
重启

3. 双核架构

优势：

• 网络和 AI 处理并行
• 提高响应速度
• 避免阻塞

4. HTTP 代理

架构设计

模块树状图

mimiclaw/
├── 🎯 核心应用层
│   ├── 📍 入口与初始化
│   │   ├── app_main() - 程序入口
│   │   ├── 系统初始化 - WiFi、NVS、SPIFFS
│   │   └── 任务调度 - FreeRTOS 任务创建
│   │
│   ├── 🤖 Agent 核心 (核心大脑)
│   │   ├── 会话管理
│   │   ├── LLM 调用层
│   │   ├── 工具调用编排
│   │   └── 消息处理循环
│   │
│   └── 🛠️ 工具模块
│       ├── 内置工具
│       └── 自定义工具扩展点
│
├── 📡 通信层
│   ├── 📱 Telegram 客户端
│   ├── 📱 飞书客户端
│   └── 🌐 网络基础层
│
├── 💾 存储与记忆层
│   ├── 📝 长期记忆
│   ├── ⚙️ 配置管理
│   └── 💾 会话持久化
│
├── 🖥️ 用户交互层
│   ├── ⌨️ 串口 CLI
│   └── 💬 消息路由
│
├── 🏗️ 系统服务层
│   ├── ⏰ 定时任务
│   ├── 📊 系统监控
│   └── 🔄 电源管理
│
└── 📁 数据文件
    ├── 📄 spiffs_data/
    └── 🔧 配置模板

核心模块详解

1. Agent 核心

2. 通信层

3. 存储与记忆层

4. 串口 CLI

飞书集成

集成架构

┌─────────────┐
│ 飞书用户    │
└──────┬──────┘
       ↓
┌─────────────────────────────────┐
│ 飞书开放平台                    │
│ - 消息事件订阅                  │
│ - Bot API                       │
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────────┐
│ 小智服务端                      │
│ - 飞书 SDK 集成                   │
│ - WebSocket 服务                  │
│ - 消息转发                      │
└──────┬──────────────────────┘
       ↓ WebSocket
┌─────────────────────────────────┐
│ ESP32 (MimiClaw)                │
│ - WebSocket 客户端              │
│ - Agent 核心                    │
│ - 消息处理                      │
└─────────────────────────────────┘

消息处理流程

1. 飞书消息接收

飞书 SDK (WebSocket)
↓ 收到消息事件
↓ lark.JSON.marshal(data)
↓ 转换为字典
↓ self._message_handler(event_dict)
↓ 传递给集成层

2. 飞书集成处理

_handle_feishu_message(event_dict)
↓ 提取消息内容
↓ 遍历所有连接的客户端
↓ self.forwarder.forward_to_client(message, client_handler)
↓ 转发消息

3. 消息转换

forward_to_client(message, client_handler)
↓ self.converter.feishu_to_client(feishu_message)
↓ 检查是否是飞书事件消息
↓ 提取 message、sender 等信息
↓ 解析消息内容（content 字段是 JSON 字符串）
↓ 转换为内部格式
↓ 发送到 Agent

WebSocket 协议

连接 URI：

ws://127.0.0.1:28000/xiaozhi/v1/?client=mimiclaw

消息格式：

{"type":"message","content":"用户消息内容","chat_id":"oc_xxxxxxxxx","sender_id":"ou_xxxxxxxxx"}

事件类型：

优势对比

总结

项目亮点

✅ 轻量级 - 纯 C 实现，无臃肿依赖 ✅ 多平台 - 支持 Telegram 和飞书 ✅ 多 LLM - 支持 Anthropic、OpenAI、智谱 AI ✅ 工具调用 - ReAct Agent 模式 ✅ 持久记忆 - 本地存储，跨重启不丢失 ✅ 定时任务 - AI 自主创建和管理 ✅ 心跳服务 - 主动型助理 ✅ OTA 更新 - 远程固件升级 ✅ 双核架构 - 网络和 AI 并行处理

技术栈

适用场景

• 🏠 家庭助理 - 智能家居控制
• 💼 办公助理 - 日程管理、信息查询
• 🎓 学习助手 - 知识问答、笔记整理
• 🤖 开发助手 - 代码生成、技术问答
• 🎮 娱乐机器人 - 聊天、游戏互动