VS code配置ESP-IDF，连接官方服务器，终端监视小智AI（win10，win11系统）

一、前言

        这篇文章主要是自己在烧录小智AI固件时的总结，是面向小白教程，只有具体的操作步骤，并没有原理解释等技术性内容，目前我只是大学生，一开始的目的是为了给我同学当作教程，所以细节会不太好，先提前至歉，欢迎各位看到的大佬斧正。

        有一点需要提前说明，我是跟着小智AI聊天机器人百科全书（下方有链接），先用Flash工具烧录了一遍，然后在VS Code上配置ESP-IDF环境后，部署了本地服务器，就想着既然能连接自己的服务器，是不是也能连接到官方的服务器，便去尝试用VS code配置ESP-IDF环境，连接到官方服务器，分别在自己的台式机和轻薄本成功实现后，才写下这篇文章。

下面的链接是我烧录时主要看的教程，在此感谢各位大佬们分享的资源和制作的教程。

b站up：

香草味的纳西妲喵，小智AI系列教程https://space.bilibili.com/1347891621/lists/5135223?type=season

小灰灰爱吃香菜版https://space.bilibili.com/399627927小智 AI 聊天机器人百科全书： https://xiaozhi.me/docs

github用户欣南科技(xinnan-tech)搭建canda环境，进行本地部署教程：https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/Deployment.md

注意：这篇文章的内容没有本地部署服务器的内容，本地部署可以打开上面的链接学习

补充一点，硬件是指如图所示的ESP32 S3等外部实际的开发板，面包板，喇叭等看得见，摸得着的实体物。

固件指的是如下图要烧录到芯片里的代码源文件，更接近软件，不过软件是存储在机械硬盘、固态硬盘等存储设备中，而固件是存储在专用的芯片中。

硬件和固件这两者是完全不同的，请分清二者的区别，不要混淆。

 二、安装准备

安装的路径不要出现中文，哪怕你用拼音，也别用中文

如果已经安装了，请跳过这一步

VS Code官网地址：https://code.visualstudio.com/

ESP-IDF下载地址1：https://dl.espressif.com/dl/esp-idf/

打不开就换下面这个

ESP-IDF下载地址2：https://dl.espressif.com.cn/dl/esp-idf/

        打开VS Code官网，点图中蓝色按键Download，下载途中不用干等，继续打开ESP-IDF下载地址

        这里以下载地址1做演示，下载第三个v5.4.1，前两个不用管，如果版本更新了，可以试着下新版本，不想折腾可以下同一个版本

1、VS Code安装

        1.1打开浏览器下载，打开文件夹所在目录

        1.2、貌似VSCode选不了下载路径，建议别把安装包放到系统盘(C盘)

        1.3按照默认选项，一直点击下一步，最后点安装即可

第一次安装，VS Code会是英文，不用慌，下面是汉化教程

点击左侧像积木一样的图标，搜索CHINESE，点击第一个插件(简体中文)右下角蓝色按钮Install，因为我之前在VS Code安装过其它插件，所以红色框内积木图标的下方会有其它图标，第一次安装VS Code，是没有下面那两个图标的，很正常。这个教程用不到那两个插件，不用管

安装完成后界面右下角会跳出提示，点蓝色按钮，就会自动更改语言重启软件，就完成了

2、ESP-IDF安装

        2.1、打开安装包，简体中文，确定。一直点下一步

2.2、安装路径不要出现中文，记住你的安装路径，记不住的话，在桌面新建文本文档，把安装路径复制进去，然后ctrl+s保存

安装过程很慢，耐心等待

2.3、安装完成后，桌面会出现下图的快捷方式图标，打开PowerShell

在这个界面输入（这里的命令没有空格，直接输入即可）

idf.py

当出现idf.py build字样就是安装成功了，可以编译固件了

以上就算是安装完成，接下来进入VSCode，配置ESP-IDF，编译小智固件。

当然，也可以参照百科全书这个教程网站，直接在ESP-IDF中进行编译和烧录，这里不多赘述

 小智 AI 聊天机器人百科全书： https://xiaozhi.me/docs

另附：Git安装

        如果你有梯子，能打开github就不用安装，可以试试点开下面的链接如果能出现图中界面并打开绿色按钮Code -> Download，成功下载，那就跳过吧。

 进入虾哥代码主页：

https://github.com/78/xiaozhi-esp32

不想安装Git 也可以跳过，这个软件是下载源码用的，如果你没有梯子上github，我个人建议还是安装一个。

可以用百度网盘，夸克网盘，UC网盘来拿源码，但我给的网盘链接里是1.5.6版的（日期2025/04/08）拿不到最新版

        （1）官网下载Git：（好像也是要梯子，基本打不开，就算能打开也下载得非常慢，如图所示，所以就不给详细教程了，自己安装吧）

Git官网地址：https://git-scm.com/

   源码与Git安装包网盘链接

（2）xiaozhi-esp32源码以及Git安装包：（推荐UC网盘，非会员也不限速） UC网盘：https://drive.uc.cn/s/9ffea5613d424            提取码：Mgqm 夸克网盘：https://pan.quark.cn/s/2367111f9515        提取码：fYzk 百度网盘：https://pan.baidu.com/s/1RVp76fFR42qTf-sZIldB7Q         提取码：0000

打开安装包，改了安装路径之后，一直点NEXT（下一步）就行，不用动它的默认设置，下面的截图看第二个带有红字的就行，其余的无脑点NEXT，为了避免有人钻牛角尖，还是放完整的流程截图在这。

终于截完图了，真的是又臭又长。全都不用改，都是默认设置，最后点Install安装就行了 

安装完成后会跳出这个弹窗，两个都不用打勾，手快点了Finish也没什么影响，把跳出来的网页关掉就好。

三、在VS Code中配置ESP-IDF

3、安装ESP-IDF插件

       3.1、打开VS Code，点击左侧这个积木一样的图标，搜索 ESP ，安装图中第一个ESP IDF插件

点击左侧刚刚安装的ESP-IDF插件图标，右下角会弹出提示，点击蓝色按钮 Open Setup wizard，另一个直接关掉

        3.2、打开Advanced，点击配置ESP-IDF扩展，等待一段时间后，就会弹出右侧的界面，点红框里的，USE EXISTING SETUP，跳转界面后打开Search ESP-IDF in system

                3.3、还记得安装ESP-IDF时让你记住的安装路径吗，或者打开你的文本文档，复制路径

跳转到该界面后，红框内的安装路径是要修改的，其它的保持默认，如下图

红框内第一个必须要包含图中红底白字的路径，第二个的路径必须和第一个不同，否则会报错

分别打开右边两个红色小方框，粘贴到如图所示位置

依次打开 frameworks  –>   esp-idf-v5.4.1，然后复制这个路径

回到VS Code，把“你的路径+Espressif\\frameworks\\esp-idf-v5.4.1”粘贴到下图红框（IDF_PATH）中，红框下方(IDF_TOOLS_PATH)就直接粘贴上一级或上两级的文件夹目录，比如：

“你的路径+Espressif”，最后点Install安装。

等它安装一会儿，你就会发现报错啦！

这里的截图是b站up主香草味的纳西妲喵香草味的纳西妲喵【教程】使用VSCode安装ESP-IDF烧录小智AI固件，视频里的，因为我弄过了，不会出报错，没法演示。

复制蓝色下划线的路径，"你的路径+Espressif\\tools\\idf-python\\3.11.2"，粘贴到刚刚新建的文本文档里，记得保存。

4、pip设置镜像（没报错可跳过）

        4.1、保存好路径后，复制下面的链接到浏览器中打开（冒号后面的），把这个网页文件保存到刚刚复制的路径上

get-pip：https://bootstrap.pypa.io/get-pip.py

        4.2、在 "你的路径\\Espressif\\tools\\idf-python\\3.11.2" 路径里，输入cmd，打开命令提示符

        4.3、打开命令提示符后，复制下面的代码，粘贴到里面运行

python.exe get-pip.py

过程图如下（这里是b站up主香草味的纳西妲喵香草味的纳西妲喵【教程】使用VSCode安装ESP-IDF 视频里的截图，我自己安装过了，没法演示。）

在命令提示符里运行下面的代码，检查pip是否安装成功：

python -m pip –version

如下图，运行代码后出现版本号，就代表安装成功。

5、配置完成

        5.1、回到VS Code，重新点击Install，耐心等待它安装完成，如果没有这个界面，请回到

3、安装ESP-IDF插件，重复第3.2小节的步骤。

四、编译并烧录小智AI固件

6、下载源码

       方法1：网盘获取

 xiaozhi-esp32源码以及Git安装包：（推荐UC网盘，非会员也不限速） UC网盘：https://drive.uc.cn/s/9ffea5613d424            提取码：Mgqm 夸克网盘：https://pan.quark.cn/s/2367111f9515        提取码：fYzk 百度网盘：https://pan.baidu.com/s/1RVp76fFR42qTf-sZIldB7Q         提取码：0000

        方法2：安装好Git后，在工具git上拉取源码

鼠标右键点击桌面，笔记本用户多一步，就是点“显示更多选项”，然后和台式机用户一样，再点Open Git Bash here，如果没有，那就是GIt没安装好，建议重新安装或者重启电脑。

然后复制下面的命令，鼠标右键点击窗口，(Paste)粘贴到弹出来的窗口中，

注意：这个窗口无法使用Ctrl+V来粘贴命令

git clone https://github.com/78/xiaozhi-esp32

然后运行就好了，完成之后github的源码文件就被下载到桌面了，连解压都不需要。详细内容请看7.1小节。

注意：源码必须解压放在ESP-IDF安装文件夹  Espressif 同一路径下，否则会报错

方法3：在github下载（外网，有时候能打开，多数情况下要挂梯子）

6.3、虾哥代码主页

进入虾哥代码主页：https://github.com/78/xiaozhi-esp32

点击Code – Download ZIP

7、调整源码文件位置并在VS Code打开

         7.1调整源码文件路径

再次提醒：源码必须解压放在ESP-IDF安装文件夹  Espressif 同一路径下，否则会报错

可以去前面新建的文本文档中查看。

       7.2打开VS Code，点左上方  文件 ->  打开文件夹

找到刚刚的路径，选择源码文件夹   xiaozhi-esp32   ，点击选择文件夹

然后点击左上方，也就是图片中红色方框内的图标，查看文件看看蓝色椭圆内的文件夹名字是否和源码文件夹 一致（不区分大小写），如果一致，那就下一步

8、连接数据线，设置硬件参数

              8.1、COM口

                如果你的开发板是和我一样有两个type c口，找到COM口，并用商家送的数据线或手机数据线连接COM口和电脑。

我的拓展板是买零件自己焊的，问了商家是等价于 面包板新版接线(WIFI) ，这里先卖个关子，下面设置硬件参数时（8.7小节）再详细说明。

        8.2、设置硬件参数

点击红色1号框内，ESP-IDF插件，显示如下图的界面后，推荐看上面黄色2号框内，底下蓝色3号框那一栏的图标和上面2号框是一一对应的，先点击白色下划线上方的 选择烧录方式

        8.3、烧录方式UART

        选择烧录方式，上方弹出选择第二个 UART

选择之后稍微等一下，然后看看底下那一栏，同样的五角星图标后面的方式是不是你选的 UART，

下面的也是一样的检查方式。

        8.4、选择正确的端口(串口)

        查看端口，右键单击windows开始菜单键，选择设备管理器，在设备管理器中打开端口，一般是CH343这个端口，我的是COM3，记住括号里的(COM3)，如果有多个，就拔掉连着开发板的数据线，看看少了哪一个，记住之后重新插上，再次确认变回来的那个和少的那个是不是一样的，记住它。

选择要使用的端口，在弹出的选项里选择你刚刚记住的COM口，我的只有一个COM3。

        8.5、开发板型号

        设置乐鑫设备目标，也就是开发板型号，我的是esp32s3，如果你买的是其它的，选同名的就行，不知道是哪个型号可以去找商家问问

        如果跳转出如图所示选项，选择第一个（红框内）

           8.6、检查以及配置

        检查底边栏，然后打开SDK配置编辑器，耐心等它加载完成，一次不成功就在右下角弹出的加载窗口点击蓝色按钮取消，然后多点几次左侧黄色下划线的SDK配置编辑器。打开右侧的界面后，找到并点击 Xiaozhi Assistant 。

        8.7、接线方式与屏幕

        找到Xiaozhi Assistant 后，其它不需要改动，因为连接的是官方服务器，直接用官方默认的就可以了。只有Board Type和OLED Type要改成你的开发板接线类型和屏幕类型。之前8.1小节的时候就卖了个关子，就是在这里了。      

像我的开发板问过商家得知是面包板新版接线（WiFi），屏幕分辨率128*32。如果屏幕分辨率不是128*32或者128*64，就选择第二个，面包板新版接线（WiFi）+LCD，其它开发板或者接线类型，请在自己的VS Code上截图对应区域，去询问商家。下方的OLED Type，如果你不清楚，请拍下你的整个开发板（包含屏幕）的照片，也去询问商家。

经历了这些硬件参数设置，终于到最后一步，编译烧录了，我终于要写完这玩意儿了。累人

9、开始编译，烧录固件，终端监视

最后这一步放在一起的原因，是VS Code上有个功能键，就是把这三个功能整合在一起了，如下图所示，就是这个小火苗图标（ESP-IDF:构建、烧录和监视），只要点一下就可以自动进行编译、烧录，最后在终端监视小智AI，非常的方便。如果你前面的步骤没有错误，文件的路径没有中文，xiaozhi-esp32源码文件夹没有放错位置（第7点），以及8.1-8.7小节没有错误，那剩下的事情就是慢慢等待编译和烧录完成，过程会耗时3-10分钟，耐心等待即可。    

也可以分开点构建项目（也就是编译固件），烧录项目，监视设备。如果你不想重新做第8点的话，就不要点彻底清理，点了的话会把之前设置的所有硬件参数全都清除掉。

点击监视设备或者三合一小火苗后，开发板上红色圆圈内的灯会闪烁，等待一会儿，就可以在终端监视小智AI了。

五、激活设备与配网

10、小智控制台和激活设备

     烧录完成连接官方服务器后，如果是没有激活过的小智AI或者在控制面板删除了设备，在打开后只会一直重复“请登录到控制面板添加设备，输入验证码：[你自己的验证码]”，屏幕也会显示这个验证码。在进入控制台激活设备之前，无法正常使用。

具体操作：打开下方的后台链接-> 点击蓝色按钮控制台 -> 手机号注册控制台账号 -> 点击蓝色按钮添加设备 -> 输入小智AI语音播报的验证码。

小智AI聊天机器人后台：https://xiaozhi.me/

先点下方的添加设备，才会弹出验证码窗口。

11、关于配网（连接wifi）

在上一步激活设备后或者部署本地服务器成功连接后，如果之前没有连接过WIFI或你手机的热点，就会自动跳出配网模式，如果已经连接过，想要自己重新配网，更改连接的WIFI，则要先点击重启键RST，在连接过程中再点击唤醒键BOOT，就会再次进入配网模式。

重启键RST，唤醒键BOOT如图：

进入配网模式后，手机连接热点xiaozhi-XXXX（XXXX是数字）后，一般会直接跳转到配网界面，就可以进入配网界面，为小智联网了。

没有自动跳转的话，下面有三个方法进入配网界面：

法一：点击手机通知跳出的“登录到WLAN网络”

法二：连接热点的手机直接点击那个连接上的热点，就可以进入配网界面，

法三;在连接热点的手机的浏览器上访问：192.168.4.1（都一样的），不过这个方法有可能加载不出网站，不稳定。

如果还不行，就按RST重启小智，重新进入配网模式，依旧不行的话，重新烧录一遍，或者找大佬问问吧。

下面是这个配网界面的介绍

附录

香草味的纳西妲喵，小智AI系列教程https://space.bilibili.com/1347891621/lists/5135223?type=season

小灰灰爱吃香菜版https://space.bilibili.com/399627927小智 AI 聊天机器人百科全书： https://xiaozhi.me/docs

小智AI聊天机器人常见问题Q&A ：https://xiaozhi.me/faq

VS Code官网地址：https://code.visualstudio.com/

ESP-IDF下载地址1：https://dl.espressif.com/dl/esp-idf/

打不开就换下面这个

ESP-IDF下载地址2：https://dl.espressif.com.cn/dl/esp-idf/

 xiaozhi-esp32源码以及Git安装包：（推荐UC网盘，非会员也不限速） UC网盘：https://drive.uc.cn/s/9ffea5613d424           提取码：Mgqm 夸克网盘：https://pan.quark.cn/s/2367111f9515        提取码：fYzk 百度网盘：https://pan.baidu.com/s/1RVp76fFR42qTf-sZIldB7Q         提取码：0000

 进入虾哥代码主页：https://github.com/78/xiaozhi-esp32