# ESP32S3_MimiClaw **Repository Path**: CryFzy/ESP32S3_MimiClaw ## Basic Information - **Project Name**: ESP32S3_MimiClaw - **Description**: 基于开源项目MimiClaw的开发 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2026-03-08 - **Last Updated**: 2026-04-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # MimiClaw: $5 芯片上的口袋 AI 助理

MimiClaw

License: MIT DeepWiki Discord X

**$5 芯片上的 AI 助理（OpenClaw）。没有 Linux，没有 Node.js，纯 C。** MimiClaw 把一块小小的 ESP32-S3 开发板变成你的私人 AI 助理。插上 USB 供电，连上 WiFi，通过 Telegram 跟它对话 — 它能处理你丢给它的任何任务，还会随时间积累本地记忆不断进化 — 全部跑在一颗拇指大小的芯片上。 ## 关于本仓库 - **基于**：本仓库为在开源项目 [memovai/mimiclaw](https://github.com/memovai/mimiclaw) 基础上的再开发（fork & redevelop），保留原有核心架构并做按需本地化与功能调整。 - **兼容性**：此仓库仍兼容原项目的大多数组件与部署流程，建议在同步上游前阅读变更并处理可能的冲突。 ## 认识 MimiClaw - **小巧** — 没有 Linux，没有 Node.js，没有臃肿依赖 — 纯 C - **好用** — 在 Telegram 发消息，剩下的它来搞定 - **忠诚** — 从记忆中学习，跨重启也不会忘 - **能干** — USB 供电，0.5W，24/7 运行 - **可爱** — 一块 ESP32-S3 开发板，$5，没了 ## 工作原理 ![](assets/mimiclaw.png) 你在 Telegram 发一条消息，ESP32-S3 通过 WiFi 收到后送进 Agent 循环 — LLM 思考、调用工具、读取记忆 — 再把回复发回来。LLM 层采用 `provider_catalog + provider_runtime + provider_codec + llm_proxy` 分层，同时支持 **Anthropic (Claude)**、**OpenAI (GPT)** 和 **Zhipu (GLM)**，运行时可切换。一切都跑在一颗 $5 的芯片上，所有数据存在本地 Flash。 ## 快速开始 ### 你需要 - 一块 **ESP32-S3 开发板**，16MB Flash + 8MB PSRAM（如小智 AI 开发板，~¥30） - 一根 **USB Type-C 数据线** - 一个 **Feishu Bot ** — 在 [飞书开放平台](https://open.feishu.cn/app?lang=zh-CN) 创建 - 一个可用的 **LLM API Key**： - Zhipu：从 [open.bigmodel.cn](https://open.bigmodel.cn/) 获取 - Minimax：从 [minimax.com](https://www.minimaxi.com/) 获取 - OpenRouter：从 [openrouter.ai](https://openrouter.ai/) 获取 ### 安装 ```bash # 需要先安装 ESP-IDF v5.5+: # https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/ git clone https://github.com/memovai/mimiclaw.git cd mimiclaw idf.py set-target esp32s3 ```
Ubuntu 安装 建议基线： - Ubuntu 22.04/24.04 - Python >= 3.10 - CMake >= 3.16 - Ninja >= 1.10 - Git >= 2.34 - flex >= 2.6 - bison >= 3.8 - gperf >= 3.1 - dfu-util >= 0.11 - `libusb-1.0-0`、`libffi-dev`、`libssl-dev` Ubuntu 安装与构建： ```bash sudo apt-get update sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \ cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 ./scripts/setup_idf_ubuntu.sh ./scripts/build_ubuntu.sh ```
macOS 安装 建议基线： - macOS 12/13/14 - Xcode Command Line Tools - Homebrew - Python >= 3.10 - CMake >= 3.16 - Ninja >= 1.10 - Git >= 2.34 - flex >= 2.6 - bison >= 3.8 - gperf >= 3.1 - dfu-util >= 0.11 - `libusb`、`libffi`、`openssl` macOS 安装与构建： ```bash xcode-select --install /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ./scripts/setup_idf_macos.sh ./scripts/build_macos.sh ```
### 配置 MimiClaw 使用**两层配置**：`mimi_secrets.h` 提供编译时默认值，串口 CLI 可在运行时覆盖。CLI 设置的值存在 NVS Flash 中，优先级高于编译时值。 ```bash cp main/mimi_secrets.h.example main/mimi_secrets.h ``` 编辑 `main/mimi_secrets.h`： ```c #define MIMI_SECRET_WIFI_SSID "你的WiFi名" #define MIMI_SECRET_WIFI_PASS "你的WiFi密码" #define MIMI_SECRET_FEISHU_APP_ID "cli_xxxx" #define MIMI_SECRET_FEISHU_APP_SECRET "你的飞书 App Secret" #define MIMI_SECRET_ZHIPU_API_KEY "xxxxxx" // 可选：智谱 API Key #define MIMI_SECRET_OPENROUTER_API_KEY "xxxxxx" // 可选：OpenRouter API Key #define MIMI_SECRET_MINIMAX_API_KEY "xxxxxx" // 可选：Minimax API Key #define MIMI_SECRET_TEXT_PROVIDER "zhipu" // "zhipu"/"minimax"/"openrouter" #define MIMI_SECRET_TEXT_MODEL "" // 可选：如 "claude-opus-4-5" / "glm-5" #define MIMI_SECRET_SEARCH_PROVIDER "tavily" // "zhipu"/"tavily"/"brave" #define MIMI_SECRET_FETCH_PROVIDER "tavily" // "zhipu"/"tavily" #define MIMI_SECRET_TAVILY_API_KEY "xxxxxx" // 可选：Tavily Search/Extract API Key ``` 然后编译烧录： ```bash # 完整编译（修改 mimi_secrets.h 后必须 fullclean） idf.py fullclean && idf.py build # 查找串口 ls /dev/cu.usb* # macOS ls /dev/ttyACM* # Linux # 烧录并监控（将 PORT 替换为你的串口） # USB 转接器：大概率是 /dev/cu.usbmodem11401（macOS）或 /dev/ttyACM0（Linux） idf.py -p PORT flash monitor ``` > **注意：请插对 USB 口！** 大多数 ESP32-S3 开发板有两个 Type-C 接口，必须插标有 **USB** 的那个口（原生 USB Serial/JTAG），**不要**插标有 **COM** 的口（外部 UART 桥接）。插错口会导致烧录/监控失败。 > >
> 查看参考图片 > > 请插 USB 口，不要插 COM 口 > >
### CLI 命令（通过 UART/COM 口连接） 通过串口连接即可配置和调试。**配置命令**让你无需重新编译就能修改设置 — 随时随地插上 USB 线就能改。 **运行时配置**（存入 NVS，覆盖编译时默认值）： ``` mimi> set_wifi MySSID MyPassword # 换 WiFi mimi> set_tg_token 123456:ABC... # 换 Telegram Bot Token mimi> set_feishu cli_xxx secret_xxx # 设置飞书 App ID / App Secret mimi> set_qq 123456789 abcdef... # 设置 QQ App ID / App Secret mimi> set_text_provider openai # 切换文本提供商（anthropic|openai|openrouter|zhipu|minimax） mimi> set_key openai sk-proj-... # 为指定提供商写入 API Key mimi> set_text_model gpt-4o # 切换文本模型 mimi> set_search_provider tavily # 切换搜索提供商（zhipu|tavily|brave） mimi> set_fetch_provider tavily # 切换网页读取提供商（zhipu|tavily） mimi> set_key tavily tvly-... # 为 Tavily 写入搜索/抓取 Key mimi> set_proxy 192.168.1.83 7897 # 设置代理 mimi> clear_proxy # 清除代理 mimi> config_show # 查看所有配置（脱敏显示） mimi> config_reset # 清除 NVS，恢复编译时默认值 ``` **调试与运维：** ``` mimi> wifi_status # 连上了吗？ mimi> memory_read # 看看它记住了什么 mimi> memory_write "内容" # 写入 MEMORY.md mimi> heap_info # 还剩多少内存？ mimi> session_list # 列出所有会话 mimi> session_clear 12345 # 删除一个会话 mimi> heartbeat_trigger # 手动触发一次心跳检查 mimi> cron_start # 立即启动 cron 调度器 mimi> feishu_send "hello" # 手动发送飞书测试消息 mimi> restart # 重启 ``` ### USB (JTAG) 与 UART：哪个口做什么 大多数 ESP32-S3 开发板有 **两个 USB-C 口**： | 端口 | 用途 | |------|------| | **USB**（JTAG） | `idf.py flash`、JTAG 调试 | | **COM**（UART） | **REPL 命令行**、串口控制台 | > **REPL 必须连接 UART（COM）口。** USB（JTAG）口不支持交互式 REPL 输入。
端口详情与推荐工作流 | 端口 | 标注 | 协议 | |------|------|------| | **USB** | USB / JTAG | 原生 USB Serial/JTAG | | **COM** | UART / COM | 外置 UART 桥接芯片（CP2102/CH340） | ESP-IDF 控制台默认配置为 UART 输出（`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`）。 **同时连接两个口时：** - USB（JTAG）口负责烧录/下载，并提供辅助串口输出 - UART（COM）口提供主要的交互式控制台，用于 REPL - macOS 下两个口都会显示为 `/dev/cu.usbmodem*` 或 `/dev/cu.usbserial-*`，用 `ls /dev/cu.usb*` 区分 - Linux 下 USB（JTAG）通常是 `/dev/ttyACM0`，UART 通常是 `/dev/ttyUSB0` **推荐工作流：** ```bash # 通过 USB（JTAG）口烧录 idf.py -p /dev/cu.usbmodem11401 flash # 通过 UART（COM）口打开 REPL idf.py -p /dev/cu.usbserial-110 monitor # 或使用任意串口工具：screen、minicom、PuTTY，波特率 115200 ```
## 记忆 MimiClaw 把所有数据存为纯文本文件，可以直接读取和编辑： | 文件 | 说明 | |------|------| | `AGENT.md` | 智能体的工作指南 - 指导 AI 的行为和任务 | | `SOUL.md` | 机器人的人设 — 编辑它来改变行为方式 | | `USER.md` | 关于你的信息 — 姓名、偏好、语言 | | `MEMORY.md` | 长期记忆 — 它应该一直记住的事 | | `HEARTBEAT.md` | 待办清单 — 机器人定期检查并自主执行 | | `cron.json` | 定时任务 — AI 创建的周期性或一次性任务 | | `2026-02-05.md` | 每日笔记 — 今天发生了什么 | | `feishu_12345.jsonl` | 聊天记录 — 你和它的对话 | ## 工具 MimiClaw 的工具调用走统一协议编解码层（`provider_codec`）— LLM 在对话中可以调用工具，循环执行直到任务完成（ReAct 模式）。 | 工具 | 说明 | |------|------| | `web_search` | 通过 Zhipu / Tavily / Brave 搜索网页，获取实时信息 | | `web_fetch` | 通过 Zhipu Reader / Tavily Extract 抓取网页正文 | | `file` | 统一文件工具：`action=read/write/edit/list` | | `cron` | 统一定时任务工具：`action=add/list/remove` | > 时间说明：设备通过 SNTP 持续同步系统时钟，Agent 每轮会在 `Current Turn Context` 注入 `current_time`，无需再单独调用取时工具。 启用网页搜索 / 网页抓取可在 `mimi_secrets.h` 中设置 [Tavily API key](https://app.tavily.com/home)（搜索与抓取共用，`MIMI_SECRET_TAVILY_KEY`），也可配置 [Brave Search API key](https://brave.com/search/api/)（仅搜索，`MIMI_SECRET_SEARCH_KEY`）。Tavily Extract 接口参考 [Tavily Extract 文档](https://docs.tavily.com/documentation/api-reference/endpoint/extract)，Zhipu 网页阅读接口参考 [智谱网页阅读文档](https://docs.bigmodel.cn/api-reference/%E5%B7%A5%E5%85%B7-api/%E7%BD%91%E9%A1%B5%E9%98%85%E8%AF%BB)。 ## 定时任务（Cron） MimiClaw 内置 cron 调度器，让 AI 可以自主安排任务。LLM 可以通过 `cron` 工具（`action=add`）创建周期性任务（"每 N 秒"）或一次性任务（"在某个时间戳"）。任务触发时，消息会注入到 Agent 循环 — AI 自动醒来、处理任务并回复。 任务持久化存储在 SPIFFS（`cron.json`），重启后不会丢失。典型用途：每日总结、定时提醒、定期巡检。 ## 心跳（Heartbeat） 心跳服务会定期读取 SPIFFS 上的 `HEARTBEAT.md`，检查是否有待办事项。如果发现未完成的条目（非空行、非标题、非已勾选的 `- [x]`），就会向 Agent 循环发送提示，让 AI 自主处理。 这让 MimiClaw 变成一个主动型助理 — 把任务写入 `HEARTBEAT.md`，机器人会在下一次心跳周期自动拾取执行（默认每 30 分钟）。 ## 其他功能 - **WebSocket 网关** — 端口 18789，局域网内用任意 WebSocket 客户端连接 - **OTA 更新** — WiFi 远程刷固件，无需 USB - **双核** — 网络 I/O 和 AI 处理分别跑在不同 CPU 核心 - **HTTP 代理** — CONNECT 隧道，适配受限网络 - **多提供商** — 支持 Anthropic (Claude)、OpenAI (GPT)、OpenRouter、Zhipu (GLM)，运行时可切换 - **协议分层** — Provider 元数据、运行时状态、协议编解码、网络传输四层解耦，便于扩展 - **定时任务** — AI 可自主创建周期性和一次性任务，重启后持久保存 - **心跳服务** — 定期检查任务文件，驱动 AI 自主执行 - **工具调用** — ReAct Agent 循环，两种提供商均支持工具调用 ## 支持的模型 - **Zhipu (GLM 系列)** — 支持 GLM 系列大模型（OpenAI 兼容）。 - **Minimax** — 支持 Minimax 提供的模型。 配置方法：通过 `main/mimi_secrets.h` 中的 `MIMI_SECRET_TEXT_PROVIDER` 与 `MIMI_SECRET_TEXT_MODEL` 指定编译时默认值； 运行时可使用 CLI 命令 `set_text_provider` / `set_text_model` 切换提供商与模型，并使用 `set_key ` 写入对应提供商凭据。 注意：不同提供商的 API 格式与能力存在差异，某些模型（如 flash 变体）更适合低延迟/低带宽场景。 ## 支持的消息通道 - **Telegram** — 通过 Bot Token 与 Telegram Bot 交互（使用 `MIMI_SECRET_TG_TOKEN` 配置）。 - **飞书（Feishu）** — 支持飞书机器人接入，当前通过飞书回调 WebSocket 收消息，并通过 REST API 发消息。需要在 `main/mimi_secrets.h` 中配置 `MIMI_SECRET_FEISHU_APP_ID` 与 `MIMI_SECRET_FEISHU_APP_SECRET`，或在运行时使用 `set_feishu` 写入，详见 `docs/im-integration/`。 - **QQ（官方直连）** — 使用 QQ 官方 OpenAPI + Gateway WebSocket： 需要在 `main/mimi_secrets.h` 中配置 `MIMI_SECRET_QQ_APP_ID` 与 `MIMI_SECRET_QQ_APP_SECRET`，或在运行时使用 `set_qq` 写入。当前发送链路默认走“及时回复/稳定回复”优先策略（文本直发），并在 recent 仅有 `chat_id` 时自动尝试纠正群聊/私聊端点。 - **WebSocket 网关** — 本地网关端口 `18789`，可用于自定义前端或第三方 UI 与设备实时交互。 以上通道可并行使用，Agent 会根据配置接收并分发来自不同通道的消息。