跳转到内容
Docs

启动与运行时装配

下文以示例应用 application/basic_demo 为例，介绍入口 main.c 与装配逻辑 app_claw.c。

main.c 入口程序

Section titled “main.c 入口程序”

main.c 会初始化系统必要组件及所需外设，为 ESP-Claw Agent 的运行做好准备。

  1. 初始化 NVS 并载入配置

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

  2. 初始化 Board Manager 与可选 Emote

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

  3. 挂载 FATFS 文件系统

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

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

    尝试初始化 Wi‑Fi（basic_demo_wifi_init / basic_demo_wifi_start）：连接至配置的 SSID、启动 SoftAP 便于 Web 配置与离线操作。

    • 在 basic_demo_wifi_init 之后会注册 basic_demo_wifi_register_state_callback：若启用了 emote，会在 Wi‑Fi 连接/断开时更新表情与文案状态，并可显示当前 AP SSID 等中间态信息。
    • 如果初始化失败，则打印错误日志，并继续启动过程。即使未连接 Wi-Fi，ESP-Claw 也可以正常使用离线规则、运行 Lua 脚本等。

  5. 启动 HTTP 服务器

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

  6. 启动 ESP-Claw Agent 子系统

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

app_claw.c Agent 装配程序

Section titled “app_claw.c Agent 装配程序”

app_claw.c 会初始化 ESP-Claw Agent 子系统，按顺序启动各子组件并设置参数，最终启动 Console REPL。

  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）及单条消息最大字符数等参数（basic_demo 默认 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_qq / feishu / tg / wechat：若凭证非空则写入 App ID / Secret / Token 等，并配置附件存盘目录（/fatfs/inbox/）与最大文件大小。
    • 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。

  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、超时等）及系统提示词；
    • 依次注册 7 个 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_skill_active_skill_docs_provider、claw_cap_tools_provider、cap_lua_async_jobs_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 启动调度器任务，最后调用 basic_demo_cli_start 启动 Console REPL，装配完成。

文件系统

Section titled “文件系统”
  • 文件夹fatfs
    • 文件夹sessions
      • … 会话历史
    • 文件夹memory
      • MEMORY.md 供人类阅读的记忆视图（只读）
      • memory_records.jsonl 结构化记忆记录
      • memory_index.json 摘要标签与关键词索引
      • memory_digest.log 记忆操作摘要日志
      • user.md 用户画像
      • soul.md 人设
      • identity.md 身份
    • 文件夹skills
      • skills_list.json Skills 列表与元数据
      • … Skills 文件
    • 文件夹scripts
      • … Lua 脚本
    • 文件夹router_rules
      • router_rules.json 自动化规则
    • 文件夹scheduler
      • schedules.json 调度任务配置
      • schedules.json.state 调度任务运行时状态
    • 文件夹inbox
      • … IM 附件