跳到主要内容

5.4 配置说明

1. 概述​

ESP-Claw edge_agent 使用 menuconfig (sdkconfig) 保存初始化默认配置，使用 NVS 持久化运行时修改的配置。

edge_agent 会将配置储存在 NVS 命名空间 app 里。 上电后，程序会读取 menuconfig 中的默认配置，再使用 NVS 中储存的键（如有）覆盖。 字段列表与读写逻辑位于 app_config.c 文件中

优先级如何理解

当前运行使用的值 = NVS 里有的用 NVS，没有的用编译默认值。

因此：第一次在 Web 或串口工具里保存过后，就会以 NVS 为准；想「恢复出厂默认」需要清除对应 NVS 键。

2. edge_agent 配置字段​

除标注为「可选」的选项外，其他选项均为必填。

基础配置​

  • wifi_ssid / wifi_password：Wi-Fi SSID 与密码
    • 除 ESP32-C5 外，其他芯片仅支持 2.4 GHz 频段的 Wi-Fi
    • 密码留空表示当前 Wi-Fi 无密码
  • time_timezone ：时区
    • 需为 POSIX TZ string 格式，推荐从此表格中查阅
    • 例如：北京/香港/新加坡等地的时区为 CST-8

LLM 相关配置​

固件侧 LLM 运行时（claw_core 中 claw_llm_runtime.c）按 profile（预设）+ backend（协议实现） 构建请求：

  • profile 决定默认网关根地址、API 路径、max_tokens 等字段名等元数据；
  • backend 决定 HTTP 请求/响应是否按 OpenAI Chat Completions 兼容格式 还是 Anthropic Messages API 请求与解析。

以下为具体配置项：

  • llm_profile：供应商/场景预设

    • 空字符串会回退到 claw_llm_profile_default() 指定的默认 profile（当前为 openai）
    • 当前版本预设取值与实际配置对应关系参阅 app_config.c

  • llm_backend_type：后端类型 [可选]

    • 需与真实接口协议一致或留空：例如调用官方 Anthropic 或兼容其 Messages 格式的网关时，应使用 anthropic；调用 OpenAI 或各类「OpenAI 兼容」网关时，应使用 openai_compatible。
    • 若填写非空，则覆盖当前 profile 的默认后端类型；若留空则使用 profile 自带默认值
    • 可选值：openai_compatible、anthropic、custom

  • llm_base_url：API Base URL [可选]

    • 自定义网关根地址；留空时使用当前 profile 的默认 base_url
    • 运行时请求的 Endpoint URL 为 base_url + api_path

  • llm_model：模型名

    • 须与所选供应商的模型名一致

  • llm_api_key：大模型 API Key

  • llm_auth_type：鉴权头类别 [可选]

    • 补充字段，例如 bearer、api-key、none 等
    • 使用 openai_compatible backend 时，llm_auth_type 留空表示使用 bearer 作为鉴权头类别，并使用 Authorization: Bearer <API Key> 请求头传递
    • 使用 anthropic backend 时，llm_auth_type 选项会被忽略。API Key 会通过 x-api-key: <API Key> 请求头传递

  • llm_timeout_ms：请求超时

    • 请求超时时间（毫秒，字符串形式存储）

IM 与开放平台​

ESP-Claw 支持接入 QQ、飞书、Telegram 与微信 ClawBot，并预留了可扩展接口。如不填写对应的凭据，对应的 IM 将无法正常使用。

  • qq_app_id / qq_app_secret：QQ 开放平台机器人凭证
  • feishu_app_id / feishu_app_secret：飞书应用凭证
  • tg_bot_token：Telegram Bot Token
  • wechat_token / wechat_base_url / wechat_cdn_base_url / wechat_account_id：微信 ClawBot 相关参数 ，推荐由扫码登录流程写入。
Capability 与 IM 配置参数的关系

接入 IM 能力需要启用对应的 Capability，并配置对应的凭据

若只启用 Capability 而不配置凭据，则该 Capability 仍会启用，但无法收发消息

网络搜索​

网络搜索 API Key 均为可选。两者均留空时，ESP-Claw 将无法通过网络搜索获取在线信息

3. 编译期 Kconfig 选项​

除上述运行时可改的 NVS 配置外，部分行为由编译期 Kconfig（menuconfig）控制，未提供运行时修改方法，修改后需重新编译固件：

  • APP_CLAW_MEMORY_MODE：选择长期记忆工作模式

    • Structured（完整结构化记忆，默认）：启用结构化记忆抽取流程；LLM 可见组额外包含 claw_memory；注入摘要标签目录而非完整 MEMORY.md
    • Lightweight（轻量）：跳过结构化抽取，直接将 MEMORY.md 文本注入上下文；适合内存或上下文窗口受限场景。

  • APP_CLAW_ENABLE_EMOTE：是否在启动时启用 LCD 表情/状态显示组件。仅在板型带 LCD 时有意义，不开启可节省少量堆内存。

可通过 idf.py menuconfig → (Top) → App Claw Config 查看和修改上述选项。

4. 修改入口​

  • Web：详见 Web 配置
  • menuconfig：适合产线烧录前写入默认 Wi‑Fi、默认 Key；仍会被 NVS 覆盖。
  • 在线烧录工具：在烧录向导里写入的值会保存到 NVS，效果等价于 Web 保存。

修改配置后，推荐重启设备以使配置生效。

安全提醒

配置页与 NVS 中存有机密令牌，请勿把导出的配置或整机 NVS 转储随意公开