AI Hub Icon
AIBit 发现开源项目
首页 / 实用开源项目

zclaw – ESP32 用 888 KiB AI 个人助理（C/C++）

February 27, 2026
类别: 实用开源项目
标签:
Open Source AI Assistant ESP32 Embedded C Microcontroller

介绍

zclaw 是一款极其轻量、全固件的 AI 个人助理，专门为 ESP32 系列微控制器设计，尺寸严格限制在 888 KiB 之内。该项目用纯 C 语言编写，借助 ESP‑IDF 与 FreeRTOS，使其能够轻松闪存到任何 ESP32‑C3、ESP32‑S3 或 ESP32‑C6 开发板上。

为什么选择 zclaw？

传统的设备端 LLM 解决方案往往需要数 GB RAM 或外接 GPU。zclaw 通过以下方式规避这些限制： * 提供小巧的单一功能 LLM 后端（Ollama、OpenAI、Anthropic 等） * 采用紧凑的调度与 GPIO API，支持简易的 “cron 类” 任务 * 使用 ESP‑NVS 存储所有凭证与配置，可选 AES 加密 * 提供 Telegram 聊天界面以及轻量级 Web 代理，让浏览器也能访问

其结果是一款完全离线且仅占 850 KiB flash 的边缘 AI，可实时响应自然语言查询。

主要特性

功能 描述
占用极小 默认构建 858 KiB，使用安全配置可降至 ≤ 888 KiB
调度 支持日常、周期性和一次性任务，并具备时区感知
GPIO 控制 读/写操作受限，支持批量 gpio_read_all()
持久状态 快速 I/O 到 NVS，关机后数据保持
自定义工具 注册自己的 C 函数作为 LLM 插件
安全模式 Flash 加密凭证使用 AES‑256
聊天渠道 Telegram 机器人 + 可选 Web 代理 UI
LLM 后端 Anthropic、OpenAI、OpenRouter、Ollama 或自定义端点
CLI 脚本 启动、安装、配置、闪存、监控及基准测试

先决条件

  1. ESP‑IDF – 按官方指南安装最新 SDK。
  2. Git – 克隆代码仓。
  3. Python 3.8+ – 用于配置与测试脚本。
  4. Telegram Bot Token – （可选，聊天使用）或 HTTP LLM 接口。
  5. Wi‑Fi 凭证 – 网络信息以启动设备。

一行脚本快速上手

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)
该脚本将完成： * 克隆或拉取最新 zclaw 源码。
* 运行非交互式 install.sh，编译固件。
* 将构建产物闪存到指定板子。
* 配置 Wi‑Fi 与 LLM 凭证。

若已有本地克隆，只需运行 ./install.sh 或 ./install.sh -y 进行演示。

闪存与安全配置

安全模式利用 ESP‑NVS 加密，保护 API 密钥和 Wi‑Fi 密码。

# 使用加密闪存并设置简易口令
./scripts/flash-secure.sh
闪存后执行 ./scripts/provision.sh。脚本会提示输入： * Wi‑Fi SSID / 密码
* LLM 提供商名称（如 ollama、openai）
* 端点和 API key
* 可选 Telegram bot token 与 chat ID

所有值会以哈希形式存入 flash。--flash-mode secure 标志保证后续升级仍保守加密。

运行聊天服务

设备配置完成后，闪存到 Wi‑Fi 并等待聊天连接。

  • Telegram – 机器人自动转发接收的消息并返回回复。
  • Web 代理 – 在宿主机运行 ./scripts/web-relay.sh。它会开启一个短时间 HTTPS 端点，ESP32 将连接至之。打开给定 URL，即可在浏览器中实时聊天。

两种接口均实时直播 LLM 输出，体验近乎原生。

调度任务

zclaw 的调度器类似轻量级 cron。

int main() {
    scheduler_register("");
    // 每日 3 AM 发送一次 ping
    scheduler_schedule("3 * * * *", "ping_device");
}
JSON 格式的 cron 语法具备时区感知，可触发任何已注册的 zclaw 工具或自定义 C 函数。

GPIO 与持久化

GPIO API 受保护：每次写操作可限制在指定的引脚范围内，gpio_read_all() 会返回连续位图。

持久内存通过 NVS 简单键值 API 暴露：

nvs_set("user_pref", 42);
int val = nvs_get("user_pref");
可用于存储用户资料、上一次提示时间或自定义应用状态。

用自定义工具扩展 zclaw

zclaw 自带一个小型插件系统。添加新工具的步骤： 1. 编写符合 zclaw_tool_t 签名的 C 函数。
2. 编辑 main/config.h 注册工具。
3. 用 ./scripts/build.sh 重新编译。

新工具可在聊天界面通过在提示前加 tool: YourToolName 调用。

开发工作流程

典型开发循环：

./scripts/test.sh host          # 验证宿主机测试
./scripts/build.sh              # 编译固件
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --write-template  # 配置本地开发配置
./scripts/monitor.sh /dev/cu.usbmodem1101
仓库包含完整 CI 流水线，位于 .github/workflows/，能自动构建、测试并验证每一次提交。

贡献

欢迎所有贡献！ * Fork、创建功能或缺陷修复分支。
* 确保本地测试通过。
* 新增 PR 并关联对应 issue。
* 许可证为 MIT – 查看 LICENSE 即可确认。

如发现安全漏洞，请直接联系维护者或使用 GitHub 安全报告功能。

许可证与致谢

zclaw 采用 MIT 许可证发布。代码为开源社区共同努力的结晶。特别感谢 ESP‑IDF 团队、FreeRTOS 贡献者以及所有在真实硬件上测试的人。

欲了解更多信息，请访问官方文档 https://zclaw.dev 或 GitHub 仓库。

原创文章: 查看原文

分享本文