ESP-Claw启动流程剖析：从NVS到Agent就绪的完整链路

本章剖析 ESP-Claw 从上电到 Agent 就绪的完整启动链。固件入口是 application/edge_agent/main/main.c 中区区 426 行的 app_main()，但它以严格的先后次序串起了 NVS、配置服务、板级管理器、文件系统、双根路径、网络、应用外壳七层初始化。本章以代码真实顺序为骨架，回答三个问题：启动顺序为什么这样排、app_claw 为什么被称为“组合根”、启动失败时固件如何降级而不是死机。读完本章，读者应能独立画出这条启动链，并说清每一步的前置依赖。

1. 启动链总览：顺序由依赖决定

1.1 app_main 的时序骨架

app_main() 开头先用两行 esp_log_level_set() 压低 esp-x509-crt-bundle、http_reuse 两个高噪声库的日志级别，随后打印三段版本号（claw_get_version()、claw_get_git_version()、edge_agent_get_version()）——这是售后排障的第一手信息。此后才是真正的初始化序列，全部压缩在一个函数里，骨架如下（省略与回调表细节）：

ESP_ERROR_CHECK(app_allocate_runtime_state());      // 分配启动期两份配置结构
ESP_ERROR_CHECK(init_nvs());                        // 1. NVS 自愈初始化
ESP_ERROR_CHECK(app_config_init());                 // 2. 打开 NVS 命名空间 "app"
ESP_ERROR_CHECK(app_config_load(s_config));         // 3. 默认值 + NVS 覆盖
app_config_to_claw(s_config, s_claw_config);        // 4. 映射为外壳运行时配置
init_timezone(app_config_get_timezone(s_config));   // 失败回落 CST-8，不致命
ESP_ERROR_CHECK(esp_board_manager_init());          // 5. 板级设备初始化（含 SD 卡探测）
ESP_ERROR_CHECK(app_fs_init());                     // 6. /system、存储分区、/ramfs
/* 发布解析后的存储根：任何组件无需关心数据在 flash 还是 SD 卡（原注释意译） */
ESP_ERROR_CHECK(claw_paths_set(CLAW_PATH_DATA, app_fs_storage_base_path()));
ESP_ERROR_CHECK(claw_paths_set(CLAW_PATH_SYSTEM, app_fs_system_base_path()));
ESP_ERROR_CHECK(wifi_manager_init());               // 7. Wi-Fi 资源初始化（不连接）
ESP_ERROR_CHECK(app_claw_ui_start());               // 8. 系统 UI 先起，状态才有处可显
ESP_ERROR_CHECK(http_server_init(&(http_server_config_t) { /* 服务回调表 */ }));
/* ……wifi_manager_start()、app_claw_start() 详见后文 …… */
register_wifi_command();                            // CLI 增补 Wi-Fi 调试命令
app_free_runtime_state();                           // 释放启动期临时结构

注意一个显眼的对比：序列前半段每行都套着 ESP_ERROR_CHECK（失败即 abort），而从 wifi_manager_start() 开始出现大量“仅告警、继续走”的分支。这不是风格不一致，而是刻意的分水岭——前半段失败则 Agent 外壳无从谈起，后半段失败只是“功能面变小”。第 7 章将系统化这一策略。

1.2 依赖分析：为什么顺序不能调换

启动顺序不是编码习惯，而是依赖图的拓扑排序：

• 存储先于数据服务：app_config 的键值、Wi-Fi 凭据都存放在 NVS 分区，而配置又是时区、Wi-Fi、能力白名单的输入，所以 NVS 与配置必须排最前；
• 板级先于文件系统：app_fs_init() 依赖 esp_board_manager_init() 探测并挂载 SD 卡，storage_sdcard_mount_point() 只有在板级管理器运行后才可能返回有效挂载点（app_fs.h 注释明确写了这条前置条件）；
• 文件系统先于路径发布：claw_paths_set() 需要真实的挂载点字符串（/fatfs 或 SD 卡挂载点），挂载顺序决定了路径的最终取值；
• 路径发布先于 app_claw：app_claw_start() 的第二步就是 build_storage_paths()，它调用 claw_paths_join() 组合出记忆、技能、路由规则等全部工作目录；claw_paths.h 注明逻辑根“应在任何读者运行之前的早期启动阶段一次性设定”；
• UI 先于 Wi-Fi 启动：Wi-Fi 状态回调会调用 app_claw_set_network_status() 刷新界面网络状态，因此 app_claw_ui_start() 必须先于 wifi_manager_start()；
• 网络是异步软依赖：app_claw_start() 完全不等待网络，时间同步服务以 network_ready = NULL 启动，内部自行等待联网——这是“网络异步化”设计的落点。

流程执行说明：

• 持久化阶段（步骤 1-2）：init_nvs() 遇脏分区先擦除重建，随后 app_config_init()/app_config_load() 产出一份“Kconfig 默认值 + NVS 覆盖”的 app_config_t；
• 存储与路径阶段（步骤 3-6）：esp_board_manager_init() 与 app_fs_init() 完成三级挂载，recover_missing_files() 把 /system/.recovery 种子补进数据分区，claw_paths_set() 把两个物理挂载点发布为逻辑根；
• 网络阶段（步骤 7-10，含 alt/else 降级）：Wi-Fi 初始化、UI 启动、HTTP 服务器初始化依次完成后 wifi_manager_start() 异步发起连接；已配置 SSID 时等待最多 30 秒，成功则打印 IP，超时或无凭据则告警降级、保持配网门户可用；
• 能力装配阶段（步骤 11-13）：app_claw_start() 先解析存储路径，再经 app_capabilities_init() 与 app_lua_modules_register() 按 Kconfig 与运行时白名单两级过滤装配能力组与 Lua 模块；
• Agent 就绪阶段（步骤 14-16）：claw_agent_mgr_init() 携带上下文提供者数组创建根代理，随后异步时间同步、app_claw_cli_start() 启动控制台 REPL，最后 app_claw_publish_startup_event() 广播启动完成事件。

2. 持久化先行：NVS 与 app_config

2.1 NVS 的自愈初始化

init_nvs() 是整个启动链的第一块基石，它处理了 NVS 分区“脏污”的两种情况：

static esp_err_t init_nvs(void)
{
    esp_err_t err = nvs_flash_init();
    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
        ESP_ERROR_CHECK(nvs_flash_erase());  // 分区脏污：擦除后重来
        err = nvs_flash_init();
    }
    return err;
}

ESP_ERR_NVS_NO_FREE_PAGES 通常意味着掉电时写入了一半，ESP_ERR_NVS_NEW_VERSION_FOUND 意味着固件更换了 NVS 布局版本。两者的对策都是“擦除重建”：代价是丢掉全部持久化配置，换来的是“设备一定能起来”的确定性。配置丢失后 app_config_load() 会落到 Kconfig 默认值，配网门户重新出现，用户重新配置即可——这是一条典型的自愈降级路径。紧随其后的 init_timezone() 也遵循同样的哲学：时区字符串为空或非法时直接 assert(setenv("TZ", "CST-8", 1)) 回落默认时区，注释明确写着“无需检查错误”。

2.2 配置 schema 与 NVS 存储

app_config 组件（详见第12章《板级适配与配置服务》）定义了固件唯一的持久化 schema。app_config_init() 只做两件事：以命名空间 "app" 打开 NVS 设置存储，并把旧版本固件的 LLM 键迁移到新键名：

esp_err_t app_config_init(void)
{
    esp_err_t err = settings_store_init(&(settings_store_config_t) {
        .namespace_name = "app",
    });
    if (err != ESP_OK) {
        return err;
    }
    return app_config_upgrade_legacy_llm_settings();  // 迁移旧版 LLM 配置键
}

app_config_t 的 schema 是清一色的定长字符数组，没有一个指针字段：

typedef struct {
    char wifi_ssid[APP_CONFIG_STR_LEN];   // Wi-Fi/AP 凭据与 AP 行为
    char llm_api_key[APP_CONFIG_STR_LEN]; // LLM 后端、模型与采样参数
    char llm_model[64];
    char qq_app_id[32];                   // QQ/飞书/TG/微信等 IM 通道令牌
    char search_brave_key[APP_CONFIG_STR_LEN];      // 搜索服务密钥
    char enabled_cap_groups[APP_CONFIG_STR_LEN];    // 启动时装配的能力组白名单
    char llm_visible_cap_groups[APP_CONFIG_STR_LEN]; // 对 LLM 可见的能力组
    char enabled_lua_modules[APP_CONFIG_STR_LEN];   // 启用时注册的 Lua 模块
    char time_timezone[APP_CONFIG_TIMEZONE_LEN];
} app_config_t;   // 节选，完整定义见 app_config.h

定长数组不是偷懒：整个结构体可以被当作一块连续 blob 校验、拷贝、写回 NVS，不需要任何动态分配，结构体大小在编译期完全确定。默认值由 Kconfig.projbuild 提供（如 APP_WIFI_SSID = CONFIG_APP_WIFI_SSID），因此同一份固件可以通过 menuconfig 预置出厂默认，再由 NVS 在运行期覆盖。特别注意最后三个字段——能力组与 Lua 模块的“启动开关”本身就是普通配置项，这构成了第 5 章要展开的运行期第二级裁剪。

2.3 配置闭环：从 NVS 到运行时再写回

配置在启动时单向流入运行时：app_config_to_claw() 把扁平的 app_config_t 映射为 app_claw_config_t。两个结构高度相似但不重合——后者还包含 asr_* 等仅运行期使用的字段，main.c 里专门有一个 main_copy_claw_to_app_config() 做反向的逐字段 strlcpy。启动后配置形成一条完整闭环：

• 读取方向：NVS → app_config_load() → app_config_to_claw() → app_claw_start(s_claw_config)；
• 写回方向一（HTTP 配网页面）：main_save_config() 先 app_config_validate_wifi() 校验，再 app_config_save() 落盘，最后构造临时 app_claw_config_t 调 app_claw_update_config() 热更新运行时；
• 写回方向二（外壳内部改配置）：app_claw 通过 main 在启动前注册的回调 app_claw_set_save_config_callback(main_save_claw_config, NULL)，由 main_save_claw_config() 重新加载一份最新 app_config_t、仅覆盖 LLM 相关字段后写回 NVS。

NVS 是唯一事实源，两份运行时结构都只是它的投影；任何一侧的修改最终都要落回 NVS，重启后状态才不丢失。

3. 存储装配与双根路径

3.1 app_fs_init：三级挂载顺序

app_fs_init() 的三级挂载顺序固定为三步：只读 system 分区 → 可写存储分区 → RAMFS（仅 CONFIG_SPIRAM 存在时）。关键逻辑在第二步“存储分区选谁”：

const char *sd_mount = storage_sdcard_mount_point();
if (sd_mount) {
    strlcpy(s_storage_base_path, sd_mount, sizeof(s_storage_base_path));
    esp_err_t rec = recover_missing_files(recovery_path, s_storage_base_path);
    /* ……SD 卡优先：flash 存储分区此时不再挂载…… */
    return ESP_OK;
}
esp_vfs_fat_mount_config_t mount_config = {
    .format_if_mount_failed = true,   // flash 分区损坏则格式化重挂载
    /* ……max_files=8、allocation_unit_size=4096 …… */
};
esp_err_t err = esp_vfs_fat_spiflash_mount_rw_wl(s_flash_storage_base_path,
                                                        APP_FS_STORAGE_PARTITION_LABEL,
                                                        &mount_config, &s_wl_handle);
/* ……随后同样调用 recover_missing_files() 补种缺文件…… */

/system 由 esp_vfs_fat_spiflash_mount_ro() 只读挂载，存放固件烧制内容：内置技能、Lua 脚本与文档、以及恢复种子（app_fs.h 注释原话）。可写存储优先使用板级管理器已挂载的 SD 卡——此时活动根路径变成 SD 卡自己的挂载点，flash 存储分区根本不挂载；没有 SD 卡时退回 flash 上的 wear-leveling 分区，且 format_if_mount_failed = true 意味着分区损坏会被自动格式化重建。两条路径殊途同归：挂载完成后都执行一次 recover_missing_files()。app_fs_storage_base_path() 返回的“活动存储根”对上层完全屏蔽了这一差异。

3.2 .recovery 恢复种子机制

.recovery 是 ESP-Claw 数据自愈的核心。源码中的定义与约定：

static const char *const s_system_base_path = "/system";
static const char *const s_flash_storage_base_path = "/fatfs";
static const char *const s_ramfs_base_path = "/ramfs";
static const char *const s_recovery_dir_name = ".recovery";
// 以点前缀命名，cap_files 的 list_dir 会把种子树对 LLM 隐藏（原注释意译）

recover_missing_files() 的语义可以从代码注释完整读出：从源目录（/system/.recovery）向数据分区递归拷贝“目标侧缺失”的条目——新格式化的分区被重新播种，部分数据丢失被逐文件修补；已存在的文件一律不动，“即使其内容已损坏”，即用户数据永远优先于出厂种子；源目录缺失甚至不算错误，opendir() 失败只打一条告警就返回 ESP_OK，因为“没有东西可恢复”不阻塞任何事。该机制之所以可靠，在于种子放在只读的 system 分区：运行期任何代码都写不进它，等价于固件镜像里自带一份“出厂默认数据”。格式化自愈（上一节的 format_if_mount_failed）与种子恢复互相咬合：前者保证“一定有一个能用的文件系统”，后者保证“文件系统里一定有最小可用数据集”。

3.3 claw_paths：逻辑根抽象

存储挂载完成后，main.c 用两行代码完成了一次关键的抽象发布：

ESP_ERROR_CHECK(claw_paths_set(CLAW_PATH_DATA, app_fs_storage_base_path()));
ESP_ERROR_CHECK(claw_paths_set(CLAW_PATH_SYSTEM, app_fs_system_base_path()));

claw_paths.h 只定义两个逻辑根：CLAW_PATH_DATA（可写数据根，flash 分区或 SD 卡挂载点）与 CLAW_PATH_SYSTEM（固件烧制的只读根，如 /system）。下游全部通过 claw_paths_join(root, subpath, out, size) 组合路径。app_claw_start() 中的 build_storage_paths() 就是第一个消费者，它在 DATA 根下派生 sessions、memory、skills、scripts、router_rules/router_rules.json、scheduler/schedules.json、inbox，在 SYSTEM 根下派生只读 skills，结果装进 app_claw_storage_paths_t 结构，随后作为参数贯穿整个能力框架（见第7章《记忆系统》、第8章《技能系统》）。双根路径的收益是结构性解耦：更换 SD 卡、修改分区表、甚至把数据迁移到别的介质，只需要改 app_fs 一个文件，记忆、技能、事件路由、IM 收件箱等全部消费者零改动。

4. 网络异步化：不让 Wi-Fi 绑架启动

4.1 初始化顺序与状态回调

网络段的顺序同样讲究：wifi_manager_init()（只分配资源、不连接）→ app_claw_ui_start() → http_server_init() → 注册状态回调 → wifi_manager_start()。http_server_init() 注入的服务回调表把 HTTP 服务器与 main 层粘在一起：load_config/save_config 挂接配置服务，get_wifi_status 挂接 Wi-Fi 状态，restart_device 借 500 毫秒延迟任务实现“先应答再重启”，微信能力编译在内时还挂接扫码登录四件套。回调注册发生在 wifi_manager_start() 之前，保证启动后的第一次状态变化不会丢失：

static void on_wifi_state_changed(bool connected, void *user_ctx)
{
    wifi_manager_status_t status = {0};
    wifi_manager_get_status(&status);
    const char *ap_ssid = status.ap_active ? status.ap_ssid : NULL;
    ESP_LOGI(TAG, "Wi-Fi state: sta_connected=%d ap_active=%d ...", ...);
    esp_err_t err = app_claw_set_network_status(connected, ap_ssid); // 刷新 UI
    if (err != ESP_OK) {
        ESP_LOGW(TAG, "Failed to update network UI: %s", esp_err_to_name(err));
    }
}

这个回调也解释了为什么 UI 必须先于 Wi-Fi 启动：连接状态变化时，界面上要有一块“网络状态”可刷新。

4.2 30 秒等待窗口与降级分支

wifi_manager_start() 的返回值是整个启动链中第一个被“容忍”的错误——失败只打 ESP_LOGE，启动照常继续。成功分支内还有三层细颗粒降级：http_server_start() 之后 captive_dns_start() 失败仅告警（配网门户不会自动弹出，但可手动访问 IP）；仅在已配置 SSID 时调用 wifi_manager_wait_connected(30000) 等待 STA 连接，返回 ESP_OK 打印 IP，ESP_ERR_TIMEOUT 打一条“窗口内未连上，转入后台重试”的告警，其他错误同样只告警；最后若 AP 已激活，打印一条醒目的配网门户横幅（SSID、认证方式、IP 与 URL）。30 秒是“用户体感启动时间”与“联网可用性”之间的折中：等待让大多数正常场景一开机就有网，超时也不清状态、不重启，后台继续重连。更重要的是设计立场：app_claw_start() 完全不依赖网络就绪——无网时 LLM 调用自然失败，但外壳、CLI、技能、Lua 运行时全部可用；时间同步服务以 network_ready = NULL 启动、内部异步等待联网，IM 能力也各自维护重连（第9章《IM通信集成》）。网络是“能力面”，不是“启动前置条件”。

5. app_claw：组合根与集中注册表

5.1 app_claw_start 的装配顺序

main.c 只负责平台层（存储、网络、HTTP），域层的全部装配集中在 components/common/app_claw/app_claw.c 的 app_claw_start() 里——这正是“组合根”（composition root）的含义：整个系统里唯一知道“这套产品由哪些部件拼成”的地方。其装配顺序（均带 #if CONFIG_APP_CLAW_CAP_* 门控）依次为：app_claw_store_current_config() 保存配置快照 → build_storage_paths() 解析路径 → cap_session_mgr_set_session_root_dir() 设会话根 → claw_event_router_init()（default_route_messages_to_agent = true，规则文件指向 router_rules/router_rules.json）→ cap_scheduler_init()（注入 claw_event_router_publish 作为事件出口）→ init_memory() → 注册会话删除处理器 → init_skills() 并在 UI 已启动时 system_ui_reload_home() 刷新启动器 → app_capabilities_init() 装配能力 → 为每个编译在内的 IM 通道调用 claw_event_router_register_outbound_binding() 绑定出站消息 → claw_agent_mgr_init() + claw_agent_mgr_create_root_agent() → claw_event_router_start() → cap_scheduler_start() → 时间同步服务 → app_claw_cli_start() → app_claw_publish_startup_event()。顺序本身就是依赖陈述：路由器必须先于调度器初始化（后者要用前者的 publish 函数），记忆与技能必须先于根代理（代理的上下文提供者要用它们），路由器的 start 又必须晚于根代理创建（否则消息来了却没有代理接）。

5.2 集中式能力注册表

app_capabilities.c 的核心是一张静态注册表，每个条目由 Kconfig 宏门控：

static const app_capability_group_entry_t s_capability_group_entries[] = {
#if CONFIG_APP_CLAW_CAP_AGENT_MGR
    { "cap_agent_mgr", "Agent Manager", "...", true,  NULL, app_cap_register_agent_mgr },
#endif
#if CONFIG_APP_CLAW_CAP_IM_WECHAT
    { "cap_im_wechat", "WeChat", "...", false, app_cap_prepare_im_wechat, app_cap_register_im_wechat },
#endif
#if CONFIG_APP_CLAW_CAP_LUA
    { "cap_lua", "Lua", "...", true,  app_cap_prepare_lua, app_cap_register_lua },
#endif
#if CONFIG_APP_CLAW_CAP_MCP_CLIENT
    { "cap_mcp_client", "MCP Client", "...", false, NULL, app_cap_register_mcp_client },
#endif
/* 其余条目同样门控：files/scheduler/skill/system/memory/llm_inspect/
       http_request/web_search/router_mgr/session_mgr（第三列帮助文案此处省略） */
};

每行是一个“能力组”：group_id 是贯穿配置、日志与文档的稳定标识；llm_visible_by_default 决定该组默认是否对 LLM 暴露（注意 IM 类、MCP 客户端、会话管理默认为 false，而 files、skill、system 等基础组为 true）；prepare 与 reg 是两个函数指针，构成两阶段装配——先 prepare（例如 app_cap_prepare_lua 会把 /system/scripts/builtin/lib 等目录加入 package.path 并完成 Lua 模块注册），后 reg（把能力注册进 claw_cap 注册表）。app_capabilities_init() 把内置表与 app_capabilities_register_external_group() 注册进来的外部组合并成一个 entries 数组，用 app_cap_build_group_map() 按 enabled_cap_groups 白名单解析出 enabled_map 与 llm_visible_map，随后对启用的条目依次执行 prepare/reg，最后 claw_cap_set_llm_visible_groups() 统一发布 LLM 可见性。应用固件因此可以插入私有能力组而不必修改框架——只要在 app_claw_start() 之前注册（能力系统的完整机制见第5章）。

5.3 Lua 模块注册表

Lua 侧是完全同构的第二张注册表 s_lua_module_entries，条目由 CONFIG_APP_CLAW_LUA_DRIVER_*（adc/gpio/i2c/mcpwm/pcnt/rmt/touch/uart 等硬件驱动）与 CONFIG_APP_CLAW_LUA_MODULE_*（audio/camera/display/lvgl/json 等高层模块）两组宏门控。app_lua_modules_register() 的装配逻辑与能力组如出一辙，遍历循环最能体现“运行期白名单”的执行方式：

for (i = 0; i < entry_count; i++) {
    if (!selected_map[i]) {
        ESP_LOGI(TAG, "Skipping Lua module at init: %s", entries[i].module_id);
        continue;
    }
    err = entries[i].reg(fatfs_base_path);   // 统一入口：注册到 Lua 运行时
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Failed to register Lua module %s: %s",
                 entries[i].module_id, esp_err_to_name(err));
        free(entries);
        free(selected_map);
        return err;                          // 错误向上传播
    }
}

被 enabled_lua_modules 白名单排除的模块只打一条 INFO 即跳过；入选模块统一以 reg(fatfs_base_path) 一个签名接入。至此形成三级裁剪体系：Kconfig 在编译期决定“哪些代码进固件”，enabled_cap_groups/enabled_lua_modules 在启动期决定“哪些装配的部件真正启用”，llm_visible_cap_groups 再决定“启用的部件哪些对 LLM 可见”。三级共享同一套 group_id/module_id 词汇表，配置界面、文档与代码天然一致（Lua 体系详见第11章《Lua运行时与驱动体系》）。

5.4 为什么集中注册而非分散自注册

面向对象直觉会倾向“每个组件自己注册自己”（构造器自注册），ESP-Claw 却选择了中心化注册表，理由都源于嵌入式固件的现实约束：

• 链接期依赖：ESP-IDF 组件模型没有可靠的 pre-main 执行点，未被引用的目标文件会被链接器的死代码消除（--gc-sections）整段丢弃——分散自注册的代码可能根本进不了固件。集中表通过 app_claw_start() 对每个注册函数的显式引用，保证参与裁剪的只有 Kconfig 一个维度；
• 固件体积控制：关闭一个 CONFIG_APP_CLAW_CAP_*，整组能力连同其依赖（IM 协议栈、MCP 客户端等）从二进制中消失，而不是“运行时不加载却仍占 flash”；
• 确定性与可审计：一张表看完产品全部能力面，注册顺序即表序，失败沿单一调用链传播；产品固件的每次能力增删都集中在一处、易于审查；
• 扩展性反而更好：外部组机制（app_capabilities_register_external_group()、app_lua_modules_register_external()）让业务固件免改框架即可插入私有能力，官方与第三方能力走同一条装配路径。

代价是新增能力必须修改 app_capabilities.c 一个文件——对产品级固件而言，这份“中心化”恰是可控性的来源。

6. Agent 就绪与收尾

6.1 根代理创建与上下文提供者

能力装配完成后，app_claw_start() 进入 Agent 就绪段。最能说明设计意图的是传给 claw_agent_mgr_init() 的上下文提供者数组：

claw_core_context_provider_t base_providers[] = {
    claw_memory_profile_provider,
#if CONFIG_APP_CLAW_MEMORY_MODE_FULL
    claw_memory_long_term_provider,
#else
    claw_memory_long_term_lightweight_provider,
#endif
    claw_memory_session_history_provider,
    claw_skill_skills_list_provider,
};
/* ……随后：
claw_agent_mgr_init(&claw_agent_mgr_config_t{ .base_context_providers = base_providers,
    .root_agent_system_prompt = APP_ROOT_AGENT_SYSTEM_PROMPT,
    .subagent_system_prompt = APP_SUBAGENT_SYSTEM_PROMPT, ... });
claw_agent_mgr_create_root_agent(&root_agent_id);   // 日志：Root agent ready id=%s */

根代理的系统提示词与子代理提示词都是编译进固件的常量，随版本发布；记忆模式（FULL 或轻量）在这里分流到不同的长期记忆提供者。代理管理器的内部设计属于第4章《Agent核心设计》的主题，此处只需注意：claw_agent_mgr_create_root_agent() 返回 root_agent_id 并打出“Root agent ready”日志，这是“Agent 就绪”的标志性时刻。此后 claw_event_router_start() 与 cap_scheduler_start() 才依次启动——事件路由与定时任务的消费者（代理）已经就位。

6.2 CLI 就绪与启动事件

收尾三步：cap_system_time_sync_service_start() 以 network_ready = NULL 启动异步时间同步（无网也不阻塞）；app_claw_cli_start() 按 ESP-IDF 版本与控制台后端创建 REPL（esp_console_new_repl_stdio/_uart/_usb_serial_jtag/_usb_cdc），设置 max_cmdline_length = 512 并注册 ask 命令——用户在串口敲 ask <prompt> 即可用当前会话与根代理对话；最后 app_claw_publish_startup_event() 经事件路由广播启动完成事件，订阅方据此行动（第6章《事件路由系统》）。控制权回到 main.c：本地 IM 能力编译在内时 http_server_webim_bind_im() 把 Web 端消息接入事件路由（第9章）；register_wifi_command() 增补 Wi-Fi 调试命令；app_free_runtime_state() 释放启动期那两份配置结构。最后一行能安全执行，是因为 app_claw_start() 入口处已用 app_claw_store_current_config() 拷贝了配置快照——所有权从未共享，main 侧的临时结构自然可以放手。

7. 失败降级与 C-OO 风格

7.1 降级路径汇总

把前文的错误处理分支集中成一张表，可以清楚看到 ESP-Claw 的取舍标准——“该服务缺失后系统是否仍有可用面”：

失败点	代码行为	用户可见结果
NVS 无空闲页/版本不符	nvs_flash_erase() 后重新 nvs_flash_init()	配置回到出厂默认，配网门户重现
flash 存储分区损坏	format_if_mount_failed = true 格式化重挂载	数据丢失但 .recovery 种子自动补齐
/system/.recovery 缺失	opendir() 失败仅告警，返回 ESP_OK	无种子可恢复，不阻塞启动
插入 SD 卡	优先采用 SD 挂载点，flash 分区不再挂载	存储根自动切换，上层无感
wifi_manager_start() 失败	仅 ESP_LOGE，启动继续	外壳与 CLI 可用，联网能力受限
STA 30 秒超时	告警后转入后台重连	配网门户横幅保持可用
captive_dns_start() 失败	仅 ESP_LOGW	门户不自动弹出，可手动访问 IP
时区配置为空/非法	断言回落 CST-8	时间显示用默认时区
时间同步未就绪	network_ready = NULL 异步等待	不阻塞启动链

与“必须 abort”的致命项对照：存储挂载失败、配置初始化失败、app_claw_start() 任一步失败都会经 ESP_ERROR_CHECK 直接终止——没有文件系统与能力框架，Agent 外壳无从谈起。

7.2 错误处理的三档策略

启动代码里的错误处理实际分三档，每档对应不同的失败半径：

• 第一档 ESP_ERROR_CHECK：致命错误，abort 并触发重启。用于 init 链上所有存储、配置、外壳调用——启动期失败重试大概率仍失败，不如重启进入 OTA/恢复流程；
• 第二档 ESP_RETURN_ON_ERROR/ESP_GOTO_ON_ERROR：向上传播并跳转 cleanup 标签。app_capabilities_init() 的 cleanup 释放 entries、enabled_map、llm_visible_map、llm_visible_groups 四块堆内存；main_wechat_login_get_status() 的 cleanup 释放登录状态结构。“谁分配谁释放”的纪律在错误路径上同样成立；
• 第三档日志容忍：仅 ESP_LOGE/ESP_LOGW 后继续执行，覆盖第 7.1 节表格中的全部条目。

值得点出的取舍是：启动链对已创建的全局对象不做逐个 delete 回滚。原因很直接——错误沿第二档传播到 main.c 后迎接它的是第一档 abort，进程即将重启，对静态单例逐个销毁毫无意义；这份“不回滚”换来了整个 init 链全是单行宏的极简形态。运行期则相反：app_claw_update_config()/app_claw_apply_config() 持有 s_config_lock 互斥锁，保存失败即返回、绝不半落地——进程还要长期活下去，就必须严格回滚。

7.3 句柄与生命周期

启动链集中展示了本项目 C 风格面向对象（C-OO）的惯用法（总述见第2章《项目架构总览》）：

• 不透明句柄：typedef struct claw_core_state *claw_core_handle_t; 对外只暴露指针，结构体细节锁在 .c 文件内；“接口”体现为函数签名约定（如 app_lua_module_register_fn 的统一原型），而非强制的虚表；
• 函数指针即多态：注册表条目的 prepare/reg 与 Lua 模块的 reg 就是小型的 ops 表，装配循环对条目一视同仁，不关心具体能力；
• 静态单例与成对生命周期：main.c 用两个 static 指针（s_config、s_claw_config）承载启动期状态，app_allocate_runtime_state() 负责幂等分配（先判空再 calloc），app_free_runtime_state() 负责对称释放并置空；所有权的边界靠“快照拷贝”划定——app_claw 存自己的配置副本，main 才敢在启动结束后释放原件；
• 单向依赖：main 依赖平台组件，app_claw 依赖域组件，配置写回经回调注入而非反向 include，调用图无环。

这四个惯用法贯穿全书，而启动链是观察它们最纯粹的场景：所有对象在这里一次性按依赖序创建，随后进入长生命周期运行。

参考文献

[0] ESP-Claw源码剖析-03_启动流程与应用外壳：https://my.feishu.cn/wiki/YLCGwlxTiiNwRGkPa4Ecymjan48

[1] ESP-Claw 官方仓库：https://github.com/espressif/esp-claw

[2] ESP-IDF 非易失性存储库（NVS）文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/api-reference/storage/nvs_flash.html

[3] ESP-IDF FATFS 文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/api-reference/storage/fatfs.html

[4] ESP-IDF 错误处理指南：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/api-guides/error-handling.html

[5] ESP-IDF 控制台（esp_console）文档：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/api-reference/system/console.html

更多 ESP-Claw 源码剖析与嵌入式开发内容，欢迎访问云栈社区。