跳转到内容

FAQ

基本运行

启动后没有连上 Wi-Fi

常见原因：

SSID/密码错误：两者均区分大小写。
路由器频段不兼容：除 ESP32-C5 外，其他芯片暂仅支持 2.4GHz Wi-Fi。
Wi-Fi 信号过差。

排查建议：

通过 SoftAP 下的 Web 配置页，修改 Wi-Fi SSID 与密码，连接到 2.4G Wi-Fi。➡️Web 配置
使开发版靠近路由器。如果开发版带天线座，检查与天线连接是否良好。

`ask` 超时或没有回复

常见原因：

设备访问不了 LLM 云端（DNS、防火墙、地区网络）。
API Key、profile、model 不匹配或过期。
模型过慢，超过路由层等待 claw_core 的时间（日志里会有线索）。
Event Router 规则不正确，消息无法正确路由。

排查建议：

观察日志中是否有 HTTP / TLS 相关错误。
确认配置中 LLM 配置完整。➡️配置说明
检查 Event Router 规则是否正确，消息是否正确路由。

通过 IM 发送的消息没有响应

常见原因：

ESP-Claw 无法收到 IM 发送的消息，或者 ESP-Claw 无法通过 IM API 发送消息。
LLM 运行故障。
Event Router 规则不正确，消息无法正确路由。

排查建议：

观察日志中的 HTTP 状态与错误消息。
查看 IM 消息是否已经收到。如果 IM 消息已收到，串口会打出相应 log。➡️ESP-Claw 无法收发 IM 消息
检查 ask 命令是否正常运行：在串口使用 ask "你好"，如果能正常收到回复，说明 LLM 已经正常工作。➡️ask 超时或没有回复
检查 Event Router 规则是否正确，消息是否正确路由。

ESP-Claw 无法收发 IM 消息

常见原因：

IM 配置参数不正确，或者 Secret/Token 过期。
ESP-Claw 无法访问 IM 平台 API：使用 Telegram Bot API 通常需要较好的网络环境。
飞书等平台 Bot 权限配置不正确。

排查建议：

观察日志中的 HTTP 状态与错误消息。
重新配置 IM 相关参数，配置完成后重启设备。
检查飞书 Bot 权限是否配置正确。

Agent 与工具

Agent 一直无法完成某个任务

典型症状：

Agent 声称自己完成了某个任务，但实际没有完成。后续重复指令，Agent 仍然无法完成。

常见原因：

LLM 可能因为在之前调用了错误的工具，导致后续 LLM 一直参考错误的上下文。
LLM 的能力欠佳，无法正确完成动作。

排查建议：

向 Agent 发送 /new 命令，切换至新 Session。
更换能力较强的模型，或缩短历史上下文。

模型「看不到」某个工具

常见原因：

该工具所在 group 不在 claw_cap_set_llm_visible_groups 白名单内（demo 默认是 cap_files、cap_skill、cap_system、cap_lua，完整结构化记忆模式还包含 claw_memory）。
需要 激活技能 后，模型才会同时拿到工具文档与对应 group 的可见性。

排查建议：

cap list 确认 descriptor 已注册。
用 skill --activate <id> --session <当前 session> 激活后重试对话。

模型声称调了工具但没有效果

常见原因：

模型幻觉，实际未产生 tool call。
工具执行失败但回复里未说明。
上下文过长导致行为异常。

排查建议：

看 claw_core 日志里的 tool 名称摘要。
手工 cap call <name> '<json>' 复现。
更换能力较强的模型，或缩短历史上下文。

自编程等高级功能表现不佳

常见原因：

所用模型的推理能力不足，无法正确生成 Lua 代码或复杂工具调用。

排查建议：

自编程、复杂工具组合等功能依赖强推理模型的能力，推荐选用 GPT-5.4 或类似性能的模型以取得最佳体验。
如果使用较弱的模型，建议先从简单任务（日常问答、定时提醒等）开始体验。

自动化与 Lua

规则改了不生效

校验 JSON。
auto reload。
auto emit_message / auto emit_trigger 做最小用例。

Lua 执行失败

路径是否在受管目录、扩展名是否为 .lua。
参数是否符合脚本预期。
异步任务是否超时（可尝试同步执行）。