配置说明

本章说明 Ameba-Claw 的配置分两类：运行期可改的配置集中在单个 JSON 文件 vfs:/claw_config.json 里（LLM 的 key、model、url、backend，Wi-Fi 凭证，各消息渠道 token，web search 等），可经 WebUI 或 AT 命令修改；编译期才能改的常量（各种上限、超时、容量、默认值）集中在 ameba_claw_defs.h 中。下面详细列出各配置项。

配置说明

Ameba-Claw 的全部用户可见配置集中在**一个** JSON 文件 vfs:/claw_config.json 里。上电时 claw_config_init() 读取它到内存；文件缺失或某字段缺失时回退到编译期默认值。通过 Web 后台或 AT 命令改配置，最终都是写这一个文件。

优先级与生效方式

• 当前值 = 文件里有的用文件，没有的用编译期默认值。 首次保存后即以文件为准；想"恢复某项默认"就删掉该字段或整个文件。

• 大多数配置保存后**立即生效**，无需重启（Web 后台明确标注了例外）。

• 少数配置**下次启动才生效**：Lua 模块开关（lua.disabled_modules）、能力运行时启停名单（cap_runtime）。

配置项一览

配置结构 claw_config_t 分成若干节（对应 JSON 里的对象），核心几节：

节	内容
wifi	STA 连接的 SSID / 密码 / 加密类型 / 是否已配置
softap	配网热点的 SSID（默认 AmebaClaw）/ 密码 / 信道
llm	LLM 接入：api_key / model / api_url / backend （0=OpenAI 兼容 Bearer，1=Anthropic）/ max_tokens / max_iterations / thinking_enabled / stream_enabled / compact_tokens / window_tokens
telegram / feishu / qq / wechat	各 IM 平台凭证（token / app_id / app_secret / iLink base_url 等）；留空即停用该平台
web_search	联网搜索：Tavily api_key + 每次返回结果数 max_results （1–5）
vision	视觉识别模型：model / api_key / base_url / api_path / api_type （api_key 留空则回退到 llm.api_key）
time	本地时区：offset_min （分钟，UTC 以东为正）+ set （用户是否显式设过）
lua	disabled_modules：逗号分隔的、运行时禁用的 Lua 模块名（如 uart,spi）；空 = 全部启用
http_request	HTTP 请求主机白名单（换行分隔；空 = 全部拒绝，* = 全部允许）
cap_visibility	对 LLM 隐藏的能力组名单（不影响 AT / 事件路由调用，只影响 LLM 是否原生看到）
cap_runtime	运行时禁用的能力组名单（deny-list；被禁用的组其生命周期钩子在下次启动时跳过）

警告

claw_config.json 里存有 API Key、IM token 等机密。请勿把它随意导出公开，也不要把设备后台端口暴露到公网。

时区的特别说明

系统时钟走 UTC（SNTP）。本地时间是用 UTC + offset_min 手动 推导的——不要依赖 localtime_r （这里没有 TZ 环境，它返回 UTC）。set 用来区分"用户配了时区"和"从没配过"：未配置时，依赖本地时间的功能（cron / 闹钟）会拒绝猜测并提示用户先设时区。写时区的唯一入口是 claw_config_set_timezone()。

编译期可调参数

除上述运行时可改的配置外，还有一类**编译期**可调的"魔数"（各种上限 / 超时 / 重试次数 / 容量 / 默认值），它们不经运行时配置，改后需重新编译固件。这些常量**统一定义在** ameba_claw/include/ameba_claw_defs.h，按模块分节（工具 I/O、Agent 引擎、记忆/会话、HTTP、调度器……），每个宏都带注释说明用途、单位和取值理由。

规则：源文件里不写裸字面量，一律 include 该头文件后引用宏。这样所有可调参数都有单一可见入口，不必翻遍源码。

配置的读写 API

• claw_config_get() —— 返回内存里的实时配置指针（claw_config_init() 后永不为 NULL）。

• 各 claw_config_set_*() —— 分节写入并持久化（如 set_llm / set_wifi / set_imbot / set_search / set_vision …）；多数支持传 NULL/0 表示"保持当前值"。

• claw_config_register_on_save() —— 注册保存后回调，供 IM 模块在凭证变化时按需启动任务。