ESP32里的AI Agent：EmbedClaw上手教程！启明云端乐鑫代理及方案商

EmbedClaw 是启明云端开源的一个可以跑在ESP32上的AI Agent项目。

这个项目最有意思的地方 ，不是“能聊天” ，而是它把几个最容易缠在一起的模块拆开了：

LLM ：现在接的是千问  qwen-plus

Tools ：现在已经有时间、文件、网页搜索、定时任务

 Agent ：负责 ReAct Tool Loop

Channel ：目前已经接了  Feishu 和  WebSocket

也就是说 ，它不是一个单纯的聊天 Demo ，更像是一个运行在 MCU 上的Agent Runtime。

项目仓库：

https://github.com/wireless-tag-com/EmbedClaw

详情可以了解：

EmbedClaw：我把一个完整 AI Agent 跑进了 ESP32！启明云端乐鑫代理及方案商

 

你需要准备什么

 

硬件上：

一块  ESP32-S3 开发板

16MB Flash

最好带  PSRAM

一根 USB 数据线

 

软件上：

已安装好的  ESP-IDF 5.x .

Python 环境

Git

项目里当前默认目标芯片就是esp32s3 ，而且会在构建时自动把  spiffs_data/ 打包进 SPIFFS 分区。

这个工程首次编译时会通过  idf_component.yml 自动拉依赖组件 ，所以第一次 build 可能会比你想象中久一点！

1

第一步：拉下源码 ，先看两个关键文件

把仓库拉下来之后 ，先看两个地方：

README_ZH.md

components/embed_claw/ec_config.h

前者告诉你这个项目的整体架构和运行方式

后者决定你到底能不能跑起来

2

第二步： 申请千问 API Key

EmbedClaw 当前接入的是千问的 OpenAI-Compatible 接口 ，代码里默认使用的是：

•  
•  

#define EC_LLM_API_URL "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions"#define EC_LLM_MODEL "qwen-plus"

你要填的核心参数只有一个：

•  

EC_LLM_API_KEY

1

 去哪里申请

官方入口：

阿里云 Model Studio API Key 文档：

 https://help.aliyun.com/zh/model-studio/get-api-key

这份官方文档说明了两件关键事：

API Key 在 API-KEY Management 页面创建和管理

Key 只用于鉴权 ，官方明确建议不要分享给其他人

 

2

申请步骤

1. 打开上面的官方文档链接

2. 按文档里的入口进入 API-KEY Management

3. 登录你的阿里云账号

4. 创建一个新的 API Key

5. 复制并保存好

拿到以后 ，后面填到：

•  

#define EC_LLM_API_KEY "你的DashScope API Key"

3

第三步： 申请 TavilyAPI Key

如果你希望 EmbedClaw 具备“查今天新闻、查天气、查最新资料” 的能力 ，就需要把  web_search 工具跑起来。

1

去哪里申请

Tavily 官方文档写得很直接：

 

2

申请步骤

1. 打开 https://app.tavily.com/home

2. 注册或登录 Tavily 账号

3. 进入控制台后生成 API Key

4. 复制保存

然后把它填到：

•  

#define EC_SECRET_SEARCH_KEY "你的 Tavily API Key"

 

3

这把 Key 有什么用

有问必有答。

 

在 EmbedClaw 里 ，模型一旦遇到“需要最新事实” 的问题 ，比如：

今天的科技新闻

某个城市的天气

某项产品的最新资料

它就会自动调用 web_search ，再把搜索结果回灌给模型继续回答。

 

4

第四步： 申请飞书 App ID 和 App Secret

1

去哪里创建应用

官方入口：

飞书开发者后台： https://open.feishu.cn/app

官方文档参考：

 

2

创建步骤

1. 打开  https://open.feishu.cn/app

2. 登录飞书开发者后台

3. 创建一个“企业自建应用 ”

4. 点击添加机器人

5. 进入配置用户权限 ，通过批量导入权限

•  

{"scopes":{"tenant":["contactreadonly","docxreadonly","imread","imupdate","imreadonly","imreadonly","imread","imwrite_only","imread","imwrite_only","imreadonly","imrecall","imsend_as_bot","imsend_multi_users","imsend_sys_msg","imupdate","im:resource","applicationself_manage","cardkitwrite","cardkitread"],"user":["contactreadonly","offline_access","basecopy","basecreate","basedelete","baseread","baseupdate","basecreate","basedelete","baseretrieve","baseupdate","basecreate","basedelete","baseread","baseupdate","baseread","basewrite_only","basecreate","baseupdate","baseread","boardnode:create","boardnode:read","calendarread","calendarcreate","calendardelete","calendarread","calendarreply","calendarupdate","calendarread","contactreadonly","contactreadonly","contactsearch","docscreate","docsread","docsupdate","docsdownload","docscopy","docxcreate","docxreadonly","docxwrite_only","drivereadonly","drivedownload","driveupload","imread","imread","im:message","imget_as_user","imget_as_user","imreadonly","searchread","search:message","spacedelete","spacemove","spaceretrieve","taskread","taskwrite","taskread","taskwrite","taskwriteonly","taskread","taskwrite","wikicopy","wikicreate","wikimove","wikiread","wikiretrieve","wikiread","wikiretrieve","wikiwrite_only"]}}

 

6. 配置事件订阅 使用长连接接收事件

如果出现了“未检测到应用连接信息 ，请确保长连接建立成功后再保存配置” 问题 ，别慌。按照如下步骤激活

I. 安装依赖：

•  

pip install lark-oapi websocket-client

II. 运行仓库里脚本激活长连接：

•  

python scripts/feishu_relay.py --app_id <你的飞书AppID> --app_secret <你的飞书AppSecret>

7. 添加订阅事件 im.message.receive_v1 ：

8. 点击“版本管理与发布”

9. 点击“创建版本”

10. 设置版本号以及更新说明点击保存 ，然后确认发布

11. 进入“凭证与基础信息”你就能看到 App ID 和 App Secret

 

5

第五步：把 3 组凭证写进工程

打开文件：

•  

components/embed_claw/ec_config.h

把里面的占位值改成你自己的：

•  
•  
•  
•  
•  

#define EC_SECRET_SEARCH_KEY        "YOUR_TAVILY_API_KEY"#define EC_LLM_API_KEY              "YOUR_DASHSCOPE_API_KEY"#define EC_LLM_MODEL                "qwen-plus"#define EC_SECRET_FEISHU_APP_ID     "YOUR_FEISHU_APP_ID"#define EC_SECRET_FEISHU_APP_SECRET "YOUR_FEISHU_APP_SECRET"

这里有三点大家需要注意一下

1.  Qwen 是必须的 ，不然模型根本起不来

2.  Tavily 不是必须的 ，但没有它就没有实时搜索

3.  Feishu 不是必须的 ，不填也能先用 WebSocket 跑通

也就是说 ，如果您只是想先验证工程活着没活着 ，最小可跑路径其实是：

先填千问 Key

可选填 Tavily Key

飞书先不配

6

第六步：开始编译

在已经正确加载  ESP-IDF 5.x 环境的终端中执行：

•  
•  

idf.py set-target esp32s3idf.py build

如果你第一次编译比较慢：

 

7

第七步：烧录并打开串口监视器

执行：

•  

idf.py -p /dev/ttyACM0 flash monitor

如果你是 macOS ，串口通常会长这样：

•  

/dev/cu.usbmodemXXXX

如果你是 Linux ，也可能是：

•  

/dev/ttyUSB0

看到串口日志后 ，说明程序已经真正进板子了。

8

第八步：第一次联网

这个项目的 Wi-Fi 逻辑是这样的：

如果设备里已经保存过 Wi-Fi ，就直接联网

如果没有保存过 Wi-Fi ，就启动一个配网热点

热点前缀默认是：

•  

#define EMBED_WIFI_SSID_PREFIX "ESP32"

配网步骤：

手机或电脑连接开发板放出的热点

打开浏览器访问  http://192.168.4.1

选择你的家庭或办公室 Wi-Fi

 输入密码并提交

设备重启

自动切回 STA 联网模式

设备一旦连网成功 ，EmbedClaw 就会自动启动。

9

第九步：先用 WebSocket 跑通 ，最省事

1

安装测试脚本依赖

仓库已经带了脚本：

•  

scripts/test_ws_client.py

先安装依赖：

•  

pip install websocket-client

 

2

连到设备

假设你的设备 IP 是  192.168.31.88 ，执行：

•  

python scripts/test_ws_client.py 192.168.31.88 18789

项目默认 WebSocket 端口是：

•  

#define EC_WS_PORT 18789

3

发一条消息试试

连接成功后 ，直接输入：

•  

你好

如果一切正常 ，你会收到开发板返回的回复。

10

第十步：再接飞书 ，完成“真正能用”的形态

当 WebSocket 已经通了以后 ，再去验证飞书会轻松很多。

以上就是本期EmbedClaw的上手教程了！

如果你对我们的EmbedClaw感兴趣，或者有想要接入的大模型、聊天机器人或者功能，欢迎在评论区留言告诉我们！Embedclaw和大家一起进步！