ESP-Claw | 面向物联网设备的 AI Agent 框架

以前我们给 IoT 设备写逻辑，是“人先想好规则，设备照着执行”。ESP-Claw 想试另一条路：你用聊天告诉设备要做什么，它自己把感知、判断和执行串起来。

https://github.com/espressif/esp-claw

如果你折腾过 ESP32，大概率写过这样的代码：按键按下，点亮 LED；温度超过阈值，蜂鸣器响；串口收到命令，执行某个动作。

这套方式很可靠，也很工程化，但有个问题：设备只会做你提前写好的事。

ESP-Claw 的想法不太一样。

它把一个 Agent Runtime 放到乐鑫芯片上，让 ESP32 不只是“接收命令的执行器”，而是变成一个能接消息、能记忆、能调用工具、能跑 Lua 脚本、还能联动硬件的小型边缘智能体。

这就是它最有意思的地方。

这是什么项目？

ESP-Claw 是乐鑫推出的面向物联网设备的 AI Agent 框架。项目主应用在 application/edge_agent，底层用 ESP-IDF 和 C 实现，运行在 ESP32 系列芯片上。

它不是单纯给 ESP32 接一个大模型 API，然后把回复打印出来。项目里真正值得看的部分，是它把设备侧 Agent 拆成了几层：

claw_core：负责 Agent Loop、上下文组装和工具调用。

claw_capabilities：把文件、Lua、IM、MCP、调度器、搜索、系统信息等能力封装成工具。

claw_memory：管理会话历史和长期记忆。

claw_skill：让设备上的 Agent 按需加载 Markdown 形式的技能说明。

lua_modules：把 GPIO、I2C、ADC、屏幕、摄像头、音频、按键、灯带等硬件能力暴露给 Lua。

换句话说，它在一块小板子上搭了一个“会聊天、会调工具、会写脚本、会记事”的设备运行时。

它解决的痛点，不只是“远程控制”

传统 IoT 最常见的路径是：设备连云，云端下发指令，设备执行。

这个模式没问题，但体验上很容易变成“高级遥控器”。你可以打开灯、查询状态、修改配置，但如果想让设备做一件稍微复杂点的事，通常还是要回到代码、规则、固件升级。

ESP-Claw 想解决的是这个中间断层。

比如你对设备说：

“每天早上 7 点提醒我喝水。”

在普通设备里，这意味着你要有配置界面、定时任务逻辑、提醒动作和存储逻辑。ESP-Claw 里则是另一套思路：消息先进入 Event Router，Agent 判断意图，再通过调度器、Lua 或 IM 能力完成后续动作。

再比如你说：

“在屏幕上画一个笑脸。”

如果硬件支持显示屏，Agent 可以通过 Lua 模块调用显示能力，把自然语言意图变成设备动作。

这不是让大模型替代所有确定性逻辑。恰恰相反，ESP-Claw 里有一套很清晰的分工：确定性的事情交给 Event Router 和 Capability，不确定的理解与编排交给 Agent。

这个边界很重要。

核心亮点

1. 用聊天定义设备行为

ESP-Claw 支持通过 Telegram、QQ、飞书、微信等 IM 入口和设备交互。对普通用户来说，这比再装一个 App、再学一套配置界面要自然得多。

它的“聊天造物”不是一句宣传语。项目里有 Skill、Capability、Lua 脚本和 Event Router 这几块拼在一起，形成了一个闭环：用户说需求，Agent 理解需求，选择工具，必要时写脚本，最后让硬件执行。

2. Lua 让设备可以动态长出新动作

在嵌入式开发里，改行为通常意味着改代码、编译、烧录。ESP-Claw 引入 Lua 的意义，是让一部分设备逻辑变成运行时可变的脚本。

项目里的 cap_lua 管理 /fatfs/scripts/，同时注册了很多 lua_module_* 和 lua_driver_* 模块。脚本可以调用 GPIO、I2C、显示、摄像头、音频、存储、事件发布等能力。

这对原型验证很有价值。你不一定每次都重刷固件，而是让设备通过脚本完成一些新动作。

3. Event Router 把自动化做得很稳

ESP-Claw 不是所有消息都一股脑扔给大模型。它有 router_rules.json，可以按事件来源、事件类型、关键词等条件匹配规则，然后执行动作。

动作包括：

调用某个 Capability运行 Lua 脚本提交给 Agent发送 IM 消息生成新事件丢弃事件

这让它既能处理自然语言，也能保留自动化系统该有的确定性。比如传感器事件、定时任务、启动事件，不一定需要大模型参与，可以直接走规则。

4. Skills 和 Capability 分得很清楚

项目里有一个设计很值得借鉴：Capability 是工具层，Skill 是知识层。

Capability 让 Agent “能做事”，比如运行 Lua、读写文件、发消息。Skill 则告诉 Agent “该怎么做”，它本质上是存放在文件系统里的 Markdown 文档。

这样做的好处是上下文不会一次性塞满。Agent 平时只看到 Skill 摘要，需要时再激活完整 Skill，同时开放对应的工具组。

这套设计对小设备尤其重要，因为上下文、内存、网络请求成本都不能乱花。

5. 记忆放在设备侧

ESP-Claw 的运行时数据挂在 /fatfs 下，包括会话历史、长期记忆、技能、脚本、路由规则、调度任务和 IM 附件。

其中长期记忆会落到 /fatfs/memory，会话在 /fatfs/sessions。这意味着它不是每次对话都从零开始，也不是把所有个人信息都默认交给云端应用保存。

当然，大模型请求本身仍然依赖外部 LLM API；这里更准确的说法是：ESP-Claw 把记忆组织和设备侧状态管理放在本地。

快速上手

如果你只是想体验，项目提供了在线烧录路径。准备一块已支持的开发板，使用 Chrome 或 Edge 浏览器连接设备，选择固件，填入 Wi-Fi、LLM API Key 和 IM 配置，就可以开始。

文档里提到，ESP-Claw 需要至少 8 MB Flash 和 8 MB PSRAM，目前支持 ESP32-S3、ESP32-P4。部分 ESP32-S3 开发板已经可以在线烧录。

如果想本地编译，项目推荐 ESP-IDF v5.5.4。大致流程是：

. <your-esp-idf-path>/export.sh
cd application/edge_agent
idf.py gen-bmgr-config -c ./boards -b esp32_S3_DevKitC_1
idf.py menuconfig
idf.py build
idf.py flash monitor

menuconfig 里需要配置 Wi-Fi、LLM、IM、搜索引擎、时区等参数。LLM 后端支持 OpenAI 风格 API 和 Anthropic 风格 API，也可以配置自定义 endpoint。

值得借鉴的设计

我最喜欢 ESP-Claw 的地方，不是“ESP32 能接大模型”，而是它没有把设备智能化做成一个单文件 Demo。

它更像一套小型运行时。

设备启动后，会先初始化 NVS、Board Manager、FATFS、Wi-Fi 和 HTTP 配置服务。然后进入 app_claw_start()，按顺序启动 Event Router、Memory、Skills、Capabilities 和 claw_core。

这个启动顺序能看出项目的工程取向：网络可以失败，HTTP 配置服务可以继续；LLM 没配完整，核心 Agent 功能会跳过，但离线规则和 Lua 脚本仍然能运行。对于嵌入式设备来说，这比“没网就全挂”要健康得多。

另一个值得看的是 Capability 的可见性管理。项目不会默认把所有工具都暴露给大模型，而是通过可见 Group 控制上下文。文件、Lua、系统、技能这类基础能力默认可见，其他能力按需启用。

这在 Agent 工程里是个很实际的问题：工具越多，模型越容易迷路，调用成本也越高。ESP-Claw 在小设备上把这个问题提前处理了。

适合谁用？

它适合三类人。

第一类是嵌入式开发者。你可以把它当作一个 ESP-IDF 项目样板，研究如何把 Agent、工具调用、事件路由和硬件能力整合进固件。

第二类是智能硬件原型团队。很多想法不必一开始就做完整 App，可以先用 IM + Agent + Lua 快速验证交互方式。

第三类是喜欢折腾 ESP32 的创客。比如做一个能聊天的桌面小屏、会提醒的硬件助手、能根据消息控制灯带和传感器的小装置。

但它不适合所有场景。

如果你的设备只需要稳定执行固定逻辑，传统状态机和规则系统可能更简单。如果你对响应延迟、离线能力、成本和隐私有极强约束，也要认真评估外部 LLM API 带来的依赖。

ESP-Claw 更适合那些“规则会变化、交互很自然、硬件动作可组合”的设备。

写在最后

ESP-Claw 有点像把 Cursor 这类 Agent 编程体验，压缩到一块 ESP32 设备里：不是让用户写代码，而是让用户描述目标，再由系统把目标拆成工具调用、脚本和事件。

它现在仍处在活跃开发阶段，边界也很清楚：强推理模型、网络、硬件适配、IM 配置都会影响体验。

但它给了一个很值得看的方向：未来的小设备，不一定只是云端智能的遥控末端。它们也可以有自己的运行时、记忆、技能和工具系统。

如果你一直觉得 IoT 设备“连上网了，但还是不够聪明”，ESP-Claw 值得翻一翻源码。

一份打通“应用→驱动”的Linux底层修炼指南！