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 開發(fā)板

16MB Flash

最好帶 PSRAM

一根 USB 數據線

軟件上：

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

Python 環(huán)境

Git

項目里當前默認目標芯片就是esp32s3 ，而且會在構建時自動把 spiffs_data/ 打包進 SPIFFS 分區(qū)。

這個工程首次編譯時會通過 idf_component.yml 自動拉依賴組件 ，所以第一次 build 可能會比你想象中久一點！

1

第一步：拉下源碼 ，先看兩個關鍵文件

把倉庫拉下來之后 ，先看兩個地方：

README_ZH.md

components/embed_claw/ec_config.h

前者告訴你這個項目的整體架構和運行方式

后者決定你到底能不能跑起來

2

第二步： 申請千問 API Key

EmbedClaw 當前接入的是千問的 OpenAI-Compatible 接口 ，代碼里默認使用的是：

#defineEC_LLM_API_URL"https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions"#defineEC_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 頁面創(chuàng)建和管理

Key 只用于鑒權 ，官方明確建議不要分享給其他人

2

申請步驟

1. 打開上面的官方文檔鏈接

2. 按文檔里的入口進入 API-KEY Management

3. 登錄你的阿里云賬號

4. 創(chuàng)建一個新的 API Key

5. 復制并保存好

拿到以后 ，后面填到：

#defineEC_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. 復制保存

然后把它填到：

#defineEC_SECRET_SEARCH_KEY"你的 Tavily API Key"

3

這把 Key 有什么用

有問必有答。

在 EmbedClaw 里 ，模型一旦遇到“需要最新事實” 的問題 ，比如：

今天的科技新聞

某個城市的天氣

某項產品的最新資料

它就會自動調用 web_search ，再把搜索結果回灌給模型繼續(xù)回答。

4

第四步： 申請飛書 App ID 和 App Secret

1

去哪里創(chuàng)建應用

官方入口：

飛書開發(fā)者后臺： https://open.feishu.cn/app

官方文檔參考：

2

創(chuàng)建步驟

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

2. 登錄飛書開發(fā)者后臺

3. 創(chuàng)建一個“企業(yè)自建應用 ”

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. 安裝依賴：

pipinstall lark-oapi websocket-client

II. 運行倉庫里腳本激活長連接：

python scripts/feishu_relay.py--app_id<你的飛書AppID>--app_secret<你的飛書AppSecret>

7. 添加訂閱事件 im.message.receive_v1 ：

8. 點擊“版本管理與發(fā)布”

9. 點擊“創(chuàng)建版本”

10. 設置版本號以及更新說明點擊保存 ，然后確認發(fā)布

11. 進入“憑證與基礎信息”你就能看到 App ID 和 App Secret

5

第五步：把 3 組憑證寫進工程

打開文件：

components/embed_claw/ec_config.h

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

#defineEC_SECRET_SEARCH_KEY "YOUR_TAVILY_API_KEY"#defineEC_LLM_API_KEY "YOUR_DASHSCOPE_API_KEY"#defineEC_LLM_MODEL "qwen-plus"#defineEC_SECRET_FEISHU_APP_ID "YOUR_FEISHU_APP_ID"#defineEC_SECRET_FEISHU_APP_SECRET"YOUR_FEISHU_APP_SECRET"

這里有三點大家需要注意一下

1. Qwen 是必須的 ，不然模型根本起不來

2. Tavily 不是必須的 ，但沒有它就沒有實時搜索

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

也就是說，如果您只是想先驗證工程活著沒活著 ，最小可跑路徑其實是：

先填千問 Key

可選填 Tavily Key

飛書先不配

6

第六步：開始編譯

在已經正確加載 ESP-IDF 5.x 環(huán)境的終端中執(zhí)行：

idf.pyset-target esp32s3idf.py build

如果你第一次編譯比較慢：

7

第七步：燒錄并打開串口監(jiān)視器

執(zhí)行：

idf.py -p /dev/ttyACM0 flash monitor

如果你是 macOS ，串口通常會長這樣：

/dev/cu.usbmodemXXXX

如果你是 Linux ，也可能是：

/dev/ttyUSB0

看到串口日志后 ，說明程序已經真正進板子了。

8

第八步：第一次聯(lián)網

這個項目的 Wi-Fi 邏輯是這樣的：

如果設備里已經保存過 Wi-Fi ，就直接聯(lián)網

如果沒有保存過 Wi-Fi ，就啟動一個配網熱點

熱點前綴默認是：

#defineEMBED_WIFI_SSID_PREFIX"ESP32"

配網步驟：

手機或電腦連接開發(fā)板放出的熱點

打開瀏覽器訪問 http://192.168.4.1

選擇你的家庭或辦公室 Wi-Fi

輸入密碼并提交

設備重啟

自動切回 STA 聯(lián)網模式

設備一旦連網成功 ，EmbedClaw 就會自動啟動。

9

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

1

安裝測試腳本依賴

倉庫已經帶了腳本：

scripts/test_ws_client.py

先安裝依賴：

pipinstall websocket-client

2

連到設備

假設你的設備 IP 是 192.168.31.88 ，執(zhí)行：

pythonscripts/test_ws_client.py192.168.31.8818789

項目默認 WebSocket 端口是：

#defineEC_WS_PORT 18789

3

發(fā)一條消息試試

連接成功后 ，直接輸入：

你好

如果一切正常 ，你會收到開發(fā)板返回的回復。

10

第十步：再接飛書 ，完成“真正能用”的形態(tài)

當 WebSocket 已經通了以后 ，再去驗證飛書會輕松很多。

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

如果你對我們的EmbedClaw感興趣，或者有想要接入的大模型、聊天機器人或者功能，歡迎在評論區(qū)留言告訴我們！Embedclaw和大家一起進步！