【拥抱AI】详解MimiClaw上扩展飞书与GLM来改造xiaozhi-esp32的过程

本项目基于github上的开源项目MimiClaw进行改造，新增飞书通信与GLM的导入，结合xiaozhi-esp32小智机器人完成基础控制的实验。

📋 目录

项目概述

基本信息

技术特点

• ✅ 纯 C 实现 – 没有 Linux，没有 Node.js，没有臃肿依赖
• ✅ 轻量级 – 运行在拇指大小的芯片上
• ✅ 易用性 – 通过 Telegram/飞书 发消息即可使用
• ✅ 持久记忆 – 跨重启不会遗忘
• ✅ 本地存储 – 所有数据存在本地 Flash

核心特性

1. 多平台支持

2. 多 LLM 提供商

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 并行处理

技术栈

适用场景

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

附录

相关链接

• MimiClaw原项目主页: memovai/mimiclaw
• 飞书集成项目: ZhiqiangHe/mimiclaw_esp32
• ESP-IDF 文档: docs.espressif.com
• 飞书开放平台: open.feishu.cn

开发者资源

• 架构文档: docs/ARCHITECTURE.md
• TODO 列表: docs/TODO.md
• 贡献指南: docs/CONTRIBUTE.md

文档版本: 1.0 最后更新: 2026-03-05