故障排查
常见问题
在哪里获取 ESP-Mosaico 的 esp-claw 出厂固件？
ESP-Mosaico 的扩展子板能否在左右两侧互换插接？
目前摄像头模块仅支持插入左侧，支持热插，不支持热拔。 若插到右侧，请关机、拔下、插到左侧、开机。 其他拓展模块支持参考https://github.com/esp-mosaico/esp-mosaico-bsp#expansion-modules 第三方拓展子板兼容性需实际验证。
如何让 ESP-Mosaico 进入下载模式？
按住 BOOT 键，然后开机。进入下载模式后，屏幕保持黑屏是正常现象。
当前 ESP-Mosaico 套装是否包含摄像头？
包含。当前套装提供官方 SC101IOT DVP 摄像头子板；它是随套装提供的独立模块，不是主机板载摄像头。
ESP-Mosaico 板上是否自带外部存储？容量是多少？
主板带板载 NAND。先行版和 v1.2 版本均使用 128MB NAND Flash。
ESP-Mosaico 如何识别磁吸方向？
内部使用两颗 BMM150 地磁传感器组成检测矩阵，可识别四个方向的磁吸状态。
ESP-Mosaico 是否内置电池，后续如何扩展续航？
主体内置 65 mAh 锂电池；后续计划开源配套的容量为 900mAh 的背挂电池模块以提高续航。
ESP-Mosaico 多功能交互子板是否自带外壳，能否自行打印外壳？
ESP-Mosaico 多功能交互子板外壳文件可见：https://makerworld.com.cn/zh/models/3012963-esp-mosaico-mo-kuai-jiao-hu?appSharePlatform=copy#profileId-3539338 ，用户可以自行打印。
ESP-Mosaico 的扩展模块使用什么接口？
当前主机左右扩展接口采用 2×10 Pin、2.54 mm 间距的双排排母。
DeepSeek 能参与 ESP-Mosaico 的开发吗？
可以。用户可使用 DeepSeek 等 AI Agent，参考 esp-mosaico-vibe 仓库进行 ESP-Mosaico 的开发。 但目前尚未提供 DeepSeek 专用插件或一键配置支持。
ESP-Mosaico 有麦克风和喇叭吗？
有。当前先行版主机板载 1 个麦克风，并标配喇叭。
ESP-Mosaico 的产品重量是多少？
ESP-Mosaico 的产品重量约为 31.7 g。
ESP-Claw 的教程和源码在哪里？
教程：https://legacy.docs.esp-claw.com/zh-cn/tutorial/ 源码仓库：https://github.com/espressif/esp-claw/tree/legacy
ESP-Mosaico 有哪些物理按键？
共有三个物理按键：USB 接口右侧是开关机键，左侧是 BOOT 键，顶部右侧是 AI 功能键。
在哪里查看 ESP-Mosaico 的入门指南、软件开发参考、恢复出厂固件页面和 FAQ？
可通过以下入口查看： • ESP-MOsaico 快速入门指南：https://mosaico.espressif.com/zh/guide/ ； • ESP-Mosaico 软件开发参考：https://github.com/esp-mosaico/esp-mosaico-vibe ； • ESP-Mosaico 恢复出厂固件：https://mosaico.espressif.com/zh/firmware-update/ ； • ESP-Mosaico 的 FAQ：https://mosaico.espressif.com/zh/guide/faq/ 。
ESP-Claw 是运行在服务器上，还是运行在 ESP-Mosaico 设备中？
ESP-Claw 运行在 ESP-Mosaico 设备中，大语言模型运行在模型服务商
如何访问 ESP-Mosaico 的 Web 控制页面？
• 当没有配网时连接设备的热点后浏览器访问 192.168.4.1 进入 • 当设备已配网，让访问 Web 页面的手机或电脑与 ESP-Mosaico 连接到同一局域网，然后在浏览器中输入 ESP-Mosaico 的局域网 IP 地址。 通过如下方式获取 IP 地址： 1、在 esp-mosaico 的 setting 页面，进入 Network 下设置 WiFi 连接2、连接 WiFi 后，可以在 setting —— AI Model 下获取 esp-mosaico 连接 WiFi 的 IP 地址 ，或者直接用手机微信扫描 IP 地址旁边的二维码进入Web 控制页面
通过 QQ 与 ESP-Claw 交互时，如何开启一个新会话？
在 QQ 中默认会沿用同一个会话。需要开启新会话时，发送 /session new。长时间使用同一会话后，较早的对话内容可能会被遗忘。相关说明：https://esp-claw.com/zh-cn/tutorial/first-interactions/
ESP-Mosaico 主固件版本与 ESP-Claw 组件版本不同，是否说明升级失败？
不一定。ESP-Mosaico 主固件基于ESP-Claw开发，但是有自己的版本号，主固件与组件版本不要求相同。应分别查看对应版本，不能仅凭二者版本不同就判定升级失败；是否成功还应核对目标固件及升级后的实际运行情况。
ESP-Mosaico 出厂固件的网页实时日志入口在哪里？旧版本没有入口怎么办？
v0.4.0 版本以上的出厂固件的网页控制台左侧提供 Log／实时日志入口。旧版页面没有该入口时，可从 https://mosaico.espressif.com/zh/firmware-update/ 更新到包含该功能的固件。排查语音识别时，先打开日志，再触发一次识别，收集当次报错；日志用于定位问题，不表示更新固件就能解决所有语音故障。
ESP-Mosaico 的 ESP-Claw 可以连接自己部署的模型服务吗？
可以配置自建的模型服务，但服务需提供所用 ESP-Claw 后端支持的兼容接口。例如 OpenAI 或 Anthropic 兼容接口。填写对应服务地址、模型名称及所需的 API Key，并确保设备能够访问该服务。模型仍运行在提供接口的主机上，不是把模型文件部署到 ESP-Mosaico 上。
用电脑给 ESP-Mosaico 烧录固件时，可以用 USB-C 转 USB-C 线吗？
可以，关键是线缆支持数据传输。USB-C 转 USB-C 数据线可以使用，但只有充电功能的线缆不能用于烧录。连接后与 USB-A 转 USB-C 线一样的使用方法
ESP-Mosaico 多功能交互子板的 PIR 人体感应信号接到哪个 GPIO？
参见 ESP-Mosaico 多功能交互子板（https://docs.espressif.com/projects/esp-dev-kits/zh_CN/latest/esp32s31/esp-mosaico/user_guide_interact.html#esp-mosaico）说明，插在左侧 H2 时 PIR 对应 GPIO4，插在右侧 H1 时对应 GPIO5。PIR 使用 AS312，输出运动检测电平。接线与开发应按实际插槽查表，不能把同一个 GPIO 编号套用到两侧。
ESP-Mosaico 烧录自制游戏固件后，为什么重启仍进入游戏，不能退出到原出厂界面？
把游戏作为原生应用固件烧录后，设备启动的是该固件，这不是在原出厂界面中额外安装一个可退出的游戏。需要原出厂功能时，应通过 https://mosaico.espressif.com/zh/firmware-update/ 安装相应出厂固件。ESP-Claw 内的 Lua／Skill 扩展是另一种开发方式，不能把两种方式的安装与退出行为混为一谈。
ESP-Mosaico 的 Vibe Mode、Recovery 和 BOOT 下载模式有什么区别？
Vibe Mode 是设备的应用安装与维护模式；Recovery 是这一保留固件所用的技术名称。设备上有Vibe Mode固件时，可按住 AI 键上电进入 Vibe Mode。BOOT 下载模式也就是 ROM 下载模式，运行芯片内置的下载程序。
如何把 ESP-Mosaico 固件以支持无线烧录的形式上传到 Ideas？
将固件打包为 .irisfw 包，在 Ideas 上传固件时选择“添加 Iris 固件”，附上该文件并完成提交。使用无线更新时，目标设备需要已安装并运行Vibe mode固件；普通 .bin 文件不能仅通过改扩展名变成 Iris 固件包。提交审核与审核通过是不同状态，上传完成后应查看实际提交状态。
ESP-Mosaico 出厂固件项目的源码在哪里？
ESP-Mosaico 出厂固件项目源码位于 https://github.com/esp-mosaico/esp-mosaico-claw 。需要自行编译时，按所选源码提交的 README 和依赖要求准备 ESP-IDF 与子模块。
ESP-Mosaico 出厂固件能否只改 API Key 或配置文件，就接入未预设的语音识别服务？
不能仅靠更换 API Key 或修改地址就让出厂固件支持一个尚未适配的 ASR 服务。应使用固件已经实现的服务商适配；接入其他服务商时，需要修改源码，实现其鉴权、音频传输和识别结果处理，再编译验证。ASR 接口不能直接按大语言模型的兼容接口来替换。
ESP-Mosaico v1.0 和 v1.2 应如何连接配套背挂充电模块？
配套充电模块按 v1.2 的背部触点设计；v1.0 可以通过 USB 接口连接。
在哪里访问 ESP-Mosaico Ideas 点子中心？
入口是 https://mosaico-ideas.espressif.com/ 。ESP-Mosaico 官网的“点子中心”页面也提供了这个链接，可从中查找社区创意应用。
从哪里查看 ESP-Mosaico 上 ESP-Claw 的串口日志？
可以通过设备右侧扩展接口中的 UART（TX/RX）查看设备的串口日志。
ESP-Mosaico 是否同时支持经典蓝牙和低功耗蓝牙？
支持。ESP-Mosaico 的 ESP32-S31 主控支持经典蓝牙（BT，BR/EDR）和低功耗蓝牙（BLE）。硬件具备这些能力，不等于每个固件都提供配对界面或全部蓝牙 Profile；具体可用功能要核对所用固件。
同一份固件需要兼容 ESP-Mosaico v1.0 和 v1.2 时，是否需要更新 BSP？
需要同一份固件兼容两版时，应核对并更新到包含相应适配的 BSP，由 BSP 识别硬件版本并处理对应差异。