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

设置说明

• bootstrap.sh 会克隆/更新仓库，然后运行 ./install.sh。您可以先检查/验证引导流程（包括 ZCLAW_BOOTSTRAP_SHA256 完整性校验）；详情请参阅入门文档。
• 在运行 install.sh 时，Linux 依赖项安装会自动检测 apt-get、pacman、dnf 或 zypper。
• 在非交互模式下，未回答的安装提示会默认为“否”，除非您传递 -y 参数（或已保存偏好设置/显式标志生效）。
• 对于闪存中的加密凭据，请使用安全模式（在安装流程中使用 --flash-mode secure，或直接运行 ./scripts/flash-secure.sh）。
• 烧录完成后，使用 ./scripts/provision.sh 配置 Wi‑Fi 和 LLM 凭据。
• 您可以随时重新运行 ./scripts/provision.sh 或 ./scripts/provision-dev.sh（无需重新烧录），以更新运行时凭据：Wi‑Fi SSID/密码、LLM 后端/模型/API 密钥（或 Ollama API 地址），以及 Telegram 令牌和聊天 ID 白名单。
• 默认的 LLM 速率限制为每小时 100 次、每天 1000 次；编译时限制可在 main/config.h 中修改（RATELIMIT_*）。
• 快速验证方法：运行 ./scripts/web-relay.sh 并发送一条测试消息，确认设备能够响应。
• 如果串口被占用，运行 ./scripts/release-port.sh 后重试。
• 如需重复本地重新配置而不必再次输入密钥，可使用带有本地配置文件的 ./scripts/provision-dev.sh（provision-dev.sh 实际上是 provision.sh --yes 的封装）。

核心特性

• 通过 Telegram 或托管 Web 中继进行对话
• 带有时区感知的计划任务（每日、周期性和一次性）
• 内置与用户自定义工具
• 如需新增内置功能，可通过“打造属于你的工具”文档添加固件工具（C 处理程序 + 注册表条目）。
• 运行时诊断功能，可通过 get_diagnostics 获取快速/运行时/内存/速率/时间/全部范围的信息。
• GPIO、DHT 和 I2C 控制，并配有保护机制（包括 gpio_read_all、i2c_scan、i2c_read/i2c_write 以及 dht_read）。
• USB 本地管理控制台，用于恢复、安全模式及网络启动前的操作。
• 重启后仍能保持数据持久化。
• 多种角色选项：中立、友好、技术型、机智。
• 支持 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
# 编辑 ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# 如果 Telegram 不断重复旧消息：
./scripts/telegram-clear-backlog.sh --show-config

更多详细信息请参阅本地开发与调试指南。

其他实用脚本

显示脚本

• ./scripts/flash-secure.sh - 加密烧录
• ./scripts/provision.sh - 将凭据写入 NVS
• ./scripts/provision-dev.sh - 本地配置文件封装，便于重复配置
• ./scripts/telegram-clear-backlog.sh - 清除积压的 Telegram 消息
• ./scripts/erase.sh - 只擦除 NVS（--nvs）或完全擦除闪存（--all），并附带保护措施
• ./scripts/monitor.sh - 串口监视器
• ./scripts/emulate.sh - 运行 QEMU 模拟器
• ./scripts/web-relay.sh - 托管中继服务 + 移动聊天界面
• ./scripts/benchmark.sh - 测量中继/串口延迟
• ./scripts/test.sh - 运行主机/设备测试流程
• ./scripts/test-api.sh - 手动/本地测试实时提供商 API

本地管理控制台

当开发板处于安全模式、未配置或 LLM 路径不可用时，您仍然可以通过 USB 串口对其进行操作，而无需 Wi‑Fi 或 LLM 交互。

./scripts/monitor.sh /dev/cu.usbmodem1101
# 然后输入：
/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 的镜像字节数）：

段落	字节数	大小	占比
zclaw 应用逻辑 (libmain.a)	39276	~38.4 KiB	~4.6%
Wi‑Fi + 网络栈	378624	~369.8 KiB	~44.4%
TLS/加密栈	134923	~131.8 KiB	~15.8%
证书包 + 应用元数据	98425	~96.1 KiB	~11.5%
其他 ESP-IDF/运行时/驱动程序/libc	201786	~197.1 KiB	~23.7%

本次构建的镜像总大小为 853034 字节；填充后的 zclaw.bin 为 853184 字节（约 833.2 KiB），距离 888 KiB 的上限还剩 56128 字节（约 54.8 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

zclaw 快速上手指南

zclaw 是一款专为 ESP32 系列芯片打造的超轻量级 AI 个人助理固件。它完全使用 C 语言编写，默认构建的固件总大小严格控制在 888 KiB 以内（包含运行时、Wi-Fi、TLS 加密等所有组件），支持通过自然语言控制 GPIO、执行定时任务及调用自定义工具。

环境准备

系统要求

• 操作系统：macOS 或 Linux（Windows 用户建议使用 WSL2）。
• 硬件目标：ESP32, ESP32-C3, ESP32-S3, ESP32-C6。
  • 推荐开发板：Seeed Studio XIAO ESP32-C3。

前置依赖

安装脚本会自动检测并安装以下依赖（需具备 sudo 权限）：

• Git
• Python 3
• ESP-IDF 工具链（脚本会自动克隆和配置）
• 包管理器（自动识别 apt-get, pacman, dnf, 或 zypper）

注意：国内开发者若遇到 GitHub 克隆缓慢的问题，建议自行配置 Git 加速代理或在网络环境较好的时段运行安装脚本。

安装步骤

方式一：一键引导安装（推荐）

适用于未下载代码的用户。该脚本会自动克隆仓库、更新子模块并执行安装。

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

方式二：本地安装

如果你已经克隆了仓库：

./install.sh

如需非交互式安装（自动确认所有提示）：

./install.sh -y

配置凭证

安装完成后，需要配置 Wi-Fi 和大模型（LLM）凭证。运行以下脚本：

./scripts/provision.sh

按提示输入 Wi-Fi SSID/密码、LLM 提供商（OpenAI/Anthropic/Ollama 等）、API Key 以及 Telegram Token（如使用 Telegram 控制）。

提示：对于本地重复开发调试，可使用 ./scripts/provision-dev.sh 配合本地配置文件，避免重复输入敏感信息。

基本使用

1. 编译与烧录

配置完成后，构建并烧录固件到开发板（请替换 /dev/cu.usbmodem1101 为你的实际串口设备路径）：

./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101

2. 验证连接

启动 Web 中继服务进行测试，或通过串口监视器查看日志：

# 启动 Web 中继（提供简单的网页聊天界面）
./scripts/web-relay.sh

# 或者直接使用串口监视器
./scripts/monitor.sh /dev/cu.usbmodem1101

3. 本地管理控制台（无需联网）

即使在没有 Wi-Fi 或未配置 LLM 的情况下，你也可以通过 USB 串口直接使用本地命令控制设备。在串口监视器中输入以下命令：

/wifi status       # 查看 Wi-Fi 状态
/wifi scan         # 扫描周围 Wi-Fi
/gpio all          # 读取所有 GPIO 状态
/gpio 5 high       # 将 GPIO 5 设置为高电平
/bootcount         # 查看启动次数
/reboot            # 重启设备

4. 开始对话

一旦设备连接 Wi-Fi 并完成凭证配置：

• Telegram 用户：直接向绑定的 Bot 发送消息，设备将通过自然语言回复并执行操作。
• Web 用户：访问 web-relay.sh 输出的本地地址进行对话。

示例对话内容：

"每天上午 8 点打开 GPIO 4" "读取当前的温度湿度传感器数据" "扫描 I2C 总线上的设备"

现在，你已经成功运行了世界上最小的 AI 个人助理之一！更多高级功能（如自定义工具开发、安全模式等）请参阅 官方文档。