M5Stack CoreS3 跑 ESP-Claw AI Agent：板级配置、16MB 双 OTA 分区与避坑实战

本文面向手持 M5Stack CoreS3、想把它变成 AI 语音 Agent 的嵌入式开发者，基于 esp-claw 仓库中 boards/m5stack/m5stack_cores3 板级适配源码与 partitions_16MB.csv 分区表，完整拆解环境搭建、板卡选择、编译烧录、电源管理操作、16MB 双 OTA 分区机制与常见故障排查，帮你避开 CoreS3 上已知的启动循环、黑屏、SD 卡冲突等坑。

1. 概述

1.1 什么是 ESP-Claw

ESP-Claw 是乐鑫（Espressif）开源的 ESP32 边缘 AI Agent 固件框架：一块 ESP32 芯片即可运行完整的 Agent，内置 Lua 技能系统、事件路由、记忆模块与 MCP 工具调用能力，通过 Wi-Fi 接入大模型（GPT、Qwen、Claude、DeepSeek 等），支持 Telegram、QQ、飞书等 IM 通道。硬件门槛为至少 8 MB Flash 与 8 MB PSRAM，目前支持 ESP32-S3 与 ESP32-P4。

1.2 为什么选择 M5Stack CoreS3

CoreS3 是一块“开箱即用”的集成形态开发板，无需面包板搭电路：屏幕、触摸、麦克风、扬声器、电源管理全部板载。它满足 ESP-Claw 的全部硬件门槛：

• ESP32-S3 双核 240 MHz，16 MB QIO Flash（80 MHz）
• 8 MB Quad PSRAM（80 MHz）
• 2.0 英寸 320x240 电容触摸屏（ILI9341 兼容面板 + FT5x06 触摸）
• AW88298 功放（扬声器输出）+ ES7210 编解码器（双麦克风输入）
• AXP2101 电源管理单元 + AW9523B IO 扩展器，软件可逐路控制外设供电
• 板载 USB Serial/JTAG，一根 USB-C 线完成烧录与日志

1.3 核心特性

esp-claw 仓库 boards/m5stack/m5stack_cores3/ 目录（版本 1.0.0，本文基于 2026-10 的 master 分支）提供了完整的声明式板级适配：

• 声明式板级配置：board_info.yaml、board_peripherals.yaml、board_devices.yaml 三件套描述全部硬件
• 自动板卡适配：idf.py bmgr 一条命令选择板卡，无需 set-target
• 16 MB 分区自动选择：构建系统按 Flash 容量自动套用 partitions_16MB.csv（双 5 MB OTA 槽）
• 电源逐路控制：LCD、触摸、扬声器、SD、5V Grove 输出均可软件开关
• 双 FAT 分区：只读 system 种子分区 + 可写 storage 分区，出厂技能与用户数据分离

2. 环境准备与安装

2.1 硬件清单

物品	规格要求	说明
M5Stack CoreS3	16 MB Flash + 8 MB PSRAM 的标准版	无 PSRAM 或小 Flash 的变体不满足门槛
USB-C 数据线	必须支持数据传输	CoreS3 板载 USB Serial/JTAG，烧录与日志走同一根线
2.4 GHz Wi-Fi	需要外网访问	设备需调用云端 LLM API
扬声器	CoreS3 板载	由 AW88298 驱动，无需外接

2.2 软件环境搭建

ESP-Claw 推荐使用 ESP-IDF v5.5.4（以下命令在激活的 ESP-IDF 终端中执行，Windows 下推荐 ESP-IDF 5.5 CMD/PowerShell 环境）：

# 激活 ESP-IDF 环境（路径换成你的安装位置）
. ~/esp/esp-idf/export.sh

# 安装板卡管理器辅助包（每个 IDF 环境只需一次）
pip install esp-bmgr-assist

# 获取源码
git clone https://github.com/espressif/esp-claw.git
cd esp-claw/application/edge_agent

2.3 验证安装

列出所有受支持的开发板，确认 m5stack_cores3 在列表中：

idf.py bmgr -c ./boards -l

预期输出（节选）：

...
m5stack_cores3
m5stack_sticks3
m5stack_tab5
...

若该命令报 bmgr 不是可用的子命令，说明 esp-bmgr-assist 未安装到当前 IDF Python 环境，重新执行 pip install esp-bmgr-assist。

3. 快速上手

3.1 选择开发板

在 application/edge_agent 目录下执行：

idf.py bmgr -c ./boards -b m5stack_cores3

该命令解析板级三件套 YAML，在 components/gen_bmgr_codes/ 下生成板卡支持代码（含 board_manager.defaults，记录了 16 MB Flash 等板级配置）。无需 idf.py set-target——芯片型号由板卡管理器自动推断。

3.2 编译与烧录

可选步骤：先通过 menuconfig 填写默认参数（Wi-Fi、LLM API Key 等，路径 (Top) → App Claw Config）：

idf.py menuconfig
idf.py build
idf.py flash monitor

构建日志中应能看到分区表自动选择的确认行：

[edge_agent] Partition table auto-selected: partitions_16MB.csv

完整的构建-烧录操作链路如下：

流程执行说明：

• 板卡选择（步骤 1-3）：bmgr 只需执行一次；切换其他板卡时重新执行即可，生成物在 components/gen_bmgr_codes/
• 构建（步骤 4-5）：CMake 脚本读取 board_manager.defaults 中的 Flash 容量，自动写入分区表选择，日志中打印确认行
• 烧录（步骤 6）：一次性写入 bootloader（0x0）、分区表（0x9000）、应用（ota_0 槽）与两个 FAT 文件系统镜像
• 监控（步骤 7）：idf.py monitor 挂接 USB Serial/JTAG 控制台，退出快捷键为 Ctrl+]

3.3 首次配置向导

不想从源码编译的用户，也可以使用官方在线烧录工具（Chrome/Edge 浏览器打开 ESP-Claw 文档站的“在线烧录”页面，WebSerial 直连），在烧录完成后按向导完成：

• 配置 Wi-Fi SSID 与密码（若向导未弹出，可连接设备 SoftAP 热点进入 Web 配置页）
• 配置 LLM 提供商 与 API Key（推荐选用推理能力较强的模型，自编程与复杂工具组合依赖强推理能力）
• 可选配置 IM Bot Token、搜索引擎 Key、时区

4. 功能操作详解

4.1 板级配置三件套

boards/m5stack/m5stack_cores3/ 目录共 11 个文件，核心是三个声明式 YAML：

文件	作用	关键内容
board_info.yaml	板卡身份	board=m5stack_cores3，chip=esp32s3，厂商 M5Stack
board_peripherals.yaml	总线与简单 GPIO	I2C0、I2S0、SPI2、功放使能 GPIO46
board_devices.yaml	具体芯片设备	AW9523B、AXP2101、AW88298、ES7210、屏幕、触摸

普通用户基本不需要改动这些文件；理解它们有助于排查外设问题。目录中其余文件：setup_device.c（设备工厂函数）、power_manager.c/h（电源管理）、sdkconfig.defaults.board（板级 sdkconfig）、components/esp_io_expander_aw9523b/（AW9523B 驱动组件，经由 override_path 本地覆盖）。

4.2 外设总线与引脚分配

CoreS3 板级定义中的总线引脚如下（来自 board_peripherals.yaml）：

总线	引脚	参数
I2C0（主）	SDA=12，SCL=11	挂接全部外设芯片
I2S0 输出	MCLK=0，BCLK=34，WS=33，DOUT=13	48 kHz，16 bit，立体声
I2S0 输入	DIN=14	与输出共享同一份配置（YAML 锚点复用）
SPI2（主）	MOSI=37，MISO=35，SCLK=36	max_transfer_sz=3600
GPIO	46	功放使能（输出、上拉）

4.3 设备拓扑与 I2C 地址表

board_devices.yaml 声明的设备清单：

设备名	芯片	类型	总线/地址	备注
gpio_expander	AW9523B	IO 扩展器	I2C 0xb0	16 脚，控制各路外设电源使能
axp2101_power_manager	AXP2101	custom	I2C 0x34	400 kHz，管理各路 LDO 输出
audio_dac	AW88298	audio_codec	I2C 0x6c	仅 DAC，1 通道输出
audio_adc	ES7210	audio_codec	I2C 0x80	4 通道 ADC，启用 2 路麦克风
display_lcd	ILI9341 兼容面板	display_lcd	SPI（CS=3，DC=35）	40 MHz，sio 单线模式
lcd_touch	FT5x06 系	lcd_touch	I2C 0x70	400 kHz
fs_sdcard	-	fs_fat	SPI（CS=4）	默认注释禁用，见 7.3 节

屏幕配置有两个 CoreS3 专属细节：invert_color: true（注释明确标注“Required for M5Stack CoreS3 LCD”），以及 sio_mode: true（SPI 单线 IO 模式，MOSI 兼作数据线，因此 MISO=35 实际复用为 DC 引脚）。

4.4 电源管理操作

CoreS3 的外设供电不直接由 ESP32 GPIO 控制，而是经 AW9523B 扩展器与 AXP2101 PMU 两级管理。power_manager.h 暴露了六个可独立开关的功能：

typedef enum {
    CORES3_POWER_MANAGER_FEATURE_LCD,      /* LCD 显示 */
    CORES3_POWER_MANAGER_FEATURE_TOUCH,    /* 触摸屏 */
    CORES3_POWER_MANAGER_FEATURE_5V,       /* Grove 口 5V 输出 */
    CORES3_POWER_MANAGER_FEATURE_SD,       /* SD 卡 */
    CORES3_POWER_MANAGER_FEATURE_SPEAKER,  /* 扬声器 */
    CORES3_POWER_MANAGER_FEATURE_CAMERA,   /* 摄像头 */
} cores3_power_manager_feature_t;

调用 cores3_power_manager_enable(handle, feature) 即可逐路使能。以 Grove 5V 输出为例，内部需要同时拉高 AW9523B 的两个引脚：

/* AW9523 P0_1 (pin 1)  = BUS_EN   */
/* AW9523 P1_7 (pin 15) = BOOST_EN */
err |= esp_io_expander_set_level(exp, (1u << 15), 1);
err |= esp_io_expander_set_level(exp, (1u << 1),  1);

扬声器供电更复杂：先经 I2C 写 AXP2101 的 ALDO1（1V8，功放 PVDD）、ALDO2/ALDO3（3V3，编解码器与麦克风），再拉高扩展器 pin 2。设备初始化阶段的上电时序如下：

流程执行说明：

• 模式修正（步骤 2-3）：AW9523B 复位后默认处于 LED 恒流模式，直接写高电平只能放开灌电流、无法真正驱动使能信号，所以必须先把 P0/P1 切成 GPIO 模式（这是官方适配中专门修过的坑）
• 分级上电（步骤 4-6）：五路外设各间隔 100 ms 依次上电，避免瞬间浪涌
• 背光最后开（步骤 7）：DLDO1 电压寄存器写完后屏幕才亮，黑屏排查时可据此判断卡在哪一步

4.5 音频链路

CoreS3 的音频是“双芯片”架构：AW88298 只做播放（DAC），ES7210 只做录音（ADC），共用一组 I2S 引脚但方向不同。YAML 中用锚点 &i2s0_config 与引用 *i2s0_config 保证输入输出配置严格一致——48 kHz 采样率、16 bit 位宽、立体声、MCLK 256 倍频。功放另有独立的使能脚 GPIO46（上拉输出），用于静音控制。

4.6 显示与触摸

UI 由 LVGL 驱动，默认主屏是一个时钟界面：时间按 HH:MM 格式显示，下方附带星期与日期，由 1 秒周期的 lv_timer 驱动刷新（时间未同步时显示 --:-- 占位）。触摸走 FT5x06 I2C 驱动，分辨率与屏幕一致（320x240）。屏幕镜像（mirror_x/mirror_y）与颜色反转都可在 board_devices.yaml 的 display_lcd 节点调整。

4.7 控制台与日志

CoreS3 板级配置强制使用 USB Serial/JTAG 作为唯一控制台：

CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y
CONFIG_ESP_CONSOLE_SECONDARY_NONE=y

操作要点：日志与烧录走同一根 USB-C 线；Windows 设备管理器中表现为“USB 串行设备(COM x)”。若插上后看到两个串口，选与 ESP32 关联的那个。Agent 各阶段的事件通知粒度可在 menuconfig 中调整（Component config → ESP-Claw Core → Agent stage notification verbosity），需要把工具调用进度推送到 IM 时选 Verbose。

5. 配置与定制

5.1 16MB 分区表详解

application/edge_agent/partitions_16MB.csv 全文如下：

# Name,    Type, SubType, Offset,   Size
nvs,       data, nvs,     0xA000,   0x6000
otadata,   data, ota,     0x10000,  0x2000
phy_init,  data, phy,     0x12000,  0x1000
ota_0,     app,  ota_0,         ,   5M
ota_1,     app,  ota_1,         ,   5M
system,    data, fat,           ,   2600K
storage,   data, fat,           ,   3M

各分区的职责（分区表本身位于 0x9000，0x0-0x9000 为 bootloader 保留区）：

分区	偏移/大小	挂载点	职责
nvs	0xA000 / 24 KB	-	键值配置存储（Wi-Fi、API Key 等运行时配置）
otadata	0x10000 / 8 KB	-	OTA 启动槽位选择数据
phy_init	0x12000 / 4 KB	-	射频校准数据
ota_0	5 MB	-	应用固件槽 A（出厂烧录目标）
ota_1	5 MB	-	应用固件槽 B（OTA 升级目标）
system	2600 KB	/system	只读种子分区：内置技能、Lua 脚本、静态资源
storage	3 MB	/fatfs	可写用户数据分区，可被运行时格式化并从 /system 重新播种

设计动机：双 5 MB OTA 槽保证升级失败可回滚；system 与 storage 分离让“恢复出厂”只需重格式化 storage，出厂技能永不丢失。

5.2 分区表自动选择机制

edge_agent 的基础 sdkconfig.defaults 默认指向 partitions_8MB.csv，CoreS3 却要用 16MB 表——衔接靠 application/edge_agent/tools/cmake/flash_partition_defaults.cmake：

• 构建时读取 components/gen_bmgr_codes/board_manager.defaults 中的 CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
• 清掉 sdkconfig 里已有的分区表文件名配置，避免旧选择残留
• 生成 build/edge_agent_partition_auto.defaults，写入 CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_16MB.csv" 并追加进 SDKCONFIG_DEFAULTS
• 在构建日志打印 [edge_agent] Partition table auto-selected: partitions_16MB.csv

因此不要手工改 sdkconfig 里的分区表文件名——每次构建都会按 Flash 容量重选。要换分区布局，正确做法是改板级 sdkconfig.defaults.board 中的 Flash 容量声明（或参考其他板卡的做法，直接在板级 defaults 中显式指定分区文件名）。

5.3 板级 sdkconfig 定制

sdkconfig.defaults.board 是 CoreS3 专属的构建配置，当前内容集中解决“Quad PSRAM 的限制”：

# 16MB QIO Flash @ 80MHz / 8MB Quad PSRAM @ 80MHz / CPU 240MHz
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
CONFIG_SPIRAM_MODE_QUAD=y
CONFIG_SPIRAM_SPEED_80M=y

# XIP 需要八线 PSRAM，CoreS3 为四线，全部关闭
CONFIG_SPIRAM_XIP_FROM_PSRAM=n
CONFIG_SPIRAM_FETCH_INSTRUCTIONS=n
CONFIG_SPIRAM_RODATA=n

# Flash 擦写期间 cache 关闭，Quad PSRAM 无法保持栈访问，
# 强制任务栈分配在内部 RAM
CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=n
CONFIG_MDNS_TASK_CREATE_FROM_INTERNAL=y

这份配置是 CoreS3 曾经“启动循环”问题的修复成果（详见 7.1 节），新增 CONFIG_ 项时建议追加在此文件而非全局 defaults，保持板卡间互不干扰。

5.4 FATFS 系统分区覆盖

板卡可以在自己的目录下放置 fatfs_image/，构建时叠加到 system 分区镜像上，同名文件覆盖基础镜像中的版本：

application/edge_agent/boards/m5stack/m5stack_cores3/fatfs_image/
└── （按 system 分区内的相对路径放置你的文件）

典型用途：为 CoreS3 替换默认主屏资源、预置专属技能脚本，而不触碰共享的基础镜像。基础镜像源在 application/edge_agent/fatfs_image/{system,storage}/。注意板级覆盖只作用于 system（只读）分区，隐藏目录不会被计入。

6. 使用技巧与最佳实践

• 善用 NVS 运行时配置：Wi-Fi、LLM Key 等改动走 Web 配置页即可，不必重编译烧录
• 在线烧录默认不擦整个 Flash，版本更新后 NVS 配置保留；彻底重置时才在高级选项里勾选全片擦除
• CoreS3 有两个常见“假故障”先自查：用了充电线（无数据功能）导致无串口；长按电源键关机后以为固件损坏
• 修改板级 YAML 后重新执行 idf.py bmgr -c ./boards -b m5stack_cores3 再 build，生成物才会刷新
• 技能与 Lua 脚本放 system 分区（只读、恢复出厂不丢），用户产生的数据才会进 storage
• 需要把 Agent 执行进度推送 IM 时，把通知粒度调到 Verbose 并配合事件路由规则

7. 常见问题与故障排除

7.1 启动循环（bootloop）

现象：设备反复重启，日志中出现 mDNS 或网络相关任务的栈溢出/异常。根因：Quad PSRAM 在 Flash 擦写事务期间无法保持任务栈可访问，早期版本中 mDNS 任务栈分配在 PSRAM 导致崩溃（官方已以提交 153cb6f7 修复）。若你自行裁剪配置后复发，确认这两项未被改回：

CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM=n
CONFIG_MDNS_TASK_CREATE_FROM_INTERNAL=y

7.2 屏幕黑屏

按以下顺序排查：

• 供电链：LCD 使能走 AW9523B pin 9，背光走 AXP2101 DLDO1（寄存器 0x90 使能、0x99 电压），两者任一失败都会黑屏
• 软件配置：invert_color: true 是 CoreS3 必需项，误关后画面近乎全黑
• SPI 占用：确认没有同时启用 SD 卡（见 7.3 节）
• 串口看日志：若启动日志能走到 Initializing power_manager device 之后仍黑屏，优先怀疑 DLDO1 写入失败（I2C 异常）

7.3 SD 卡与 LCD 冲突

board_devices.yaml 中 SD 卡设备整段被注释禁用，注释原文说明了原因：SD 卡与 LCD 共享 SPI 资源，同时使用会导致 SD 挂载失败甚至程序崩溃。板级注释同时提醒：AW9523B 的 pin 1/pin 5 拉低时可经 Grove/DC 口供电，但同样会触发 SD+LCD 并用的崩溃问题。需要 SD 卡扩展存储时，只能二选一：启用 SD 并放弃屏幕，或改用网络存储方案。

7.4 串口与烧录问题

• 找不到串口：换数据线（而非充电线）、换 USB 口；设备管理器确认“USB 串行设备”存在
• 端口被占用：关闭其他 monitor/putty 会话；Windows 上 tasklist | findstr -i python 排查残留的 monitor 进程
• 烧录后无输出：CoreS3 控制台固定在 USB Serial/JTAG，若日志空白先确认没有同时开 UART 输出的旧配置
• idf.py monitor 退出快捷键是 Ctrl+]（Windows ESP-IDF 环境下）

7.5 Grove 5V 无输出

Grove 口 5V 需要 AW9523B 的 BUS_EN（pin 1）与 BOOST_EN（pin 15）同时为高。两个易踩的坑：只拉了其中一个；或 AW9523B 仍处于默认 LED 恒流模式（此时“写高”并不能真正输出高电平）。固件正常路径会在初始化时完成模式切换，如果你在应用层直接操作扩展器发现拉不高，参考 setup_device.c 中 io_expander_factory_entry_t 的三步初始化（GCR 推挽 + LEDMODE0/1 切 GPIO）。

8. 实战案例

8.1 案例一：从源码到第一次对话

• 准备：ESP-IDF v5.5.4 环境已激活，CoreS3 经 USB-C 连接主机
• 执行 pip install esp-bmgr-assist（一次性）
• idf.py bmgr -c ./boards -b m5stack_cores3，确认生成 components/gen_bmgr_codes/
• idf.py menuconfig：在 App Claw Config 中填入默认 LLM 提供商与 API Key（也可留空，烧录后经 Web 配置）
• idf.py build：确认日志出现 [edge_agent] Partition table auto-selected: partitions_16MB.csv
• idf.py flash monitor：等待启动完成，屏幕出现时钟主屏
• 在 Web 配置页完成 Wi-Fi 与 LLM 绑定后，对设备说话或经 IM 下发消息，即可开始第一次对话
• 验证成功标志：日志出现 Agent 阶段事件，扬声器播放 TTS 回复

8.2 案例二：OTA 双槽升级

16MB 表的两个 5 MB 应用槽是 OTA 的基础，升级流程如下：

流程执行说明：

• 双槽互备（步骤 2-4）：运行中的槽只读，新固件永远写空闲槽，升级中断不影响当前系统
• 先验证后生效（步骤 7-9）：新版本首次启动处于“待验证”状态，自验证通过才正式切换；失败则自动回滚到旧槽
• 运行时可用的存储：/system（只读技能库）与 /fatfs（可写用户区）不受 OTA 影响

9. 总结

• M5Stack CoreS3 是 ESP-Claw 支持度最完整的集成形态板卡之一：屏幕、触摸、双麦、扬声器、电源管理全板载，16 MB Flash + 8 MB PSRAM 满门槛
• 板级适配完全声明式：三件套 YAML + idf.py bmgr 一条命令完成选板，无需 set-target
• 16MB 分区表由构建系统按 Flash 容量自动选择，双 5 MB OTA 槽 + system/storage 双 FAT 分离是可靠升级与“恢复出厂”的基石
• CoreS3 的 Quad PSRAM 有硬限制：任务栈必须留在内部 RAM，相关 sdkconfig 不要随意“优化”掉
• 最大的硬件坑是 SD 卡与 LCD 的 SPI 冲突，以及 AW9523B 默认 LED 模式导致的 5V/GPIO“拉不高”问题

不适合的场景：无 PSRAM 或 8 MB 以下 Flash 的板子（如部分 Lite 变体）无法运行；需要本地大模型推理的场合请选择更高配置平台。

参考文献

[0] M5Stack CoreS3 跑 ESP-Claw AI Agent：板级配置、16MB 分区表与避坑实战：https://my.feishu.cn/wiki/Jo3Kw3Tu9inOAEkAzP2c122UnNc

[1] ESP-Claw 官方文档（在线烧录/从源码编译）：https://esp-claw.espressif.com/

[2] ESP-Claw 源码仓库：https://github.com/espressif/esp-claw

[3] ESP-IDF v6.0 安装指南（实际安装 v5.5.4）：https://docs.espressif.com/projects/esp-idf/zh_CN/v6.0/esp32s3/get-started/index.html

[4] ESP Board Manager 开发板适配文档：https://docs.espressif.com/projects/esp-board-manager/zh_CN/latest/create-board/index.html

[5] ESP-IDF 分区表文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32s3/api-guides/partition-tables.html