---
title: 启动与运行时装配
description: 从 app_main 到各子系统就绪的顺序
---

import { Steps, FileTree, LinkCard } from '@astrojs/starlight/components';
import LinkToSource from '@/components/LinkToSource.astro';

下文以示例应用 `application/edge_agent` 为例，介绍入口 <LinkToSource relativePath="application/edge_agent/main/main.c" /> 与装配逻辑 <LinkToSource relativePath="components/common/app_claw/app_claw.c" />。

## `main.c` 入口程序

<LinkToSource relativePath="application/edge_agent/main/main.c" /> 会初始化系统必要组件及所需外设，为 ESP-Claw Agent 的运行做好准备。

<Steps>
1. **初始化 NVS 并载入配置**

    上电后，`edge_agent` 会先尝试初始化 NVS 分区（`nvs_flash_init`）。
    随后，通过 `app_config_init` + `app_config_load`，将Wi‑Fi、LLM、IM、搜索、时区等读入内存，完成基本配置初始化。

2. **初始化 Board Manager 与可选 Emote**

    调用 `esp_board_manager_init` 完成板级设备句柄装配。<br />
    若启用 `CONFIG_APP_CLAW_ENABLE_EMOTE`，随后还会调用 `app_claw_ui_start` 启动表情显示组件，并将屏幕初始状态设为离线提示。

3. **挂载 FATFS 文件系统**

    尝试将 FATFS 文件系统挂载至 `/fatfs` 虚拟路径。<br />
    如果挂载失败，`ESP_ERROR_CHECK` 会触发 `abort`，设备将重启。文件系统是 ESP-Claw 正常运行的必要条件。

4. **初始化 Wi‑Fi 与状态回调**

    尝试初始化 Wi‑Fi（`wifi_manager_init` / `wifi_manager_start`）：连接至配置的 SSID、启动 SoftAP 便于 Web 配置与离线操作。<br />
    - 在 `wifi_manager_init` 之后会注册 `wifi_manager_register_state_callback`：若启用了 emote，会在 Wi‑Fi 连接/断开时更新表情与文案状态，并可显示当前 AP SSID 等中间态信息。<br />
    - 如果初始化失败，则打印错误日志，并继续启动过程。即使未连接 Wi-Fi，ESP-Claw 也可以正常使用离线规则、运行 Lua 脚本等。

5. **启动 HTTP 服务器**

    启动 HTTP 服务器（`http_server_init` / `http_server_start`），供用户通过 Web 配置页面调整系统配置。
    同时会启动 captive DNS（`captive_dns_start`），便于 SoftAP 配网场景下自动跳转到门户页。

6. **启动 ESP-Claw Agent 子系统**

    调用 `app_claw_start(&s_settings)`，启用 ESP-Claw Agent 子系统。

</Steps>

## `app_claw.c` Agent 装配程序

<LinkToSource relativePath="components/common/app_claw/app_claw.c" /> 会初始化 ESP-Claw Agent 子系统，按顺序启动各子组件并设置参数，最终启动 Console REPL。

<Steps>
1. **初始化 Session Manager 与 Event Router**

    先调用 `cap_session_mgr_set_session_root_dir` 配置会话管理器的会话根目录，
    再调用 `claw_event_router_init`，载入自动化规则文件路径（demo：`/fatfs/router_rules/router_rules.json`），
    并配置与 `claw_core` 通信的超时时间及默认是否将消息路由给 Agent（`default_route_messages_to_agent`，当 LLM 配置完整时为 `true`）。
    `run_agent` 动作采用异步提交模式，Agent 响应通过 `out_message` 事件发布回 Event Router。

2. **初始化调度器**

    调用 `cap_scheduler_init`，指定调度配置文件路径（`/fatfs/scheduler/schedules.json`）、检查频率（`tick_ms`）、最大条目数（`max_items`）、任务栈大小及优先级，并绑定发布接口（`claw_event_router_publish`）。调度器在此时初始化，但尚未启动。

3. **初始化 Memory**

    调用 `claw_memory_init`，设置会话历史目录（`/fatfs/sessions/`）、长期记忆目录（`/fatfs/memory`）及单条消息最大字符数等参数（`edge_agent` 默认 1024 字符/条）。
    如果记录结构所需文件不存在，则会自动创建。

4. **初始化 Skills**

    调用 `claw_skill_init`，设置技能根目录（`/fatfs/skills/`）及会话状态根目录，供 `activate_skill` 等操作使用。

5. **初始化 Capabilities**

    调用 `claw_cap_init`，随后依次初始化各 cap 模块并注册到 cap 组：

    - **cap_files**：设置文件访问根目录（`/fatfs`）。
    - **cap_lua**：设置 Lua 脚本根目录（`/fatfs/scripts/`）。
    - **cap_im_platform**：若 IM 凭证非空，则写入 QQ / 飞书 / Telegram / 微信的 App ID、Secret 或 Token 等字段，并配置共享附件存盘目录（`/fatfs/inbox/`）与最大文件大小。该组件会注册各平台运行时 Group（`cap_im_qq`、`cap_im_feishu`、`cap_im_tg`、`cap_im_wechat`）。
    - **cap_web_search**：若 Brave / Tavily key 非空则写入搜索密钥。
    - **cap_router_mgr**：注册 Event Router 的管理命令（`event_router`）。
    - **cap_system**：注册系统信息能力组（内存、CPU、Wi-Fi、IP，提供重启动作）。
    - **cap_mcp_client / cap_mcp_server / cap_skill / cap_time / cap_llm_inspect / cap_session_mgr** 等：逐一调用 `*_register_group` 完成注册（其中 Skill 管理模块源码目录为 `cap_skill_mgr`，Group ID 仍是 `cap_skill`）。
    - 完整结构化记忆模式下，还会注册 `claw_memory` 能力组；轻量模式下不注册该组。
    - 调用 `claw_cap_set_llm_visible_groups` 将 `cap_files`、`cap_skill`、`cap_system`、`cap_lua` 设为 LLM 初始可见组；完整结构化记忆模式还会额外包含 `claw_memory`。最后 `claw_cap_start_all` 启动全部 cap。

    <br />

6. **绑定出站 IM 通道**

    调用 `claw_event_router_register_outbound_binding`，将 `qq`、`feishu`、`telegram`、`wechat` 四个来源分别绑定到对应的发送 cap（如 `qq_send_message`）。

7. **初始化 claw_core（条件执行）**

    若 `llm_api_key`、`llm_model`、`llm_profile` 均非空：
    - 调用 `claw_core_init` 配置 LLM 后端（API Key、profile、model、base_url、超时等）及系统提示词；
    - 依次注册 context provider：`claw_memory_profile_provider`、长期记忆 provider（完整模式为 `claw_memory_long_term_provider`，轻量模式为 `claw_memory_long_term_lightweight_provider`）、`claw_memory_session_history_provider`、`claw_skill_skills_list_provider`、`claw_cap_tools_provider`；
    - 调用 `claw_core_start` 启动推理任务。

    若 LLM 未完整配置，则跳过 `claw_core_init` / `claw_core_start` 并打印 WARN；`ask`、默认路由至 Agent、图片 inspect 等依赖 core 的功能完全不可用，直到 LLM 配置补全并重启。

8. **启动 Event Router、时间同步、调度器与 Console REPL**

    调用 `claw_event_router_start` 开始处理入站事件，随后调用 `cap_time_sync_service_start` 启动 SNTP 时间同步服务（首次同步成功时会触发 `cap_scheduler_handle_time_sync` 对调度器进行时间校准），再调用 `cap_scheduler_start` 启动调度器任务，最后调用 `app_claw_cli_start` 启动 Console REPL，装配完成。

</Steps>

## 文件系统

<FileTree>
- fatfs
  - sessions
    - ... 会话历史
  - memory
    - MEMORY.md 供人类阅读的记忆视图（只读）
    - memory_records.jsonl 结构化记忆记录
    - memory_index.json 摘要标签与关键词索引
    - memory_digest.log 记忆操作摘要日志
    - user.md 用户画像
    - soul.md 人设
    - identity.md 身份
  - skills
    - skill_id
      - SKILL.md Skill 元数据与正文
      - scripts/ Skill 自带脚本（可选）
  - scripts
    - ... Lua 脚本
  - router_rules
    - router_rules.json 自动化规则
  - scheduler
    - schedules.json 调度任务配置
    - schedules.json.state 调度任务运行时状态
  - inbox
    - ... IM 附件
</FileTree>
