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

MimiClaw是基于ESP32-S3的纯C语言AI助理项目，支持Telegram和飞书双平台，集成Anthropic、OpenAI、智谱AI多LLM提供商。项目具备工具调用、持久记忆、定时任务、心跳服务等核心功能，通过小智服务端实现飞书SDK集成。文档详细介绍了项目架构、配置方法、CLI命令、飞书集成流程等内容。

奔跑草-

317人浏览 · 2026-03-05 15:12:29

奔跑草- · 2026-03-05 15:12:29 发布

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

在这里插入图片描述

项目概述

基本信息

项目	说明
名称	MimiClaw
硬件	ESP32-S3 开发板（16MB Flash + 8MB PSRAM）
成本	约 $5
功耗	0.5W
运行时间	24/7
许可证	MIT
GitHub源项目	memovai/mimiclaw
改造后的项目	ZhiqiangHe/mimiclaw_esp32

技术特点

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

核心特性

1. 多平台支持

平台	状态	说明
Telegram	✅ 完整支持	原生支持
飞书	✅ 新增支持	通过小智服务端集成

2. 多 LLM 提供商

提供商	模型	切换方式
Anthropic	Claude	运行时切换
OpenAI	GPT	运行时切换
智谱AI	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 密钥管理

工具调用编排
├── 工具注册管理
├── 工具参数解析
├── 工具执行调度
└── 执行结果反馈

快速开始

硬件需求

组件	说明	备注
ESP32-S3 开发板	16MB Flash + 8MB PSRAM	如小智 AI 开发板，约 ¥30
USB Type-C 数据线	用于供电和烧录	-
网络环境	WiFi 或代理	国内需要代理

软件需求

组件	版本	获取方式
ESP-IDF	v5.5+	官方文档
飞书 App ID/Secret	-	open.feishu.cn 获取

安装步骤

# 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 命令详解

配置命令（运行时修改）

命令	参数	说明
`wifi_set`	SSID 密码	`wifi_set MySSID MyPassword`
`set_tg_token`	Bot Token	`set_tg_token 123456:ABC...`
`set_api_key`	API Key	`set_api_key sk-ant-api03-...`
`set_model_provider`	提供商	`set_model_provider openai`
`set_model`	模型名	`set_model gpt-4o`
`set_proxy`	主机端口	`set_proxy 192.168.1.83 7897`
`clear_proxy`	-	清除代理
`set_search_key`	API Key	`set_search_key BSA...`
`config_show`	-	查看所有配置（脱敏）
`config_reset`	-	清除 NVS，恢复编译时默认值

调试命令（系统运维）

命令	说明	输出示例
`wifi_status`	WiFi 连接状态	`Connected to MySSID, IP: 192.168.1.100`
`heap_info`	剩余内存	`Free heap: 245760 bytes`
`session_list`	列出所有会话	`Session 12345: 10 messages`
`session_clear`	删除会话	`session_clear 12345`
`memory_read`	查看记忆	显示 MEMORY.md 内容
`memory_write`	写入记忆	`memory_write "记住：我喜欢咖啡"`
`heartbeat_trigger`	触发心跳	手动执行心跳检查
`cron_start`	启动 cron	立即启动定时任务
`restart`	重启设备	重启 ESP32

使用场景

场景 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	`/spiffs/config/`	机器人人设
USER.md	`/spiffs/config/`	用户信息
MEMORY.md	`/spiffs/memory/`	长期记忆
HEARTBEAT.md	`/spiffs/`	待办清单
cron.json	`/spiffs/`	定时任务
tg_12345.jsonl	`/spiffs/sessions/`	聊天记录

文件内容示例

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日
- 用户喜欢喝咖啡

工具系统

工具列表

工具名	功能	API
web_search	网页搜索	Brave Search API
get_current_time	获取当前时间	HTTP API
cron_add	创建定时任务	内部 cron
cron_list	列出任务	内部 cron
cron_remove	删除任务	内部 cron

工具调用流程

用户消息
    ↓
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)

常用示例

表达式	说明
`0 8 * * *`	每天 8:00
`0 /6 * *`	每 6 小时
`0 9 * * 1-5`	工作日 9:00
`/30 * * *`	每 30 分钟
`0 0 1 * *`	每月 1 号 0:00

Cron 命令

命令	说明
`cron_add`	创建定时或一次性任务
`cron_list`	列出所有任务
`cron_remove`	按任务 ID 删除

心跳服务

工作原理

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

HEARTBEAT.md 格式

# 待办清单

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

规则：

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

使用场景

场景：定期提醒

# HEARTBEAT.md

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

效果：

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

其他功能

1. WebSocket 网关

特性	说明
端口	18789
用途	局域网内 WebSocket 客户端连接
协议	WebSocket
消息格式	JSON

使用场景：

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

2. OTA 更新

特性	说明
方式	WiFi 远程刷固件
优势	无需 USB 连接
安全	HTTPS 传输，签名验证

更新流程：

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

3. 双核架构

核心	用途	优先级
Core 0	网络 I/O	高
Core 1	AI 处理	高

优势：

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

4. HTTP 代理

特性	说明
协议	HTTP CONNECT 隧道
类型	HTTP / SOCKS5
用途	适配受限网络

架构设计

模块树状图

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

核心模块详解

1. Agent 核心

子模块	功能	关键 API
会话管理	维护多轮对话上下文	`session_create()`, `session_switch()`
LLM 调用层	与 OpenAI/Claude/智谱通信	`llm_call()`, `llm_set_provider()`
工具编排	解析 Function Calling 并执行工具	`tool_register()`, `tool_execute()`
消息循环	主事件循环	`agent_feed_message()`

2. 通信层

子模块	功能	关键流程
Bot API 封装	调用 Telegram/飞书 Bot API	HTTPS → JSON → 消息对象
消息转换	协议适配	Telegram/飞书格式 ↔ 内部格式
连接管理	保持在线	轮询 / WebSocket

3. 存储与记忆层

子模块	功能	存储位置
长期记忆	MEMORY.md 管理	SPIFFS 文件系统
配置管理	NVS 键值存储	Flash NVS 分区
会话持久化	会话历史保存	RAM + Flash 缓存

4. 串口 CLI

命令类型	示例命令	功能
配置命令	`wifi_set`, `set_api_key`	修改运行时配置
调试命令	`heap_info`, `session_list`	查看系统状态
管理命令	`restart`, `memory_write`	系统管理

飞书集成

集成架构

┌─────────────┐
│  飞书用户   │
└──────┬──────┘
       │
       ↓
┌─────────────────────────────────┐
│   飞书开放平台              │
│   - 消息事件订阅            │
│   - 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"
}

事件类型：

类型	说明
`hello`	握手消息
`welcome`	欢迎消息
`message`	用户消息
`response`	AI 回复
`ping`	心跳检测
`pong`	心跳响应

优势对比

特性	直接接入飞书 API	通过小智服务端
HTTPS 请求复杂度	高	低
Token 管理	需要自己实现	服务端处理
事件订阅	需要 Webhook	服务端处理
ESP32 资源占用	高	低
维护成本	高	低

总结

项目亮点

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

技术栈

层级	技术
硬件	ESP32-S3 (Xtensa LX7)
固件	ESP-IDF v5.5+
语言	C (FreeRTOS)
通信	WiFi、HTTP、WebSocket
存储	SPIFFS、NVS
LLM	Anthropic、OpenAI、智谱AI
搜索	Tavity、Brave Search API

适用场景

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

附录

开发者资源

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

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

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙APP架构演进：从MVC到MVVM再到声明式架构

人工智能6S服务平台

Flutter 三方库 surrealdb 的鸿蒙化适配指南 - 掌控多模型云数据库、实时同步实战、鸿蒙级精密架构专家

人工智能6S服务平台

Flutter 三方库 flutter_loggy_dio 的鸿蒙化适配指南 - 掌控全链路网络监控、Loggy 日志实战、鸿蒙级通讯诊断专家

人工智能6S服务平台

所有评论(0)

查看更多评论

奔跑草-

@u010690311

已为社区贡献1条内容

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

奔跑草-

📋 目录

项目概述

基本信息

技术特点

核心特性

1. 多平台支持

2. 多 LLM 提供商

3. 工具调用

工作原理

消息处理流程

核心组件

Agent 核心（大脑）

快速开始

硬件需求

软件需求

安装步骤

⚠️ 重要提示

配置说明

配置层次

配置文件

mimi_secrets.h（编译时配置）

CLI 命令详解

配置命令（运行时修改）

调试命令（系统运维）

使用场景

记忆系统

存储结构

文件内容示例

SOUL.md（机器人人设）

USER.md（用户信息）

MEMORY.md（长期记忆）

记忆操作

工具系统

工具列表

工具调用流程

工具示例

定时任务

Cron 表达式

常用示例

Cron 命令

心跳服务

工作原理

HEARTBEAT.md 格式

使用场景

其他功能

1. WebSocket 网关

2. OTA 更新

3. 双核架构

4. HTTP 代理

架构设计

模块树状图

核心模块详解

1. Agent 核心

2. 通信层

3. 存储与记忆层

4. 串口 CLI

飞书集成

集成架构

消息处理流程

1. 飞书消息接收

2. 飞书集成处理

3. 消息转换

WebSocket 协议

优势对比

总结

项目亮点

技术栈

适用场景

附录

相关链接

开发者资源

所有评论(0)

奔跑草-