MimiClaw：基于5美元芯片的口袋AI助手

English | 中文 | 日本語

全球首款运行在5美元芯片上的AI助手（OpenClaw）。无需Linux，无需Node.js，纯C语言实现。

MimiClaw可以将一块小巧的ESP32-S3开发板变成你的私人AI助手。只需接入USB电源、连接WiFi，并通过Telegram与它对话——无论你提出什么任务，它都能轻松应对，并且会利用本地存储不断学习进化，这一切都仅靠一颗拇指大小的芯片完成。

认识MimiClaw

• 微型 — 无Linux，无Node.js，无臃肿软件，纯C代码
• 便捷 — 通过Telegram发送消息，剩下的交由它处理
• 忠诚 — 基于内存学习，重启后仍能记住信息
• 高效 — USB供电，功耗仅0.5W，可全天候运行
• 亲民 — 仅需一块ESP32-S3开发板，成本约5美元，无需其他配件

工作原理

当你在Telegram上发送消息时，ESP32-S3通过WiFi接收该消息，将其输入到代理循环中——LLM进行思考、调用工具、读取记忆——然后将回复发回给你。支持Anthropic（Claude）和OpenAI（GPT）两种模型提供商，可在运行时切换。所有操作均在一块仅需5美元的芯片上完成，数据完全存储在本地闪存中。

快速入门

所需材料

• 一块带有16MB闪存和8MB PSRAM的ESP32-S3开发板（例如Xiaozhi AI板，约10美元）
• 一根USB Type-C数据线
• 一个Telegram机器人Token — 可在Telegram上联系@BotFather获取
• 一个Anthropic API密钥 — 从console.anthropic.com获取，或一个OpenAI API密钥 — 从platform.openai.com获取

安装步骤

# 首先需要安装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

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

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闪存中，优先级高于编译时的默认值。

cp main/mimi_secrets.h.example main/mimi_secrets.h

编辑main/mimi_secrets.h文件：

#define MIMI_SECRET_WIFI_SSID       "YourWiFiName"
#define MIMI_SECRET_WIFI_PASS       "YourWiFiPassword"
#define MIMI_SECRET_TG_TOKEN        "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
#define MIMI_SECRET_API_KEY         "sk-ant-api03-xxxxx"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"     // "anthropic" 或 "openai"
#define MIMI_SECRET_SEARCH_KEY      ""              // 可选：Brave Search API密钥
#define MIMI_SECRET_TAVILY_KEY      ""              // 可选：Tavily API密钥（推荐）
#define MIMI_SECRET_PROXY_HOST      ""              // 可选：例如 "10.0.0.1"
#define MIMI_SECRET_PROXY_PORT      ""              // 可选：例如 "7897"

随后进行编译和烧录：

# 清理构建（每次修改mimi_secrets.h后必须执行）
idf.py fullclean && idf.py build

# 查找串口设备
ls /dev/cu.usb*          # macOS
ls /dev/ttyACM*          # Linux

# 烧录并监视（将PORT替换为你的串口）
# USB适配器：通常是/macOS上的/dev/cu.usbmodem11401或/Linux上的/dev/ttyACM0
idf.py -p PORT flash monitor

重要提示：请务必插入正确的USB端口！ 大多数ESP32-S3开发板配备两个USB-C接口。你必须使用标有USB（原生USB串口/JTAG）的那一端，而不能使用标有COM（外部UART桥接）的那一端。如果插错端口，会导致烧录或监视失败。

参考图片

CLI命令（通过UART/COM端口）

通过串口连接以进行配置或调试。配置命令允许你在不重新编译的情况下更改设置——只需随时插入USB线即可。

运行时配置（保存至NVS，会覆盖编译时默认值）：

mimi> wifi_set MySSID MyPassword   # 更改WiFi网络
mimi> set_tg_token 123456:ABC...   # 更改Telegram机器人Token
mimi> set_api_key sk-ant-api03-... # 更改API密钥（Anthropic或OpenAI）
mimi> set_model_provider openai    # 切换模型提供商（anthropic|openai）
mimi> set_model gpt-4o             # 更改LLM模型
mimi> set_proxy 127.0.0.1 7897  # 设置HTTP代理
mimi> clear_proxy                  # 移除代理
mimi> set_search_key BSA...        # 设置Brave Search API密钥
mimi> set_tavily_key tvly-...      # 设置Tavily API密钥（推荐）
mimi> config_show                  # 显示所有配置（已加密）
mimi> config_reset                 # 清除NVS，恢复为编译时默认值

调试与维护：

mimi> wifi_status              # 我是否已连接WiFi？
mimi> memory_read              # 查看机器人当前的记忆内容
mimi> memory_write "content"   # 向MEMORY.md写入内容
mimi> heap_info                # 当前剩余多少RAM？
mimi> session_list             # 列出所有聊天会话
mimi> session_clear 12345      # 清除指定会话
mimi> heartbeat_trigger           # 手动触发心跳检查
mimi> cron_start                  # 立即启动定时任务调度器
mimi> restart                     # 重启设备

USB（JTAG）与 UART：各端口的用途

大多数 ESP32-S3 开发板都提供了 两个 USB-C 端口：

REPL 需要使用 UART（COM）端口。 USB（JTAG）端口不支持交互式 REPL 输入。

# 通过 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 将所有内容存储为纯文本文件，您可以直接阅读和编辑：

工具

MimiClaw 同时支持 Anthropic 和 OpenAI 的工具调用——LLM 可以在对话过程中调用工具，并循环执行直到任务完成（ReAct 模式）。

要启用网页搜索功能，请通过 MIMI_SECRET_TAVILY_KEY 设置 [Tavily API 密钥]（https://app.tavily.com/home），这是首选方式；或者通过 MIMI_SECRET_SEARCH_KEY 在 mimi_secrets.h 中设置 [Brave Search API 密钥]（https://brave.com/search/api/）。

Cron 任务

MimiClaw 内置了一个 cron 定时器，允许 AI 自动安排自己的任务。LLM 可以通过 cron_add 工具创建周期性任务（“每隔 N 秒”）或一次性任务（“在某个 Unix 时间戳”）。当任务触发时，其消息会被注入到代理循环中——因此 AI 会醒来、处理任务并作出响应。

这些任务会持久化到 SPIFFS（cron.json）中，即使重启也能保留。典型应用场景包括每日总结、定期提醒以及定时检查等。

心跳机制

心跳服务会定期从 SPIFFS 中读取 HEARTBEAT.md 文件，并检查其中是否有待办事项。如果发现未完成的任务（非空行、标题或已勾选的 - [x] 方框），它会向代理循环发送提示，让 AI 自主执行这些任务。

这使得 MimiClaw 成为一个主动型助手——只需将任务写入 HEARTBEAT.md，机器人就会在下一次心跳周期（默认每 30 分钟）自动处理它们。

其他功能

• WebSocket 网关，位于端口 18789——可通过任何 WebSocket 客户端从您的局域网连接
• OTA 更新——无需 USB，即可通过 WiFi 烧录新固件
• 双核架构——网络 I/O 和 AI 处理分别运行在不同的 CPU 核心上
• HTTP 代理——支持 CONNECT 隧道，适用于受限网络
• 多提供商支持——同时支持 Anthropic（Claude）和 OpenAI（GPT），可在运行时切换
• Cron 定时器——AI 可以自主安排周期性和一次性任务，且重启后仍能保留
• 心跳机制——定期检查任务文件，并提示 AI 自主行动
• 工具调用——ReAct 代理循环，支持两家提供商的工具调用

针对开发者

技术细节请参阅 docs/ 文件夹：

• docs/ARCHITECTURE.md——系统设计、模块图、任务布局、内存预算、协议、闪存分区
• docs/TODO.md——功能差距跟踪与路线图
• docs/WIFI_ONBOARDING_AP.md——本地 MimiClaw-XXXX 入网/管理 AP 流程的工作原理
• docs/tool-setup/——外部服务集成（如 Tavily 等）的配置指南

贡献说明

在提交问题或拉取请求之前，请先阅读 CONTRIBUTING.md。

贡献者

感谢所有为 MimiClaw 做出贡献的人。

许可证

MIT 许可证

致谢

受 OpenClaw 和 Nanobot 的启发。MimiClaw 重新实现了面向嵌入式硬件的核心 AI 代理架构——无需 Linux，无需服务器，仅需一块价值 5 美元的芯片。

星标历史

MimiClaw 快速上手指南

MimiClaw 是一款运行在廉价 ESP32-S3 芯片（约 5 美元）上的轻量级 AI 助手。它无需 Linux 或 Node.js，仅用纯 C 语言编写，通过 Telegram 与你交互，支持本地记忆和自主任务调度。

环境准备

系统要求

• 操作系统：Ubuntu 22.04/24.04 或 macOS 12/13/14
• Python：>= 3.10
• ESP-IDF：v5.5+ (Espressif IoT Development Framework)

前置依赖安装

Ubuntu 用户：

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

macOS 用户：

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake ninja dfu-util

注意：请确保已正确安装 ESP-IDF v5.5+。如未安装，可参考官方文档：https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/

安装步骤

1. 克隆项目并配置目标

git clone https://github.com/memovai/mimiclaw.git
cd mimiclaw
idf.py set-target esp32s3

2. 运行自动配置脚本

根据系统选择对应脚本（会自动处理 ESP-IDF 环境变量）：

Ubuntu:

./scripts/setup_idf_ubuntu.sh
./scripts/build_ubuntu.sh

macOS:

./scripts/setup_idf_macos.sh
./scripts/build_macos.sh

3. 配置密钥信息

复制示例配置文件并编辑：

cp main/mimi_secrets.h.example main/mimi_secrets.h

使用文本编辑器打开 main/mimi_secrets.h，填入以下信息：

#define MIMI_SECRET_WIFI_SSID       "你的 WiFi 名称"
#define MIMI_SECRET_WIFI_PASS       "你的 WiFi 密码"
#define MIMI_SECRET_TG_TOKEN        "你的 Telegram Bot Token"
#define MIMI_SECRET_API_KEY         "你的 Anthropic 或 OpenAI API Key"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"     // 可选："anthropic" 或 "openai"
#define MIMI_SECRET_TAVILY_KEY      ""              // 可选：Tavily 搜索 API Key（推荐）

获取 Token 指引：

• Telegram Bot Token: 在 Telegram 中联系 @BotFather 创建。
• API Key: Anthropic Console 或 OpenAI Platform。

4. 编译与烧录

重要提示：ESP32-S3 开发板通常有两个 USB-C 接口。请务必连接到标记为 USB (Native USB/JTAG) 的端口，不要连接到标记为 COM 的端口，否则烧录会失败。

执行清洁构建并烧录：

# 修改过 mimi_secrets.h 后必须执行 fullclean
idf.py fullclean && idf.py build

# 查看串口设备名
ls /dev/cu.usb*          # macOS
ls /dev/ttyACM*          # Linux

# 替换 PORT 为你的实际端口号进行烧录和监控
idf.py -p PORT flash monitor

基本使用

1. 运行时配置 (可选)

如果不希望重新编译，可通过串口 CLI 动态修改配置。请使用标记为 COM (UART) 的端口连接串口终端（如 screen, minicom 或 IDE 自带终端），波特率 115200。

常用命令示例：

mimi> wifi_set MySSID MyPassword
mimi> set_tg_token 123456:ABC...
mimi> set_api_key sk-ant-api03-...
mimi> set_model_provider openai
mimi> config_show

2. 开始对话

1. 确保设备已通电并连接 WiFi（串口日志显示连接成功）。
2. 打开 Telegram，找到你创建的 Bot。
3. 发送任意消息（例如：“你好，介绍一下你自己”）。
4. Bot 将调用 LLM 进行处理并回复。

3. 高级功能简述

• 长期记忆：Bot 会自动将重要信息存入 MEMORY.md，重启后依然记得。
• 自主任务：编辑设备文件系统中的 HEARTBEAT.md 添加待办事项，Bot 会定期检查并主动执行。
• 联网搜索：若配置了 Tavily 或 Brave API Key，Bot 可实时搜索网络信息回答最新问题。

现在，你拥有一个运行在拇指大小芯片上的私人 AI 助手！