本项目基于github上的开源项目MimiClaw进行改造，新增飞书通信与GLM的导入，结合xiaozhi-esp32小智机器人完成基础控制的实验。 📋 目录 项目概述 核心特性 工作原理 快速开始 配置说明 CLI命令详解 记忆系统 工具系统 定时任务 心跳服务 其他功能 架构设计 飞书集成 项目概述 基本信息
技术特点 ✅ 纯 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 或代理 国内需要代理
软件需求
安装步骤 # 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* # macOSls /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 配置 */#defineMIMI_SECRET_WIFI_SSID"你的WiFi名"#defineMIMI_SECRET_WIFI_PASS"你的WiFi密码"/* Telegram Bot */#defineMIMI_SECRET_TG_TOKEN"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"/* 飞书机器人 */#defineMIMI_SECRET_FEISHU_APP_ID"cli_xxxxxxxxxxxxxx"#defineMIMI_SECRET_FEISHU_APP_SECRET"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"/* LLM 配置 */#defineMIMI_SECRET_API_KEY"sk-ant-api03-xxxxx"#defineMIMI_SECRET_MODEL"claude-opus-4-5"#defineMIMI_SECRET_MODEL_PROVIDER"anthropic"// "anthropic" | "openai" | "zhipu"/* 搜索 API（可选） */#defineMIMI_SECRET_SEARCH_KEY"tvly-dev-xxxxx"#defineMIMI_SECRET_SEARCH_PROVIDER"tavily"/* 代理配置（国内用户） */#defineMIMI_SECRET_PROXY_HOST"192.168.1.83"#defineMIMI_SECRET_PROXY_PORT"7897"#defineMIMI_SECRET_PROXY_TYPE"http"// "http" | "socks5"CLI 命令详解 配置命令（运行时修改）
命令 参数 说明 示例 wifi_setSSID 密码 wifi_set MySSID MyPasswordset_tg_tokenBot Token set_tg_token 123456:ABC...set_api_keyAPI Key set_api_key sk-ant-api03-...set_model_provider提供商 set_model_provider openaiset_model模型名 set_model gpt-4oset_proxy主机 端口 set_proxy 192.168.1.83 7897clear_proxy- 清除代理 set_search_keyAPI Key set_search_key BSA...config_show- 查看所有配置（脱敏） config_reset- 清除 NVS，恢复编译时默认值
调试命令（系统运维）
命令 说明 输出示例 wifi_statusWiFi 连接状态 Connected to MySSID, IP: 192.168.1.100heap_info剩余内存 Free heap: 245760 bytessession_list列出所有会话 Session 12345: 10 messagessession_clear删除会话 session_clear 12345memory_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
使用场景 ：
2. OTA 更新
特性 说明 方式 WiFi 远程刷固件 优势 无需 USB 连接 安全 HTTPS 传输，签名验证
更新流程 ：
新固件上传到服务器 ↓ ESP32 检测到更新 ↓ 下载固件 ↓ 验证签名 ↓ 写入 Flash ↓ 重启 3. 双核架构
核心 用途 优先级 Core 0 网络 I/O 高 Core 1 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用户消息 responseAI 回复 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
适用场景 🏠 家庭助理 - 智能家居控制 💼 办公助理 - 日程管理、信息查询 🎓 学习助手 - 知识问答、笔记整理 🤖 开发助手 - 代码生成、技术问答 🎮 娱乐机器人 - 聊天、游戏互动 附录 相关链接 开发者资源 文档版本 : 1.0最后更新 : 2026-03-05
