zclaw自定义工具开发指南两种方法为ESP32 AI助手编写专属C语言工具【免费下载链接】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 助手整套固件仅 888KiB。作为 ESP32 AI 助手它内置了 GPIO 控制、定时任务、持久记忆等工具而通过 zclaw 自定义工具开发你还能用两种方法为它编写专属工具一是无需重新烧录的运行时用户工具二是用 C 语言编写 Handler 的固件级工具。本指南带你从原理到实操完成第一次 ESP32 工具开发。为什么需要 zclaw 自定义工具zclaw 的工作方式是你用自然语言Telegram 或 Web Relay发出指令模型理解意图后调用工具Tool来执行——写 GPIO、读写记忆、创建定时任务。内置工具清单集中在 main/builtin_tools.def覆盖 GPIO、I2C、DHT 传感器、Memory、Cron 调度等能力。但当你想实现一键浇花夜间关机流程这类组合动作或接入全新的硬件能力时就需要开发专属工具。zclaw 为此提供了两条开发路径方法适合场景成本运行时用户工具create_tool用现有内置工具拼出的快捷动作不改代码、不烧录固件工具C 语言 Handler全新硬件能力、严格参数校验改代码 测试 重新烧录方法一运行时用户工具免代码、免烧录原理用自然语言组装内置工具运行时用户工具的本质是一条动作指令文本。当你用自然语言让助手创建工具时固件会调用create_tool把它持久化到 NVS 存储中之后模型每次调用这个工具固件就返回动作文本模型再自行拆解为内置工具调用去执行。整个流程你说创建一个工具 xxxcreate_tool将 名称 描述 动作 存入 NVS持久化重启不丢模型按名称调用该工具固件返回动作文本模型执行对应的 gpio/memory/cron 调用注意这不涉及任何动态代码加载而是通过可提示的意图来塑造行为安全且零烧录。相关源码main/user_tools.c 负责 NVS 读写与校验main/agent.c 负责在工具执行时把动作文本交回模型。一键创建步骤直接在对话中创建例如你创建一个工具叫 water_plants。 描述给A区植物浇水。 动作将 GPIO 5 置高等待 30000 毫秒再将 GPIO 5 置低。 你运行 water_plants 助手调用工具→ 执行 gpio_write delay gpio_write写完后立即用测试提示词调用一次如果模型走偏了调整动作措辞即可。命名与容量约定写工具前必看字段规则说明name仅字母、数字、下划线最长 24 字符不能与内置工具重名description简短明确模型靠它决定何时调用action具体、祈使语气应能清晰映射到内置工具最长 256 字符容量上限最多 8 个用户工具用完记得用delete_user_tool清理这些限制在 main/config.h 中定义固件创建时会逐一校验非法命名、重名、超量都会被拒绝并给出日志。让记忆驱动工具创建先让 zclaw 记住硬件接线再创建工具效果最佳你记住 GPIO 5 控制办公室灯光。 助手已存入记忆键如 u_office_lighting_pin5 之后 你创建一个控制灯光的工具。 助手直接复用已记住的引脚创建工具模式总结先用记忆教一次接线再用自然语言创建高层工具。方法二固件工具C 语言 Handler 烧录当你需要的行为不是现有工具的简单组合时新 I/O 路径、严格 JSON Schema、确定性校验、特殊错误处理就该走固件路线。工具 Handler 的标准签名所有固件工具都是一个统一的 C 函数定义在 main/tools.htypedef bool (*tool_execute_fn)(const cJSON *input, char *result, size_t result_len);input模型传入的 JSON 参数result写回给模型的文本结果返回true表示执行成功一个最小 Handler 示例以新增relay_status工具为例// main/tools_relay.c bool tools_relay_status_handler(const cJSON *input, char *result, size_t result_len) { (void)input; snprintf(result, result_len, Relay status: healthy); return true; }固件工具开发五步流程实现 Handler在main/tools_*.c中新建函数新建文件需将其加入 main/CMakeLists.txt 的SRCS列表若扩展现有文件则跳过此步声明原型在 main/tools_handlers.h 中添加函数声明注册工具在 main/builtin_tools.def 添加一行注册项TOOL_ENTRY(relay_status, Get relay health from host web relay., {\type\:\object\,\properties\:{}}, tools_relay_status_handler)补充主机端测试在 test/host/ 下为输入校验与输出格式添加用例构建、烧录、验证./scripts/test.sh host ./scripts/build.sh ./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101 ./scripts/monitor.sh /dev/cu.usbmodem1101提示注册表集中管理在main/builtin_tools.def所以写完 Handler 后新增一个工具通常只需一行注册代码。请把name、description和 JSON Schema 当作面向模型的 API 契约——刻意修改并保持测试同步。两种方法怎么选能用内置工具表达GPIO 动作 延时 记忆组合→ 用方法一五分钟搞定随时可改需要新硬件能力、严格参数校验、固件级保证如新传感器驱动、时序敏感操作→ 用方法二经验法则用户工具适合宏命令固件工具适合新能力工具设计自查清单✅ 动作文本是否只引用已支持的内置能力✅ 时长是否明确写成毫秒/分钟避免稍后这类模糊词✅ 结果是否可通过gpio_read、memory_get、cron_list观察验证✅ 避免过大的多领域宏——拆成更小的工具更可靠✅ 工具名避免语义重叠否则模型选择会混乱工具版本管理把工具名当 API 契约行为发生不兼容变化时新起一个名字如_v2后缀并迁移调用方旧工具用delete_user_tool清理。用list_user_tools可随时查看当前全部用户工具。延伸阅读完整开发文档本地版docs-site/build-your-own-tool.html内置工具注册表main/builtin_tools.def用户工具存储与校验main/user_tools.c工具注册与执行核心main/tools.c本地开发工作流docs-site/local-dev.html主机端测试目录test/host/从零到能用的第一个 zclaw 专属工具方法一甚至不需要写一行代码而方法二的 C Handler 体系也让 ESP32 固件级工具开发变得有章可循。现在就给你的 ESP32 AI 助手添一件新武器吧。【免费下载链接】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），仅供参考