zclaw

适用于 ESP32 的最小 AI 个人助手。

zclaw 使用 C 语言编写，运行在 ESP32 开发板上，默认构建的固件总大小严格限制在 <= 888 KiB。它支持定时任务、GPIO 控制、持久化内存以及通过自然语言组合自定义工具。

888 KiB 上限是固件总大小，不仅仅是应用代码。它包括 zclaw 逻辑以及 ESP-IDF/FreeRTOS 运行时、Wi-Fi/网络、TLS/加密和证书包开销。

使用有趣，破解也有趣。

完整文档

使用文档站点获取完整指南和参考。

• 完整文档
• 本地管理控制台
• 使用场景：有用 + 有趣
• 变更日志（网页版）
• 完整 README（原文）

快速开始

一行脚本引导 (macOS/Linux)：

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

已经克隆了？

./install.sh

非交互式安装：

./install.sh -y

亮点

• 通过 Telegram 或托管 Web 中继聊天
• 时区感知的调度（daily、periodic 和一次性 once）
• 内置 + 用户自定义工具
• 对于全新内置功能，通过“构建你自己的工具”文档添加固件工具（C 处理器 + 注册表条目）。
• 通过 get_diagnostics 运行时诊断（快速/运行时/内存/速率/时间/所有范围）
• GPIO、DHT 和 I2C 控制并带有保护措施（包括 gpio_read_all、i2c_scan、i2c_read/i2c_write 和 dht_read）
• USB 本地管理控制台，用于恢复、安全模式和预网络启动
• 跨重启的持久化内存
• 角色选项：neutral、friendly、technical、witty
• 提供商支持 Anthropic、OpenAI、OpenRouter 和 Ollama（自定义端点）

硬件

已测试目标：ESP32、ESP32-C3、ESP32-S3 和 ESP32-C6。

支持经典的 ESP32-WROOM/ESP32 DevKit 开发板。

非常欢迎提供其他 ESP32 变体的测试报告！

推荐入门板：Seeed XIAO ESP32-C3

本地开发与破解

典型快速循环：

./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101

配置文件设置一次，然后重复使用：

./scripts/provision-dev.sh --write-template
# edit ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# if Telegram keeps replaying stale updates:
./scripts/telegram-clear-backlog.sh --show-config

更多详情请见本地开发与破解指南。

其他实用脚本

本地管理控制台

当开发板处于安全模式、未配置或 LLM 路径不可用时，您仍然可以通过 USB 串口操作它，无需 Wi-Fi 或 LLM 往返。

./scripts/monitor.sh /dev/cu.usbmodem1101
# then type:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

可用的本地命令：

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm（破坏性操作；清除 NVS 并重启）

完整参考：本地管理控制台

大小分布

当前默认 esp32 分布（来自 idf.py -B build size-components 的分组镜像字节）：

此构建的镜像总大小为 853034 字节；填充后的 zclaw.bin 为 853184 字节（约 833.2 KiB），剩余 56128 字节（约 54.8 KiB）在 888 KiB 限制内。

延迟基准测试

中继路径基准测试（包括 Web 中继处理 + 设备往返）：

./scripts/benchmark.sh --mode relay --count 20 --message "ping"

直接串口基准测试（主机往返 + 首次响应时间）。如果固件记录 METRIC request ... 行，报告还将包括设备端时序：

./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --count 20 --message "ping"

许可证

MIT