zclaw安全与运维指南Flash加密、安全模式、工厂重置与速率限制完整防护【免费下载链接】zclawYour personal AI assistant at all-in 888KiB (~35KB in app code). Running on an ESP32. GPIO, cron, custom tools, memory, and more.项目地址: https://gitcode.com/gh_mirrors/zc/zclawzclaw 是运行在 ESP32 上的超小型 AI 个人助理固件总体积仅约 888 KiB。当它 7×24 小时挂在家中联网工作时安全与运维是必须认真对待的问题Flash 加密保护 API 密钥、安全模式防启动死循环、工厂重置快速恢复出厂、速率限制控制 API 开销。本文带你完整掌握 zclaw 的四层防护体系。内建安全默认值开箱即用的 5 道防线 ️zclaw 的设计哲学是最安全的部署路径应该是显式且可重复的。出厂固件已默认启用以下防护无需任何额外配置防护机制作用源码位置速率限制限制 LLM 请求频率控制 API 花费main/ratelimit.cTelegram 白名单只接受已配置的 chat ID 发来的消息main/telegram_chat_ids.c配置门禁未完成凭证配置前不进入正常运行main/local_admin.c启动循环守卫连续启动失败后自动进入安全模式main/boot_guard.c敏感键识别自动识别密码/Token 类配置键main/security.c#L10-L30Flash 加密4 步保护 Flash 中的 API 密钥 zclaw 的 WiFi 密码、LLM API Key、Telegram Token 都存放在 Flash 的 NVS 分区中。如果设备丢失未加密的 Flash 可以被直接读出。zclaw 提供一键加密脚本 scripts/flash-secure.sh自动完成以下 4 步生成加密密钥为设备生成唯一的 XTS-AES-128 密钥按 MAC 地址保存到keys/目录安全构建使用 sdkconfig.secure 安全配置重新编译固件烧写密钥到 eFuse将密钥永久烧入芯片硬件熔丝加密烧录固件使用encrypted-flash目标写入加密固件⚠️重要提醒Flash 加密是永久性操作一旦启用就再也无法烧录未加密固件。生成的密钥文件务必备份——没有它USB 重新烧录将完全失效。两种模式按需选择开发模式默认密钥保持可读方便日常 USB 重刷迭代生产模式--production密钥附加硬件读保护适合物理接触风险较高的部署场景./scripts/flash-secure.sh # 开发模式 ./scripts/flash-secure.sh --production # 生产模式烧录完成后用 scripts/provision.sh 写入凭证设备即进入加密保护状态。安全模式启动死循环时的自动逃生舱 坏固件、坏配置都可能让设备陷入启动 → 崩溃 → 再启动的死循环。zclaw 的启动守卫机制会在 main/main.c#L149-L167 中持续计数每次启动递增持久化的启动计数器main/boot_guard.c#L31-L45连续失败达到4 次MAX_BOOT_FAILURES见 main/config.h#L190即自动进入安全模式安全模式下设备停止轮询 Telegram、停止调用 LLM只保留 USB 串口管理通道启动成功后稳定运行30 秒计数器自动清零好消息是安全模式不是砖机状态。插上 USB 线通过本地管理控制台即可诊断和恢复./scripts/monitor.sh /dev/cu.usbmodem1101 # 然后输入 /bootcount # 查看启动计数与距离安全模式还差几次 /wifi scan # 扫描周边 WiFi /reboot # 重启设备工厂重置3 种恢复出厂方法 设备配置混乱、凭证需要更换时zclaw 提供三条恢复出厂路径全部会清空 WiFi 凭证、Token、计划任务、记忆数据和启动状态方法一硬件按键默认 GPIO9启动时按住 BOOT 按键默认 GPIO9低电平5 秒以上固件会自动擦除 NVS 并重启。引脚和按住时长可在 main/config.h#L160-L170 中按板子接线调整核心逻辑在 main/main.c#L66-L95。方法二串口命令两步确认防误触/factory-reset # 第一步显示将要擦除的内容 /factory-reset confirm # 第二步确认后擦除 NVS 并重启两步确认设计main/local_admin.c#L510-L536确保任何一条误发的消息都不会直接清空设备。方法三宿主机脚本带护栏./scripts/erase.sh --nvs # 仅擦除凭证/配置保留固件 ./scripts/erase.sh --all # 整片 Flash 擦除需交互输入 ERASE ALL 确认scripts/erase.sh 对全片擦除强制要求交互确认非交互模式必须显式传--yes避免自动化脚本误删。速率限制如何防止 API 账单失控 AI 助理联网运行最大的隐性成本是 LLM API 调用。zclaw 内置滑动窗口限速器main/ratelimit.c#L107-L134在每次 LLM 请求前检查两个阈值限制维度默认值说明每小时上限100 次防止短时突发刷量每天上限1000 次控制日级总开销关键设计细节小时窗口在整点自动重置日窗口在跨天时自动清零并持久化日计数通过 NVS 持久保存NVS_KEY_RL_DAILY重启不会清零防刷量无法靠拔电绕过触发限制时设备会明确回复Rate limited: 100/100 requests this hour而非静默失败阈值是编译期配置修改 main/config.h#L196-L198 中的RATELIMIT_MAX_PER_HOUR/RATELIMIT_MAX_PER_DAY后重新编译即可配合 Telegram chat ID 白名单和 Web 中继的ZCLAW_WEB_API_KEY访问密钥zclaw 从入口到调用全链路都有访问控制。设备丢失应急处置清单 万一设备丢失且当时未开启 Flash 加密请立刻按顺序执行假设 API 密钥已泄露——未加密设备上的 NVS 可被直接读取到 LLM 服务商控制台轮换 API Key通过BotFather吊销并重建 Telegram Bot Token轮换 Web 中继的ZCLAW_WEB_API_KEY如果设备开启了 Flash 加密则 Flash 内容对没有密钥文件的人是一堆乱码上述风险大幅降低——这正是 scripts/flash-secure.sh 的价值所在。写在最后zclaw 用不到 40 KiB 的应用代码在 888 KiB 的总固件预算里塞下了一整套面向真实部署的安全体系Flash 加密守住静态密钥安全模式兜住坏固件工厂重置提供恢复路径速率限制锁住 API 开销。四层防护环环相扣让你可以放心把这枚 ESP32 小助手长期挂在家中。更多细节可参考文档站的安全章节 docs-site/security.html 与本地管理控制台 docs-site/local-admin.html。【免费下载链接】zclawYour personal AI assistant at all-in 888KiB (~35KB in app code). Running on an ESP32. GPIO, cron, custom tools, memory, and more.项目地址: https://gitcode.com/gh_mirrors/zc/zclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
