MiniClaw 基础功能一览
0x00 概要
0x01 基本知识
0x02 设计理念
0x03 机器人概念
机器人的人设与大脑接口
工具程序
外延与技能集合
程序提示词与差异化优势
0x04 工作原理与架构细节
0xFF 参考链接与资源下载地址
MiniClaw 的主要痛点映射
成本过高？没有云端订阅费，
MiniClaw 使用单颗 ESP32‑S3。$5 左右，完全零服务器费用，直接跑在家里或边缘设备上。使用者只需一次性购买硬件，即可获得持续 AI 助手功能。
担心数据泄露？需要把敏感信息送到云端，
所有对话、记忆、技能都保存在本地 Flash，不依赖任何第三方服务器。即使 WiFi 离线，助手也能保持完整记忆并继续工作。
离线环境下怎么办？无法连接 Telegram 或网络？
MiniClaw 内置 OTA 与自愈 WiFi 状态机；当网络恢复时会自动同步最新固件和任务。在完全离线时所有本地工具仍然可用。
部署步骤繁琐，需要 Docker / Python 环境？不想学 Linux，
一条串口就可以完成所有配置；通过串口 CLI 或 OTA 更新即插即用，无需任何操作程序或解释器。对于技术爱好者，只要烧录固件，就能立即得到一个全功能 AI 助手。
资源受限导致卡顿或无法完成复杂任务。
MiniClaw 使用双核分工。Core 1 专注 LLM 推理，Core 0 专注 I/O；每次推理耗时仅数十毫秒，话说回来，工具调用采用一次性缓冲，不使用流式解析。以降低 SRAM 占用并保证实时性。
Tool 程序采用声明‑注册‑派发三步走。新增一个工具只需编写 C 文件并在 CMakeLists.txt 注册，无需改动主循环或 LLM 层。支持通过文件程序动态加载新技能，实现零代码热更新。
< l i class=“painpoint-item”>
项目提供完整 Markdown 文档、示例技能文件还有 API 调试工具；代码风格统一且极简，可快速阅读和修改。通过 Serial CLI 可实时看日志和调试状态，大大降低学习成本。
MimiClaw 是一款运行在 ESP32‑S3 上的纯 C AI 助手。它不依赖 Linux，也不需要 Node.js 或 Python，仅使用 FreeRTOS 与 ESP‑IDF 完成所有功能。
至于关键优势。
零服务器 ——所有模型推理由小型芯片完成，只需局域网 WiFi 通信。
极致低内存 ——启动时占用不到 100 KB RAM，仅使用 8 MB PSRAM 存储模型权重和缓存。其实，
双模 AI ——可即时切换 Anthropic Claude 或 OpenAI GPT 提供商。无需重新编译，
本地持久化记忆 ——SPIFFS 存储会话历史、长期记忆及每日笔记，即使重启也不会丢失。
ReAct Agent 循环 ——自主调用工具完成任务，并实时反馈给使用者。
定时任务 —AI 可创建 cron 表，在指定时间自动执行动作或发送提醒。
MimiClaw 主要特色
特色描述
详细说明 & 使用者收益
🔥 极简设计
- 开销低于 100 KB RAM
- 编译后体积小，便于 OTA 更新
- 易于维护和二次开发，适合 DIY 爱好者与嵌入式工程师
🏁 双模 AI
- 根据网络环境或成本需求随时切换
- 避免单一供应商限制。提高可靠性
📬 本地记忆
- 所有对话记录永久保存在设备上，无隐私泄漏风险
- 重启后自动恢复上下文，让助手更像长期伙伴
🔀 ReAct Agent 循环推理模式
- LLM 不再是单向输出，而是能主动执行动作
- 完成复杂多步任务的能力，在资源受限设备上更加智能交互
⏵ 定时任务
- AI 可自行安排提醒、执行脚本等，为使用者提供 “随叫随到” 功能
🔔 主动心跳检测 & 自动恢复状态
- 实时监测待办事项文件，一旦发现变化立即触发相应行动；减少人工检查负担，
MimiClaw 主要定位
MimiClaw 的使命是为技术爱好者提供一种 **极致轻量且完全私有化的嵌入式 AI Agent 网站**。它不是替代云端服务，而是为预算有限但重视隐私的人群创造一种全新的低成本 AI 助手体验。
*全球首个 $5 芯片级 AI 助手* —— 在仅 $5 的 ESP32‑S3 上运行完整 Agent。实现成本革命与技术进展，同时填补行业市场空白。
*极简却完整* —— 拥有 ReAct 循环、工具调用、持久化记忆、自主行为等主要能力。同时保持代码量精简，可直接插电即用，无服务器需求。
使用场景
*个人助理* — Telegram 提供天气查询、定时提醒等日常协助。
*智能家居控制* — GPIO 工具实现灯光、电机等硬件控制。老实说，
更多实验网站
*边缘 AI 实验网站* — 为嵌入式研究者提供可
框架。支持快速集成新传感器/执行器。
MimiClaw 是一次 “纯 C 在 MCU 上重现完整 Agent 栈”的工程实践。它刻意抛弃了云端/操作程序/解释器三层间接性，以达到美元级别的成本、使用较稳定及永不离线的目标。
主要设计哲学
*裸金属 + FreeRTOS* — 所有逻辑直接跑在 ESP-IDF 上。没有 GC 或解释器，从而保证启动即 AGENT 而非等待环境准备。说起来，
• *薄通道 + 厚Agent* — 网络通道仅做数据转发。全部业务逻辑集中在统一 Agent Loop 中，以降低延迟并提高鲁棒性。
• *资源敏感* — 内部 SRAM 用作栈 / WiFi/TLS 控制块，大缓冲均走 PSRAM；双核分工避免 I/O 阻塞推理过程。
• *两层配置* — 编译期默认值 + 串口 CLI 覆盖。使得使用者可以在 USB 接口即可调整设置，而无需重新编译。
MiniClaw 工作原理与架构细节
总体架构图说明 – 小型芯片中的“大脑+身体”组合
Pseudo 图示展示了 Core 0 与 Core 1 的职责划分，还有外部通信模块如何将消息传递给 Agent 循环：
┌─────────────────────┐
│ Core‑1 │ ────► Agent Loop ───► Tool System ───► GPIO / File Ops
│ └─────────────────────┘ ▲ ▲
│ │ │ │
│ ▼ │ ▼
│ Core‑0 ────► TeleBot/WebSocket ➜ │ |
└─────────────────────┘ │ |
| |
└────────▼────── Web Search / Cloud APIs
数据流细节
步骤
操作
描述
1️⃣ 接收消息 Telegram Bot 长轮询
收到来自使用者的文本指令
2️⃣ 入队列 FreeRTOS xQueue
将消息包装为 mimi_msg_t 并放入 inbound 队列
3️⃣ 消息处理 agent_loop- 加载历史会话 - 建立 system prompt - 调用 LLM API 并解析返回
4️⃣ 工具调用 tool_registry_dispatch当 LLM 输出 tool_use 块时根据名称找到对应实现并执行
5️⃣ 保存结果 SPIFFS 写回 session/history - 写入 MEMORY.md 等
保留对话记录与长期记忆
6️⃣ 返回回复 outbound dispatch
根据 channel 字段发送 Telegram 消息或 WebSocket 帧
启动序列流程图
appmain
├ init nvs
├ initspiffs
├ message businit
├ memory storeinit
├ session mgrinit
├ wifi managerinit
├ http proxyinit # 加载代理配置
├ telegram botinit # 加载 Bot token
├ llm proxyinit # 加载 API key / 模型选择
├ tool registryinit # 注册所有 Tool JSON schema 和 handler
├ agent loopinit
├ serial cli_init # 开启 REPL 接口。可无 WiFi 调试
└─ wifimanager start # 建立 WiFi 连续连接
├─ wifimanager waitconnected
├ if success:
telegram botstart # 开始 Telegram long polling task on Core‑1
agent loopstart # 启动 Agent Loop on Core‑1
ws serverstart # 启动 WebSocket Server on Core‑1?outbound dispatch_task # 响应队列调度 on Core‑1?
硬件资源约束 & 对策
ESP32‑S3 简明规格表<\/th>
Cores:LXtensa LX7 @ ~160 MHz，每个 core 独立运行；老实说，PSRAM8 MB 用于大缓冲；SRAM512 KB 用作栈/控制块；Flash16 MB 存放模型权重。<\/b>
<\/tbody><\/table>
说到关键约束，
模型大小 ≤ 2 MB : 必须使用量化模型。如 q8_8 quantized GPT-NeoX 等.
推理时间 ≤ 数十 ms : 避免长循环阻塞主线程.
中间激活 ≤ ~800 KB : PSRAM 必须足够容纳激活缓存.
与原生 OpenClaw 的区别
架构类型<\/th> MiniClaw
OpenClaw
资源使用情况<\/th> MiniClaw
<\/i>
OpenClow
<\/ td\>
\end{table}...
---
## 程序提示词与 Skill 创造机制
为了让 LLM 更准确、 JSON schema 与 handler。\t\t\t — 在 main/CMakeLists.txt 添加源文件。\t\t\t — 在 tool_registry.c 注册。\t — 重启即可生效，topically:
c
// toolgpio.c example skeleton
tool t toolgpio = {
.name=\"gpio read\"。.schema={...},.handler=&toolgpio read,};老实说，toolregistry register;不过，and same for new skills stored under /spiffs/sessions/.md . \t\t此方法无缝接入现有 ReAct 循环。vital note : all persistent state lives in SPIFFS paths . Use Serial CLI commands to inspect or modify.
actionable.\t---"
