# mimiclaw

**Repository Path**: supowang/mimiclaw

## Basic Information

- **Project Name**: mimiclaw
- **Description**: > 基于 [memovai/mimiclaw](https://github.com/memovai/mimiclaw) v0.1.1 开源项目
> 本版本在原始项目基础上进行了多平台移植和中国网络环境适配
> 支持四个 ESP32 芯片平台：**ESP32-P4** / **ESP32-S3** / **ESP32** / **ESP32-C3**
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-04-03
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MimiClaw 多平台移植版 — 完整指南

> 基于 [memovai/mimiclaw](https://github.com/memovai/mimiclaw) v0.1.1 开源项目
> 本版本在原始项目基础上进行了多平台移植和中国网络环境适配
> 支持四个 ESP32 芯片平台：**ESP32-P4** / **ESP32-S3** / **ESP32** / **ESP32-C3**
> 更新日期：2026-04-03

---

## 目录

- [一、项目概述](#一项目概述)
- [二、相比原始开源项目的改动](#二相比原始开源项目的改动)
- [三、四平台硬件参数对比](#三四平台硬件参数对比)
- [四、四平台软件配置对比](#四四平台软件配置对比)
- [五、快速上手指南（通用流程）](#五快速上手指南通用流程)
- [六、各平台专项指南](#六各平台专项指南)
- [七、通信通道配置](#七通信通道配置)
- [八、串口 CLI 调试命令](#八串口-cli-调试命令)
- [九、常见问题与踩坑记录](#九常见问题与踩坑记录)
- [十、项目文件结构](#十项目文件结构)

---

## 一、项目概述

MimiClaw 是一个运行在 ESP32 芯片上的纯 C AI Agent 固件。它通过 QQ / 飞书 / WebSocket 与用户通信，调用大语言模型 API（Anthropic Claude / OpenAI 兼容 API），以 ReAct 模式执行多轮工具调用（网页搜索、文件读写、GPIO 控制、定时任务等），并将对话记忆持久化到 SPIFFS Flash 存储。

**本版本的主要改动：**
1. 从仅支持 ESP32-S3 扩展到支持 **4 个芯片平台**（ESP32-P4 / S3 / ESP32 / C3）
2. 将 Telegram 通道替换为 **QQ 通道**（适配中国网络环境）
3. 时区、LLM API 地址、时间源等适配中国使用场景
4. 大量内存优化和稳定性改善

---

## 二、相比原始开源项目的改动

### 2.1 新增文件

| 文件 | 用途 |
|------|------|
| `main/channels/qq/qq_bot.c` | QQ Bot 完整实现（~900行，WebSocket+REST） |
| `main/channels/qq/qq_bot.h` | QQ Bot 头文件 |
| `sdkconfig.defaults.esp32` | ESP32 平台 SDK 配置 |
| `sdkconfig.defaults.esp32c3` | ESP32-C3 平台 SDK 配置 |
| `sdkconfig.defaults.esp32p4` | ESP32-P4 平台 SDK 配置（含 esp_hosted SDIO） |
| `partitions_esp32.csv` | ESP32 分区表（4MB Flash，无 OTA） |
| `partitions_esp32c3.csv` | ESP32-C3 分区表（2MB Flash，无 OTA） |
| `partitions_esp32p4.csv` | ESP32-P4 分区表（16MB Flash，含 OTA） |
| `scripts/build_esp32.sh` | ESP32 构建脚本 |
| `scripts/build_esp32c3.sh` | ESP32-C3 构建脚本 |
| `scripts/build_esp32p4.sh` | ESP32-P4 构建脚本 |
| `docs/PORTING_CHANGELOG.md` | ESP32 移植变更日志 |
| `docs/PORTING_ESP32AIS.md` | ESP32AIS 移植方案文档 |
| `docs/PORTING_DIFF_REPORT.md` | 逐文件改动对比报告 |
| `docs/MULTI_PLATFORM_GUIDE.md` | 本文档 |

### 2.2 删除文件

| 文件 | 原因 |
|------|------|
| `main/channels/telegram/telegram_bot.c` | 替换为 QQ 通道 |
| `main/channels/telegram/telegram_bot.h` | 替换为 QQ 通道 |

### 2.3 修改文件汇总

| 文件 | 改动概要 |
|------|---------|
| `main/mimi_config.h` | 四级平台条件编译（核心改动最大，从 163→270 行） |
| `main/mimi.c` | 启动 banner 按平台显示、飞书条件编译、QQ 通道集成 |
| `main/CMakeLists.txt` | telegram→qq，`esp_driver_gpio`→`driver` |
| `main/idf_component.yml` | 添加 `esp_wifi_remote`（仅 P4） |
| `main/bus/message_bus.h` | `MIMI_CHAN_TELEGRAM`→`MIMI_CHAN_QQ` |
| `main/agent/agent_loop.c` | PSRAM 宏适配、C3 buffer 缩小、working status 条件编译 |
| `main/agent/context_builder.c` | 大 buffer 栈→堆分配、C3 尺寸缩小 |
| `main/llm/llm_proxy.c` | PSRAM 宏、C3 OOM 降级、OpenAI URL→dashscope |
| `main/channels/feishu/feishu_bot.c` | ws_send_frame 栈→堆、C3 buffer 缩小、WS 超时调整 |
| `main/cli/serial_cli.c` | telegram→qq、PSRAM 条件显示 |
| `main/tools/gpio_policy.h` | 四平台 GPIO 白名单 |
| `main/tools/gpio_policy.c` | C3 GPIO 屏蔽分支 |
| `main/tools/tool_get_time.c` | 时间源 telegram.org→baidu.com |
| `main/tools/tool_web_search.c` | C3 search buffer 缩小 |
| `main/tools/tool_registry.c` | Telegram→通用 |
| `main/tools/tool_cron.c` | Telegram→通用 |
| `main/cron/cron_service.c` | Telegram→通用 |
| `main/onboard/wifi_onboard.c` | Telegram→QQ 配网面板 |
| `main/onboard/onboard_html.h` | Telegram→QQ 配置页面 |
| `main/mimi_secrets.h.example` | Telegram→QQ 密钥模板 |
| `sdkconfig.defaults` | +FreeRTOS Timer 栈 4096 |

### 2.4 功能性变化（全平台）

这些改动与平台移植无关，是为中国网络环境做的适配：

| 改动 | 原始 | 当前 | 原因 |
|------|------|------|------|
| 时区 | `PST8PDT,M3.2.0,M11.1.0`（美西） | `CST-8`（中国） | 中国使用 |
| OpenAI API 地址 | `api.openai.com` | `coding.dashscope.aliyuncs.com` | 阿里千问 DashScope |
| 时间获取 URL | `api.telegram.org` | `www.baidu.com` | 国内可达 |
| 通信通道 | Telegram | **QQ**（C2C + 群聊） | 国内可用 |

### 2.5 核心 C 逻辑零改动

以下模块完全不需要修改，证明 MimiClaw 的架构具备良好的平台无关性：

WiFi 管理 (`wifi_manager.c`)、记忆存储 (`memory_store.c`)、会话管理 (`session_mgr.c`)、WebSocket 网关 (`ws_server.c`)、HTTP 代理 (`http_proxy.c`)、OTA 更新 (`ota_manager.c`)、技能加载 (`skill_loader.c`)、心跳服务 (`heartbeat.c`)、文件工具 (`tool_files.c`)、GPIO 工具 (`tool_gpio.c`)

---

## 三、四平台硬件参数对比

| 维度 | ESP32-P4 | ESP32-S3 | ESP32 | ESP32-C3 |
|------|---------|---------|-------|---------|
| **CPU** | 双核 RISC-V 400MHz | 双核 Xtensa LX7 240MHz | 双核 Xtensa LX6 240MHz | 单核 RISC-V 160MHz |
| **内部 SRAM** | 768 KB | ~512 KB | 520 KB | 400 KB |
| **PSRAM** | 32 MB (200MHz) | 8 MB Octal (80MHz) | 4 MB Quad (80MHz) | 无 |
| **Flash** | 16 MB QIO | 16 MB QIO | 4 MB DIO | 2 MB DIO |
| **WiFi** | 无（C6 slave 通过 SDIO） | 802.11 b/g/n | 802.11 b/g/n | 802.11 b/g/n |
| **蓝牙** | 无（C6 提供） | BLE 5.0 | BT 4.2 + BLE | BLE 5.0 |
| **控制台** | USB Serial/JTAG | USB Serial/JTAG | UART | UART |
| **OTA** | 支持（双分区） | 支持（双分区） | 不支持（单分区） | 不支持（单分区） |
| **定位** | 旗舰（资源最充裕） | 标准（原始目标） | 经济（PSRAM 减半） | 极限（无 PSRAM） |

---

## 四、四平台软件配置对比

### 4.1 内存缓冲与任务栈

| 参数 | ESP32-P4 | ESP32-S3 | ESP32 | ESP32-C3 |
|------|---------|---------|-------|---------|
| `MIMI_QQ_MAX_MSG_LEN` | 8192 | 4096 | 2048 | 1024 |
| `MIMI_QQ_POLL_STACK` | 16 KB | 12 KB | 10 KB | 10 KB |
| `MIMI_AGENT_STACK` | 32 KB | 24 KB | 16 KB | 12 KB |
| `MIMI_AGENT_MAX_HISTORY` | 30 | 20 | 10 | 2 |
| `MIMI_LLM_STREAM_BUF_SIZE` | 48 KB | 32 KB | 24 KB | 8 KB |
| `MIMI_CONTEXT_BUF_SIZE` | 24 KB | 16 KB | 12 KB | 6 KB |
| `MIMI_SESSION_MAX_MSGS` | 30 | 20 | 10 | 6 |
| `MIMI_OUTBOUND_STACK` | 16 KB | 12 KB | 10 KB | 6 KB |
| `MIMI_LLM_MAX_TOKENS` | 4096 | 4096 | 4096 | 2048 |

### 4.2 Agent 行为参数

| 参数 | ESP32-P4 | ESP32-S3 | ESP32 | ESP32-C3 |
|------|---------|---------|-------|---------|
| `MIMI_HAS_PSRAM` | 1 | 1 | 1 | **0** |
| `MIMI_DUAL_CORE` | 1 | 1 | 1 | **0** |
| `MIMI_AGENT_CORE` | 1 | 1 | 1 | **0** |
| `MIMI_AGENT_MAX_TOOL_ITER` | 10 | 10 | 10 | **3** |
| `MIMI_MAX_TOOL_CALLS` | 4 | 4 | 4 | **1** |
| `MIMI_AGENT_SEND_WORKING_STATUS` | 1 | 1 | 1 | **0** |
| `MIMI_ENABLE_FEISHU` | 1 | 1 | 1 | **0** |

### 4.3 分区表对比

| 分区 | ESP32-P4 (16MB) | ESP32-S3 (16MB) | ESP32 (4MB) | ESP32-C3 (2MB) |
|------|----------------|----------------|-------------|---------------|
| nvs | 24 KB | 24 KB | 16 KB | 16 KB |
| otadata | 8 KB | 8 KB | - | - |
| phy_init | 4 KB | 4 KB | 4 KB | 4 KB |
| app (ota_0) | 3 MB | 2 MB | 1.625 MB (factory) | 1.3 MB (factory) |
| app (ota_1) | 3 MB | 2 MB | - | - |
| spiffs | 9.75 MB | ~12 MB | 2.25 MB | 640 KB |
| coredump | 64 KB | 64 KB | 64 KB | - |

### 4.4 GPIO 白名单

| 平台 | 可用 GPIO 范围 | 排除引脚 |
|------|--------------|---------|
| ESP32-P4 | 0-53 | 14-19 (SDIO→C6), 24-31 (Flash/PSRAM), 54 (C6 Reset) |
| ESP32-S3 | 1-46 | 19-20 (USB), 26-32 (Flash/PSRAM), 33-37 (内部) |
| ESP32 | 2-33 | 0 (BOOT), 1/3 (UART), 6-11 (Flash), 34-39 (仅输入) |
| ESP32-C3 | 0-10 | 11 (VDD_SPI), 12-17 (Flash/JTAG), 18-19 (USB) |

### 4.5 通信通道

| 通道 | ESP32-P4 | ESP32-S3 | ESP32 | ESP32-C3 |
|------|---------|---------|-------|---------|
| QQ Bot | 启用 | 启用 | 启用 | 启用 |
| 飞书 Bot | 启用 | 启用 | 启用 | **禁用** (省内存) |
| WebSocket | 启用 | 启用 | 启用 | 启用 |
| Serial CLI | 启用 | 启用 | 启用 | 启用 |

### 4.6 验证状态

| 平台 | 编译 | QQ 通道 | 飞书 | LLM 调用 | Web Search | 备注 |
|------|------|--------|------|---------|-----------|------|
| ESP32-P4 | 通过 | 通过 | 通过 | 通过 | 通过 | 全功能验证通过（P4 v1.3 芯片） |
| ESP32-S3 | 通过 | 通过 | 通过 | 通过 | 通过 | 原始平台 |
| ESP32 | 通过 | 通过 | 通过 | 通过 | 通过 | 双通道同时在线 |
| ESP32-C3 | 通过 | 通过 | 禁用 | 通过 | 通过 | 简单问题正常，复杂问题受限 |

---

## 五、快速上手指南（通用流程）

### 5.1 环境准备

**前置条件：**
- ESP-IDF v5.5+ 已安装并激活（[安装指南](https://docs.espressif.com/projects/esp-idf/zh_CN/v5.5.3/esp32/get-started/index.html)）
- 目标芯片的工具链已安装
- Git、Python 3、CMake、Ninja 可用

```bash
# 确认 ESP-IDF 环境已激活
idf.py --version
# 应输出类似: ESP-IDF v5.5.3

# 如果只装了 S3 工具链，需要为其他芯片补装：
cd $IDF_PATH
./install.sh esp32,esp32c3,esp32p4   # 按需选择
```

### 5.2 克隆项目

```bash
git clone <本项目仓库地址>
cd mimiclaw
```

### 5.3 配置密钥

```bash
# 复制密钥模板
cp main/mimi_secrets.h.example main/mimi_secrets.h

# 用你喜欢的编辑器打开
vim main/mimi_secrets.h    # 或 nano / VS Code / 其他编辑器
```

> ⚠️ `mimi_secrets.h` 已被 `.gitignore` 排除，不会被提交到 Git 仓库，你的密钥是安全的。

模板文件中有详细的注释说明每个字段的含义和获取方式。以下是各配置项的详细指导：

#### 5.3.1 WiFi 配置 [必填]

```c
#define MIMI_SECRET_WIFI_SSID       "你的WiFi名"
#define MIMI_SECRET_WIFI_PASS       "你的WiFi密码"
```

- 填入你的 2.4GHz WiFi 名称和密码（不支持 5GHz）
- 如果留空，设备启动后会进入**配网模式**：创建 `MimiClaw-XXXX` 开放热点，手机连接后打开 `http://192.168.4.1` 在网页上配置
- 也可以烧录后通过串口 CLI 命令修改：`set_wifi <SSID> <Password>`

#### 5.3.2 LLM 大语言模型 API [必填，二选一]

MimiClaw 支持两种 LLM API，选择其中一种即可：

**方式 A：OpenAI 兼容 API — 阿里千问 DashScope（推荐国内用户，无需代理）**

1. 注册阿里云账号并开通 DashScope：https://dashscope.console.aliyun.com/
2. 进入「API-KEY 管理」，点击「创建新的 API-KEY」
3. 复制 Key（以 `sk-` 开头）

```c
#define MIMI_SECRET_API_KEY         "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
#define MIMI_SECRET_MODEL           "qwen-plus"       /* 推荐 qwen-plus 性价比最高 */
#define MIMI_SECRET_MODEL_PROVIDER  "openai"           /* 固定填 "openai" */
```

可选模型：`qwen-turbo`（最快最便宜）、`qwen-plus`（推荐）、`qwen-max`（最强）

**方式 B：Anthropic Claude API（需要海外网络或代理）**

1. 注册 Anthropic：https://console.anthropic.com/
2. 进入 Settings → API Keys，创建 Key
3. 如果在国内，需要配置 HTTP 代理（见 5.3.6）

```c
#define MIMI_SECRET_API_KEY         "sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
#define MIMI_SECRET_MODEL           "claude-sonnet-4-20250514"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"        /* 固定填 "anthropic" */
```

可选模型：`claude-haiku-4-20250414`（最快）、`claude-sonnet-4-20250514`（推荐）、`claude-opus-4-5`（最强）

> 💡 烧录后也可以通过串口 CLI 切换模型，无需重编译：
> ```
> set_model_provider openai
> set_model qwen-plus
> set_api_key sk-xxxxxxxx
> restart
> ```

#### 5.3.3 QQ Bot [选填]

通过 QQ 与 MimiClaw 对话，支持单聊（C2C）和群聊（@机器人）。

**获取步骤：**

1. 登录 [QQ 开放平台](https://q.qq.com/)
2. 点击「创建机器人」
3. 填写机器人基本信息，提交审核
4. 在应用详情页找到 **AppID** 和 **AppSecret**
5. 沙箱模式可直接测试，正式发布需通过审核

```c
#define MIMI_SECRET_QQ_APP_ID       "102012345"
#define MIMI_SECRET_QQ_APP_SECRET   "abcdefghijklmnop1234567890"
```

留空则 QQ 通道不启用，不影响其他通道。

> 💡 串口 CLI 也可设置：`set_qq_creds <AppID> <AppSecret>`

#### 5.3.4 飞书 Bot [选填]

通过飞书与 MimiClaw 对话，使用 WebSocket 长连接模式，**无需公网 IP**。

**获取步骤：**

1. 登录[飞书开放平台](https://open.feishu.cn/)，创建「企业自建应用」
2. **添加应用能力** → 选择「机器人」
3. **权限管理** → 开通以下权限：
   - `im:message`（接收消息）
   - `im:message:send_as_bot`（以机器人身份发送消息）
4. **事件与回调** → 事件订阅方式选择「**长连接**」
5. 添加事件订阅：`im.message.receive_v1`（接收消息）
6. 在「凭证与基础信息」中获取 **App ID** 和 **App Secret**
7. **创建版本** → **申请发布**（审核通过后机器人上线）

```c
#define MIMI_SECRET_FEISHU_APP_ID   "cli_a1234567890abcde"
#define MIMI_SECRET_FEISHU_APP_SECRET "abcdefghijklmnopqrstuvwxyz123456"
```

> ⚠️ ESP32-C3 平台上飞书通道被自动禁用（内存不足），仅 QQ 可用。

留空则飞书通道不启用。

> 💡 串口 CLI 也可设置：`set_feishu_creds <AppID> <AppSecret>`

#### 5.3.5 网页搜索 API [选填]

让 MimiClaw 能搜索互联网获取实时信息（天气、新闻、技术文档等）。

**推荐 Tavily（免费 1000 次/月，注册即用）：**

1. 注册 [Tavily](https://app.tavily.com/home)（支持 Google/GitHub 登录）
2. 登录后在 Dashboard 页面复制 API Key（以 `tvly-` 开头）

```c
#define MIMI_SECRET_TAVILY_KEY      "tvly-xxxxxxxxxxxxxxxxxxxxxxxx"
```

**备选 Brave Search（需信用卡验证）：**

```c
#define MIMI_SECRET_SEARCH_KEY      "BSAxxxxxxxxxxxxxxxxxxxxxxxx"
```

两个都配置时优先使用 Tavily。都不配置则 `web_search` 工具不可用（不影响其他功能）。

> 💡 串口 CLI 也可设置：`set_tavily_key <Key>`

#### 5.3.6 HTTP 代理 [选填]

仅在需要访问海外 API（如 Anthropic Claude）时配置。使用阿里千问等国内 API 时无需代理，留空即可。

```c
#define MIMI_SECRET_PROXY_HOST      "192.168.1.100"   /* 代理服务器地址 */
#define MIMI_SECRET_PROXY_PORT      "7890"            /* 代理端口 */
#define MIMI_SECRET_PROXY_TYPE      "http"            /* "http" 或 "socks5" */
```

> 💡 串口 CLI 也可设置：`set_proxy <host> <port> [http|socks5]`
> 清除代理：`clear_proxy`

#### 5.3.7 最小配置示例

如果你只想快速体验，只需配置 WiFi + LLM API 两项即可：

```c
/* 最小配置：WiFi + 阿里千问 */
#define MIMI_SECRET_WIFI_SSID       "MyWiFi"
#define MIMI_SECRET_WIFI_PASS       "MyPassword"
#define MIMI_SECRET_API_KEY         "sk-xxxxxxxxxxxxxxxx"
#define MIMI_SECRET_MODEL           "qwen-plus"
#define MIMI_SECRET_MODEL_PROVIDER  "openai"
```

烧录后通过串口 CLI 或配网页面（`http://192.168.4.1`）补充其他配置。

### 5.4 编译和烧录

**通用流程（所有平台一致）：**

```bash
# 1. 删除旧配置（切换平台必须）
del sdkconfig        # Windows
# rm sdkconfig       # Linux/macOS

# 2. 设置目标芯片
idf.py set-target <芯片名>

# 3. 编译
idf.py build

# 4. 烧录 + 打开串口监控
idf.py -p <COM端口> flash monitor
```

其中 `<芯片名>` 和 `<COM端口>` 按实际填：

| 平台 | `<芯片名>` | 典型 `<COM端口>` |
|------|-----------|----------------|
| ESP32-P4 | `esp32p4` | COM5（USB-JTAG） |
| ESP32-S3 | `esp32s3` | COM3（USB-JTAG） |
| ESP32 | `esp32` | COM4（UART/CH340） |
| ESP32-C3 | `esp32c3` | COM6（UART/CH340） |

### 5.5 验证启动

烧录成功后，串口输出应类似：

```
I mimi: ========================================
I mimi:   MimiClaw - ESP32 AI Agent          ← 显示你的芯片平台
I mimi: ========================================
I mimi: Internal free: 257223 bytes
I mimi: PSRAM free:    4192024 bytes          ← 有 PSRAM 的平台显示
...
I mimi: WiFi connected: 10.150.21.67
I qq: QQ Bot READY (session=xxx)              ← QQ 已连接
I feishu: Feishu WS connected                 ← 飞书已连接（C3 无此行）
I mimi: All services started!
I mimi: MimiClaw ready. Type 'help' for CLI commands.
```

用 QQ 或飞书给机器人发消息测试。

---

## 六、各平台专项指南

### 6.1 ESP32-S3（标准平台，推荐新手）

```bash
del sdkconfig
idf.py set-target esp32s3
idf.py build
idf.py -p COM3 flash monitor
```

**特点：** 原始目标平台，资源最充裕（16MB Flash + 8MB PSRAM），所有功能完整支持。

**适合硬件：** ESP32-S3-DevKitC-1、ESP32-S3-LCD-1.47B、Waveshare ESP32-S3 等。

### 6.2 ESP32（经济方案）

```bash
del sdkconfig
idf.py set-target esp32
idf.py build
idf.py -p COM4 flash monitor
```

**特点：** 4MB Flash 无 OTA，2.25MB SPIFFS，4MB PSRAM 够用。QQ + 飞书双通道同时在线。

**适合硬件：** ESP32AIS、ESP32-WROOM-32、ESP32-DevKitC 等带 PSRAM 的模组。

**注意事项：**
- 控制台通过 UART（非 USB），需外部 USB-TTL 转接器（如 CH340/CP2102）
- 无 OTA，固件更新需要有线烧录
- 固件编译后约 1.2MB，分区上限 1.625MB，余量 26%

### 6.3 ESP32-C3（极限移植）

```bash
del sdkconfig
idf.py set-target esp32c3
idf.py build
idf.py -p COM6 flash monitor
```

**特点：** 无 PSRAM 仅 400KB SRAM，单核 160MHz。仅启用 QQ 通道（飞书禁用以省内存）。

**适合硬件：** ESP32-C3-32S、ESP32-C3-DevKitM-1、合宙 ESP32-C3 等。

**已知限制：**
- 简单对话（不需要 web_search）完美运行
- 需要多轮 tool call 的复杂问题（如天气查询需要 time+search+回答 3 轮）受 `MAX_TOOL_ITER=3` 限制
- 飞书通道被禁用以节省 ~18KB 内存
- 会话历史仅保留 2 条（vs S3 的 20 条）

**C3 专属踩坑记录：**
- `CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN` 必须 >= 8192（Tavily/DashScope TLS record 可达 8-12KB）
- `CONFIG_LWIP_MAX_SOCKETS` 不能低于 10（HTTP server 内部占 3 个）
- 修改 `sdkconfig.defaults.esp32c3` 后必须 `del sdkconfig` + `idf.py set-target esp32c3` 才能重新生成
- 所有 >256 字节的栈局部变量必须改 heap 分配，否则栈溢出

### 6.4 ESP32-P4（旗舰方案，实验性）

```bash
del sdkconfig
idf.py fullclean                    # P4 首次建议 fullclean
idf.py set-target esp32p4
idf.py build
idf.py -p COM5 flash monitor
```

**特点：** 双核 RISC-V 400MHz + 32MB PSRAM + 16MB Flash，资源最强。WiFi 通过 ESP32-C6 slave 芯片（SDIO 接口）提供。

**适合硬件：** JC1060P470C_I_W_Y 模组（谷泰微电子）及其他 P4+C6 组合方案。

**重要——C6 Slave 固件烧录（仅需一次）：**

P4 模组上的 ESP32-C6 芯片需要单独烧录 slave 固件：

1. 找到 C6 slave 固件：`JC-C6-slave_v2.3.2.bin`（模组资料包 `8-Burn operation/Burn files/` 目录下）
2. 使用 `flash_download_tool` 或 `esptool.py` 烧录到 C6：
   - 芯片选择 ESP32-C6
   - 烧录地址 0x0
   - 波特率 115200 或 460800
3. 烧录完成后 C6 自动运行 slave 程序，无需任何操作

**SDIO 引脚连接（硬件已焊好，无需配置）：**

| 信号 | GPIO |
|------|------|
| CLK | 18 |
| CMD | 19 |
| D0 | 14 |
| D1 | 15 |
| D2 | 16 |
| D3 | 17 |
| C6 Reset | 54 (高电平有效) |

---

## 七、通信通道配置

> 详细的获取步骤和配置方法见 [5.3 配置密钥](#53-配置密钥)，本章仅补充技术细节。

### 7.1 QQ Bot

配置方法见 [5.3.3](#533-qq-bot-选填)。

**QQ 通道技术细节：**
- 鉴权：AppID + AppSecret → Access Token（7200s 有效期，自动刷新）
- 消息接收：WebSocket 长连接（QQ 官方 WSS 网关）
- 消息发送：HTTP REST API（被动回复优先，失败自动回退主动消息）
- 被动回复窗口：单聊 60 分钟，群聊 5 分钟

### 7.2 飞书 Bot

配置方法见 [5.3.4](#534-飞书-bot-选填)，更多细节参考 [docs/im-integration/FEISHU_SETUP.md](im-integration/FEISHU_SETUP.md)。

### 7.3 Web Search（Tavily）

配置方法见 [5.3.5](#535-网页搜索-api-选填)，更多细节参考 [docs/tool-setup/TAVILY_SETUP.md](tool-setup/TAVILY_SETUP.md)。

### 7.4 WiFi 配网门户

如果没有预先配置 WiFi 密码（`mimi_secrets.h` 中留空），设备会自动进入配网模式：

1. 设备创建热点 `MimiClaw-XXXX`（开放网络）
2. 手机连接该热点
3. 浏览器打开 `http://192.168.4.1`
4. 在配网页面填写 WiFi 名、密码、API Key 等
5. 点击「Save & Restart」

WiFi 连接成功后，配网热点仍然保持运行（管理模式），可以随时修改配置。

---

## 八、串口 CLI 调试命令

连接串口终端（115200 波特率），输入 `help` 查看所有命令：

| 命令 | 功能 |
|------|------|
| `wifi_status` | 显示 WiFi 连接状态和 IP 地址 |
| `heap_info` | 显示内部 SRAM 和 PSRAM 可用内存 |
| `memory_read` | 读取 MEMORY.md 内容 |
| `session_list` | 列出所有会话文件 |
| `session_clear <chat_id>` | 清除指定会话 |
| `config_show` | 显示当前配置（密钥脱敏） |
| `config_reset` | 清除所有 NVS 运行时配置 |
| `set_qq_creds <app_id> <secret>` | 设置 QQ 凭据（无需重编译） |
| `set_feishu_creds <app_id> <secret>` | 设置飞书凭据 |
| `set_tavily_key <key>` | 设置 Tavily API Key |
| `restart` | 重启设备 |

---

## 九、常见问题与踩坑记录

### Q: 切换芯片平台后编译报错？

**A:** 必须删除 `sdkconfig` 再 `set-target`：

```bash
del sdkconfig           # 关键！不删会用旧配置
idf.py set-target <芯片名>
idf.py build
```

如果还报错，尝试 `idf.py fullclean` 后重来。

### Q: ESP32-P4 bootloader 报 tool_version_check 错误？

**A:** `idf.py fullclean` 后重新 `set-target` + `build` 即可。这是 ESP-IDF 的缓存问题。

### Q: QQ 消息发送返回 400 错误？

**A:** 代码中已内置 fallback 机制——被动回复（带 msg_id）失败时会自动去掉 msg_id 重试主动消息。如果主动消息也失败，检查 QQ 机器人的审核状态和权限配置。

### Q: ESP32-C3 上 web_search 后 OOM？

**A:** C3 的 `MAX_TOOL_ITER=3` 限制了最多 3 轮 tool call。需要多轮搜索的复杂问题（如天气查询）可能无法完成。这是 400KB SRAM 无 PSRAM 的硬约束。简单问题（如「你叫什么名字」）完全正常。

### Q: TLS 连接错误 -0x7100 或 -0x7200？

**A:** `-0x7100` 是服务端断开连接（偶发网络问题），agent 会自动重试。`-0x7200` 是 TLS record 太大，需确保 `MBEDTLS_SSL_IN_CONTENT_LEN >= 8192`。

### Q: 飞书连不上？

**A:** 飞书使用 WebSocket 长连接模式（ESP32 主动连接飞书服务器），无需公网 IP。检查：1) App 是否已创建版本并发布；2) 是否开启了「长连接」事件订阅模式；3) 凭据是否正确。

### Q: 如何使用 Anthropic Claude API（需要代理）？

**A:** 见 [5.3.2 方式 B](#532-llm-大语言模型-api-必填二选一) 和 [5.3.6 HTTP 代理](#536-http-代理-选填)。或者直接使用阿里千问，无需代理。

---

## 十、项目文件结构

```
mimiclaw/
├── CMakeLists.txt                  # 项目根 CMake
├── sdkconfig.defaults              # 通用默认配置
├── sdkconfig.defaults.esp32s3      # ESP32-S3 平台配置
├── sdkconfig.defaults.esp32        # ESP32 平台配置
├── sdkconfig.defaults.esp32c3      # ESP32-C3 平台配置
├── sdkconfig.defaults.esp32p4      # ESP32-P4 平台配置（含 SDIO）
├── partitions.csv                  # ESP32-S3 分区表 (16MB)
├── partitions_esp32.csv            # ESP32 分区表 (4MB)
├── partitions_esp32c3.csv          # ESP32-C3 分区表 (2MB)
├── partitions_esp32p4.csv          # ESP32-P4 分区表 (16MB)
│
├── main/
│   ├── mimi.c                      # 入口 app_main()
│   ├── mimi_config.h               # 全局配置（四平台条件编译）
│   ├── mimi_secrets.h              # 密钥文件（gitignored）
│   ├── mimi_secrets.h.example      # 密钥模板
│   ├── idf_component.yml           # 组件依赖
│   ├── CMakeLists.txt              # 源文件注册
│   │
│   ├── agent/                      # AI Agent 核心
│   │   ├── agent_loop.c/h          # ReAct 循环（最多 10 轮 tool call）
│   │   └── context_builder.c/h     # 系统提示构建
│   │
│   ├── channels/                   # 通信通道
│   │   ├── qq/qq_bot.c/h           # QQ Bot（WebSocket + REST）
│   │   └── feishu/feishu_bot.c/h   # 飞书 Bot（WebSocket 长连接）
│   │
│   ├── llm/llm_proxy.c/h          # LLM API 调用（Anthropic + OpenAI 双协议）
│   ├── bus/message_bus.c/h         # FreeRTOS 消息总线
│   ├── memory/                     # 记忆与会话
│   ├── tools/                      # AI 工具（12 个）
│   ├── wifi/wifi_manager.c/h       # WiFi STA 管理
│   ├── onboard/                    # WiFi 配网门户
│   ├── cli/serial_cli.c/h          # 串口 REPL
│   ├── gateway/ws_server.c/h       # WebSocket 网关 (:18789)
│   ├── cron/cron_service.c/h       # 定时任务
│   ├── heartbeat/heartbeat.c/h     # 心跳服务
│   ├── proxy/http_proxy.c/h        # HTTP CONNECT 隧道
│   ├── skills/skill_loader.c/h     # SPIFFS 技能文件加载
│   └── ota/ota_manager.c/h         # OTA 更新
│
├── spiffs_data/                    # 初始 SPIFFS 内容（烧录到 Flash）
│   ├── config/SOUL.md              # AI 人格定义
│   ├── config/USER.md              # 用户档案模板
│   ├── memory/MEMORY.md            # 长期记忆（AI 自主写入）
│   └── skills/                     # 4 个预置技能
│
├── scripts/                        # 构建脚本
│   ├── build_esp32.sh / build_esp32c3.sh / build_esp32p4.sh
│   ├── build_macos.sh / build_ubuntu.sh
│   └── setup_idf_macos.sh / setup_idf_ubuntu.sh
│
├── docs/                           # 文档
│   ├── ARCHITECTURE.md             # 架构设计文档
│   ├── MULTI_PLATFORM_GUIDE.md     # 本文档
│   ├── PORTING_*.md                # 移植记录
│   ├── im-integration/             # 飞书配置指南
│   └── tool-setup/                 # Tavily 配置指南
│
└── assets/                         # README 图片
```

---

## 附录：一键编译命令速查

```bash
# ESP32-S3
del sdkconfig && idf.py set-target esp32s3 && idf.py build && idf.py -p COM3 flash monitor

# ESP32
del sdkconfig && idf.py set-target esp32 && idf.py build && idf.py -p COM4 flash monitor

# ESP32-C3
del sdkconfig && idf.py set-target esp32c3 && idf.py build && idf.py -p COM6 flash monitor

# ESP32-P4
del sdkconfig && idf.py fullclean && idf.py set-target esp32p4 && idf.py build && idf.py -p COM5 flash monitor
```