上周末我从抽屉底翻出一块ESP32-S3开发板板子本身不值钱但我不想让它继续跑那些“点灯、读传感器”的老套路。研究了一阵我决定把扣子(Coze)平台上搭好的自定义智能体通过API接进来ESP32联网后发一段文本云端智能体理解并回复板子再根据回复去点亮LED、显示建议或者直接做动作。整套流程从配置到跑通大约花了一个晚上所有坑几乎都集中在HTTP请求和JSON解析上。这篇文章就写给想玩“AI 硬件”的人——创客、嵌入式方向的学生或者手里有块吃灰板子想升级成“带脑子设备”的老手。我会把Coze侧怎么配置、ESP32侧代码怎么写、以及我调试中踩过的几个典型错误完整走一遍。1. 为什么是“ESP32直接调智能体”而不是本地跑模型或自己包一层后端1.1 硬件侧跑大模型的现实难度很多人第一次看到“ESP32接入智能体”这个标题第一反应是能不能在板子上直接跑个模型我先说结论现阶段不要想这事。ESP32的SRAM普遍只有几百KBFlash也就4MB上下一个对话模型哪怕量化到很小的体积也需要几百MB存储和几十MB内存跑推理。板子上跑个关键词匹配、简单决策树没问题但要跑真正意义上的对话智能体算力和内存都差着好几个数量级。这是硬件物理规格决定的不是代码优化能解决的。所以“ESP32 云端智能体”的正确姿势一定是板子负责采集、联网、组包、解析和执行智能体负责理解、推理、决策和回复。两边各干各擅长的活儿。1.2 三种常见方案的取舍前面说了本地跑模型不可行那剩下的选择主要有三种方案资源要求开发成本适合场景自购云服务器做中转需要一台长期运行的服务器要搭服务、维护密钥、处理并发不想依赖第三方平台、流量很大的生产项目裸调大模型API只需要一个模型服务商API Key要自己维护多轮历史、上下文切割、工具调用、错误重试只有一两句话交互、逻辑很简单的场景直接调Coze API无需服务器板子直连Coze侧可视化配置ESP32只发HTTP请求需要知识库、工作流、插件组合的“自定义智能体”玩法我最终选了Coze原因很实际Coze帮我把“模型选择、提示词、多轮历史、工具调用”这些事都封装在了智能体内部ESP32只需要往一个接口丢文本就行。如果裸调模型API我得自己在代码里维护每轮对话的上下文长度、做老消息裁剪还要处理各种模型参数这些在单片机上写起来非常痛苦。1.3 这么接最大的好处逻辑迭代搬到云端传统单片机开发里想改一个设备行为哪怕只是把“温度过高提示开窗”改成“温度过高直接发通知”都得重新改代码、编译、烧录。但ESP32接Coze之后设备行为逻辑可以在Coze端通过改提示词、调工作流来变更板子里的代码一行都不用动。我把这个称为“动态逻辑下发”。比如我在Coze工作流里接了一个天气插件ESP32发送“今天适合户外跑步吗”智能体自己会去取天气数据再回答板子上完全没有跑任何天气相关的代码。这种能力在传统嵌入式开发里简直不敢想。2. Coze侧三个准备智能体设定、发布成API、拿到鉴权Key2.1 为硬件定制一个“话少、可控”的智能体在Coze里创建一个Bot很简单但为硬件场景设计提示词要注意一件事响应必须足够短、足够结构化。ESP32的内存有限一个动不动输出几百字的回复不仅解析麻烦还可能导致内存崩溃。我最初没注意这点Coze智能体回复了一整段带Markdown格式的文字板子直接当场重启。给硬件用的智能体我建议在系统提示词里写清楚这些约束你是一个嵌入式设备上的智能助手回复要简短、口语化尽量控制在100字以内。 不要使用Markdown、Emoji、表格等特殊格式。 当用户表达控制类意图时只输出标准JSON例如 {action:led_on}。 当用户给出环境数据时用一句话给出结论和建议。这里有个经验不要等设备端做“内容清洗”直接在提示词阶段把输出格式收紧设备端解析工作会轻松很多。控制指令用JSON约束输出问答内容用字数限制兜底这两条是我跑通之后觉得最值钱的设定。2.2 发布为API服务智能体配置好后需要发布成API服务才能被外部调用。在Coze的智能体页面找到“发布”或“分享”相关的入口选择发布为“API服务”之后平台会给你一个Bot ID形如一串数字。这里要注意发布形态的区别。Coze智能体在API化时有的版本会区分“对话流”和“工作流”。对话流适合纯文本对话工作流适合带工具编排的复杂任务。我第一次跑通用的是对话流形态对应的API是/v3/chat接口如果你的Bot发布了工作流版本调用的接口形态和入参结构会不同这个在遇到错误时需要回去核对。2.3 创建个人访问令牌调用Coze API需要鉴权方式是在请求头里加Authorization: Bearer Token。Token在Coze平台“个人访问令牌”页面创建创建时可以选择权限范围建议按最小权限原则分配。这个Token只会在创建时完整显示一次一定要先复制保存好。另外提醒一句不要把它直接硬编码后传到GitHub公开仓库即使项目再小也建议放到单独的头文件并加入.gitignore。网上有很多爬虫专门扫公开仓库里的API密钥被刷掉免费额度是小事被恶意调用产生费用就麻烦了。2.4 先用curl验证接口别急着碰硬件我特别建议在写ESP32代码之前先在电脑上用curl把API调通这样能把“平台配置问题”和“设备端问题”清晰分开。curl -X POST https://api.coze.cn/v3/chat \ -H Authorization: Bearer 你的Token \ -H Content-Type: application/json \ -d { bot_id: 你的Bot ID, user_id: esp32_test_001, stream: false, auto_save_history: true, additional_messages: [ {role: user, content: 你好请用一句话回复我} ] }几个关键字段说下bot_id上一步发布API服务后拿到的ID。user_id你自己定义的终端用户标识同一个设备用固定ID才能让Coze端记住多轮上下文。stream必须设成false。如果设成trueCoze会返回流式分块数据ESP32解析起来麻烦得多。additional_messages要发给智能体的消息数组角色是user。有个容易搞混的点走Coze API时不需要填任何模型名。模型是在Coze智能体配置里选中好的底层是DeepSeek还是其他模型对ESP32侧完全透明。如果你在调用时看到类似the supported api model names are deepseek-flash的报错多半是把模型平台的请求格式套到Coze上了请求地址或Body结构对不上。v3接口的响应结构大致长这样{ code: 0, msg: success, data: { id: chat_id, conversation_id: conversation_id, bot_id: bot_id, choices: [ { index: 0, message: { role: assistant, type: answer, content: 智能体的回复文本 }, finish_reason: end } ] } }ESP32阶段要提取的内容就是data.choices[0].message.content。3. 硬件端选型和Arduino环境配置别在这一步翻车3.1 选哪块板子理论上只要是带WiFi的ESP32系列都能做但型号选择影响后续体验芯片型号典型内存适合场景ESP32-WROOM-32520KB SRAM / 4MB Flash普通API调用项目性价比最高ESP32-S3512KB SRAM / 8MB Flash带屏幕、带语音、需要更多IO的项目ESP32-C3400KB SRAM / 4MB Flash对功耗有要求、功能简单的项目ESP32-C5较低主打低功耗跑复杂JSON解析要谨慎我自己用的是ESP32-S3 DevKit因为手里正好有而且USB口调试方便。如果你只是为了复刻这个项目经典ESP32 DevKit完全够用还便宜。3.2 Arduino IDE安装esp32开发包开发环境我用的是Arduino IDE 2.x配置方法很成熟打开“文件”-“首选项”在“附加开发板管理器网址”里填入https://espressif.github.io/arduino-esp32/package_esp32_index.json打开“开发板管理器”搜索esp32安装Espressif官方包。在“工具”-“开发板”里选择对应型号比如ESP32 Dev Module或ESP32S3 Dev Module。有个小坑有些兼容开发板用的是CH340串口芯片如果电脑识别不到端口需要装CH340驱动原厂板一般是CP2102macOS和Windows驱动通常自动装好。设备管理器里看不到COM口时先查这两类驱动别急着怀疑板子坏了。3.3 需要安装的库代码里会用到WiFi.h、WiFiClientSecure.h、HTTPClient.h这三个是esp32核心库自带的不用额外装。ArduinoJson需要从库管理器安装我用的最新7.x版本。ArduinoJson是这个项目里唯一必须手动装的库作用是构造请求JSON和解析响应JSON。有人会觉得自己拼字符串也能搞定String body {\bot_id\:\ botId \};小项目临时用没问题但一旦遇到中文内容、嵌套数组、字符串转义手动拼很容易出问题。用ArduinoJson还能自动处理UTF-8编码省去一堆烦恼。3.4 烧录前的小检查先烧一个Blink示例验证开发链路再跑复杂代码。如果遇到“连接失败”“串口打不开”大概率是以下原因端口选错重新在设备管理器里确认。下载时需要按住板上的BOOT键尤其是一些老款开发板。串口监视器乱码先确认波特率是不是和Serial.begin()一致中文乱码很可能是监视器字符编码问题。4. ESP32发请求的核心代码JSON构造、HTTPS、响应解析4.1 整体流程拆解整个请求流程可以分成6步WiFi连接。用ArduinoJson构造请求体。WiFiClientSecure建立TLS连接。HTTPClient发送POST请求。读取响应字符串。ArduinJson解析响应提取content字段然后按指令执行动作。流程不复杂但每一步都有容易踩的细节下面逐段说明。4.2 完整示例代码这是一个能直接编译运行的示例框架。注意把BOT_ID和API_TOKEN换成你自己的。#include WiFi.h #include WiFiClientSecure.h #include HTTPClient.h #include ArduinoJson.h const char* WIFI_SSID 你的WiFi; const char* WIFI_PASS 你的WiFi密码; const char* BOT_ID 你的Bot ID; const char* API_TOKEN 你的Coze个人访问令牌; const char* USER_ID esp32-device-01; // 固定设备ID用于多轮记忆 const int LED_PIN 2; void setup() { Serial.begin(115200); pinMode(LED_PIN, OUTPUT); WiFi.mode(WIFI_STA); WiFi.begin(WIFI_SSID, WIFI_PASS); while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); } Serial.println(\nWiFi connected); } String askCoze(const String userMessage) { WiFiClientSecure *client new WiFiClientSecure; client-setInsecure(); // 开发阶段跳过证书校验正式项目建议加载CA证书 HTTPClient http; http.begin(*client, https://api.coze.cn/v3/chat); http.addHeader(Content-Type, application/json); http.addHeader(Authorization, String(Bearer ) API_TOKEN); // 构造请求体 JsonDocument bodyDoc; bodyDoc[bot_id] BOT_ID; bodyDoc[user_id] USER_ID; bodyDoc[stream] false; bodyDoc[auto_save_history] true; JsonArray messages bodyDoc[additional_messages].toJsonArray(); JsonObject msg messages.addJsonObject(); msg[role] user; msg[content] userMessage; msg[content_type] text; String requestBody; serializeJson(bodyDoc, requestBody); int httpCode http.POST(requestBody); String response http.getString(); http.end(); delete client; if (httpCode ! 200) { Serial.printf(HTTP error: %d\n, httpCode); return ERROR; } // 解析响应 JsonDocument respDoc; DeserializationError err deserializeJson(respDoc, response); if (err) { Serial.println(JSON parse failed); return ERROR; } const char* content respDoc[data][choices][0][message][content] | EMPTY; return String(content); } void loop() { if (Serial.available()) { String input Serial.readStringUntil(\n); input.trim(); if (input.length() 0) { String reply askCoze(input); Serial.println(AI: reply); // 简单指令执行 if (reply.indexOf(led_on) 0) { digitalWrite(LED_PIN, HIGH); } else if (reply.indexOf(led_off) 0) { digitalWrite(LED_PIN, LOW); } } } }这个示例用串口输入的文本作为触发源方便调试。实际项目里可以把触发源换成按键、定时器或者传感器事件。4.3 让回复变成设备动作设备接入AI之后最难的不是请求而是“怎么把回复变成行动”。我在示例里用了最简单的关键词匹配如果你的Coze提示词里约定了结构化JSON输出ESP32侧可以直接解析JSONStaticJsonDocument256 actDoc; deserializeJson(actDoc, reply); const char* action actDoc[action] | ; if (strcmp(action, led_on) 0) { digitalWrite(LED_PIN, HIGH); } else if (strcmp(action, led_off) 0) { digitalWrite(LED_PIN, LOW); }两种方式对比我推荐后者。关键词匹配对回复内容要求太严格只要Coze偶尔加一句说明文字匹配就可能失效。用JSON约定指令相当于在提示词层就约定了通信协议稳定性高得多。4.4 内存和请求频率管理这块是最容易被忽视的。ESP32虽然比普通单片机内存大但经不住每次请求都泄漏一点。每次请求完要调用http.end()释放连接示例里把WiFiClientSecure用new创建、用完delete也是为了避免栈内存被大的TLS握手数据撑爆。JsonDocument建议在请求函数内部创建局部变量用完自动释放不要图方便用全局变量长期运行容易产生内存碎片。请求间隔至少留几秒。一是避免触发平台限流二是给堆内存释放留出时间。我的实测经验是10秒以上间隔非常稳。5. 从“能通”到“能用”四种交互模式直接抄作业5.1 按键触发最简单的智能问答终端第一个能跑通的模式我建议做成按键触发。一个按钮接GPIO按下时执行一次askCoze把回复显示在串口或一块0.96寸OLED屏上。这个模式的优点是逻辑极简、省电、不浪费Token而且在调试时能非常明确地复现问题。我第一次调通整个链路就是靠按键模式按一下看串口打印原始JSON逐步确认哪一步有问题。5.2 定时环境上报让智能体做判断把ESP32接上DHT11温湿度传感器每10分钟向Coze发送一条拼好的环境数据摘要让智能体输出结论。拼接消息的示例String message 当前温度 String(temperature) 度湿度 String(humidity) %请判断是否适合浇花用一句话回复;这种模式下智能体变成了“判断中枢”。你甚至可以把采集到的数据放到Coze工作流里让智能体结合历史数据或外部天气API给更复杂的建议。板子端完全不用关心这些逻辑是怎么实现的只需要负责采集和组包。5.3 串口/局域网调试模式用PC串口发送消息再转发给Coze是开发阶段效率最高的方式。示例代码里已经实现了这部分功能打开串口监视器输入一行文本按回车串口打印AI回复。如果你想在手机或另一台电脑上远程调试可以让ESP32起一个简单的HTTP Server浏览器里发消息。不过这种模式不适合长期跑耗电倒是小事安全性才是主要问题毕竟开发板的鉴权机制很弱。5.4 语音交互是进阶方向建议晚点上有朋友问能不能让板子直接“说话”我的经验是这条路复杂度会突然跳一个台阶。语音交互意味着你要加麦克风采集音频、做语音唤醒、把音频送到云端做语音识别再把识别文本发给Coze最后还要把回复语音合成播出来。这一套下来ESP32的资源和开发工作量都明显增加。Coze本身支持文件上传和语音类插件但ESP32内存小直接上传音频文件并不现实通常需要借助外部ASR服务做转写。建议先把文本链路跑稳定再逐步往语音方向扩展。一口吃不成胖子这个项目里尤其如此。6. 调试中踩过的坑从400 schema到内存爆炸的排查链路6.1 “invalid schema for function artifact”类400错误如果你在Coze智能体上挂了工作流或工具而请求体里没有按平台的工具入参结构传参很容易遇到类似invalid schema for function artifact的400错误。这种错误本质上不是HTTP层面的问题而是“请求参数和服务器端的函数定义对不上”。Coze平台会给每个工具函数定义入参schema当你传入的字段类型、字段名或者必填项不符合要求时就会报这个错。我的排查顺序是这样的先用PC上已经调通的curl请求做基准把Body内容打印出来对比。回到Coze智能体的工具/工作流配置页逐个核对入参schema里有哪些必填字段。如果请求体里出现了工具定义中没有的字段删掉再试。确认你调用的是“对话流”接口还是“工作流”接口两者的入参结构差很多。很多人在这一步卡住其实是把请求发到了错误的API形态上。Coze把同一个Bot发布成API服务时对话流和工作流的调用方式是两套不同的接口约定field名字一样不代表能通用。6.2 看到“supported api model names are deepseek-flash”意味着什么这个报错我见过不少次而且是在别人拿示例代码改的时候经常出现。本质原因只有一个请求发错了地方。有人以为Coze的智能体底层用了DeepSeek就直接拿DeepSeek官方的API格式来调Coze结果请求地址还是Coze的Body里却带了model字段。Coze API会认为你想切换模型于是报出它支持的模型列表。记住一个原则**走Coze API你的身体里不需要出现任何模型名字。**模型是在Coze智能体配置页里选好的ESP32发出去的请求只有对话内容没有模型参数。如果你在Coze的模型配置里把底层模型从DeepSeek换成其他模型ESP32端代码一行都不用改这正是这种封装架构的价值所在。6.3 TLS证书校验失败第一次跑HTTPS请求最常见的现象是请求返回-1或者-2这种负数状态码日志里没有任何HTTP错误信息。这个坑的根源是开发板的时钟问题。TLS证书校验需要当前时间ESP32刚上电时RTC是不准确的时间没同步就会导致证书链校验失败。有两个解决办法开发阶段用client.setInsecure()跳过证书校验调试成本最低。正式项目里先通过NTP同步时间再加载正确的CA证书。我个人在开发阶段是先用setInsecure()代码里注释清楚“这是开发妥协”等项目逻辑稳定后再补证书和时间同步。需要注意跳过证书校验意味着理论上存在中间人攻击风险公网项目不建议长期这么干。6.4 中文乱码和JSON转义问题串口打印AI回复出现中文乱码大多数时候不是代码问题而是串口监视器的显示问题。Coze返回的是UTF-8编码ArduinoJson解析时不会动编码串口监视器如果显示区域编码设置不对就会看到乱码。先把波特率和监视器编码确认一遍再怀疑代码。另一个相关问题是手动转义中文。有些新手会这样写String content \\u4f60\\u597d; // 手动转义“你好”没必要。ArduinoJson的serializeJson会自动处理JSON转义你只要把原始中文字符串放进去就行。发送端不需要URLEncode只需要保证请求头Content-Type: application/json正确设置。6.5 响应体过大导致内存崩溃症状很典型程序跑着跑着板子突然重启串口打印乱码或者Guru Meditation Error。我在最开始犯过这个错。Coze智能体回复很长一段带格式文本时StaticJsonDocument2048根本装不下直接溢出。解决思路分三层在Coze提示词里限制回复字数这是最有效的办法。解析响应时用DeserializationError检查解析是否成功失败时打印响应前几百个字符做诊断。如果必须接收长文本把StaticJsonDocument换成DynamicJsonDocument或调大缓冲区但ESP32内存有限建议优先压缩Coze回复长度。我实测的经验是提示词里写“100字以内”后Coze大部分回复都稳定在几百字节2048字节的JsonDocument基本够用。6.6 Token上限、限流与安全如果请求频率太高Coze API会返回429限流错误。处理方式是退避重试第一次失败等2秒第二次等4秒第三次等8秒指数增长直到请求成功。Token安全方面最需要注意的是别把Bearer Token传到公开渠道。我的习惯是建一个config.h文件存放Token和WiFi密码然后把这个文件加入.gitignore确保不会误提交到GitHub。下面这张表是我整理的典型问题速查方便你排查时快速定位错误现象可能原因优先排查顺序HTTP 400 invalid schema工具/工作流入参结构不匹配核对Coze端schema定义HTTP 400 supported model names请求体里带了模型名去掉model字段HTTP 403Token过期或权限不足检查Token是否过期HTTP 429请求频率过高增加重试退避负数状态码TLS握手失败检查证书和系统时间板子重启JSON文档太大缩短Coze回复、调大缓冲区中文乱码监视器编码问题检查波特率和UTF-8设置最后分享一点个人体会这个项目真正有价值的点不在于让板子“会聊天”而在于把硬件交互里最复杂的自然语言理解环节外包给了云端智能体本地只负责联网、组包、解析、执行。我后续想继续扩展的方向是在Coze工作流里接一个数据库记录设备每次上报的历史再让智能体基于历史数据做趋势判断——而实现这个功能不需要改一行ESP32代码。如果你第一次做类似的接线项目最省时间的调试路径是先用curl把API调通再用按键触发模式打印原始JSON确认解析逻辑正确之后再往界面和业务方向扩展。希望这块板子别继续吃灰了。