【花雕动手做】Mosaico-Claw的使用与避坑：读懂技能路由，避开ChatCoding隐形陷阱
标签：*ESP-Mosaico、VibeMode、Mosaico-Claw、ChatCoding、MCP、硬件在环 HIL、具身智能、踩坑实录*
## 导读：
很多创客拿到 ESP-Mosaico，兴冲冲打开 CLAW，一句话发出去，结果模型只给文字回答、不生成 Lua 脚本，或者生成脚本运行报错、定时任务不触发、换 IM 之后上下文断连。绝大多数问题不是板子硬件坏了，而是**对 Claw 内置 6 个技能的路由机制、会话边界、权限模型、额度链路理解不到位**。
前面我们拆解了设置面板、AI 后端、IM 远程 HIL 链路，本篇聚焦 Mosaico-Claw 的核心运行机制，从初始化、两种输入通道、六大技能底层逻辑、分层避坑，到工程边界做深度拆解，把日常调试里高频、隐蔽的坑一次性梳理清楚，和前面的远程 HIL 链路内容打通。
> 配图：Vibe Mode 首页界面，包含天气时钟 Idea、Camera 视觉入口、CLAW 对话入口、Works 项目仓库入口
## 一、首页界面底层逻辑（先理清入口分工，避免从源头踩坑）
顶部状态栏：时间、WiFi、电池
卡片区：天气时钟Idea（本身就是一个已经部署、持续运行的Idea应用）
三个圆形入口：Camera / CLAW / Works
很多新手混淆三者定位，这是第一个隐形大坑：
1. **CLAW：AI 创作工作台（Agent 交互入口）**
只负责对话、意图识别、技能路由、生成脚本 / 方案，**不长期保存成品项目**。你在这里生成的 Lua 脚本，部署之后才会存入 Works。
2. **Works：Idea 应用持久化仓库**
所有已经部署、可以独立启动的硬件项目存放于此。它是沙箱应用的管理器，**本身不具备 AI 生成能力**；很多人在 Works 里直接修改代码，改完发现增量迭代失效 —— 因为 Works 里的脚本脱离了 CLAW 的会话上下文，无法自动继承历史硬件快照。
3. **Camera：视觉外设专属入口**
配套摄像头子板，负责图像采集、预览；它和 AI Model 里的`Vision On`开关强绑定。**就算插上摄像头，不开 Vision On，LLM 也拿不到画面**。
> 核心认知：CLAW 是 “设计师”，Works 是 “成品仓库”，Camera 是 “眼睛”。
## 二、首次启动初始化流程 + 额度体系深层避坑
首次打开 Mosaico-Claw Idea，标准流程：WiFi 配置 → IM 账号绑定 → 开始对话。这里有两个极易忽略的底层约束：
1. **出厂免费额度的边界（高频踩坑点）**
出厂赠送额度，覆盖 ASR 语音识别 + LLM 推理，适合轻量问答、简单绘图脚本。
坑 1：额度耗尽不是 “完全不能用”，而是**随机出现空响应、路由错乱、AI Create 直接降级到快速提问**，不会给清晰的额度耗尽报错。很多人误以为是模型路由 bug，反复改指令，排查很久。
坑 2：免费额度和你自己配置的 OpenAI 兼容后端是两套独立链路。**切换自定义后端之后，不再消耗出厂额度**，全部走你自己 API Key 的配额。
坑 3：额度只负责推理，脚本在板子本地 Lua 沙箱运行，**脚本运行不消耗 token**，这也是 HIL 硬件在环的核心特点。
2. **WiFi 与 IM 绑定的底层约束**
IM 通道（微信 / 飞书）默认仅局域网内生效；IM 绑定信息保存在板子 Flash，**换 WiFi、换路由器，IM 绑定关系不会自动失效，但会无法连通**。
> 避坑：更换局域网之后，优先进入 IM Channels 页面重新校验链路，不要直接发消息。
### 两种输入通道的底层差异（本地语音 VS IM 远程文字）
板载语音输入：首页点开 CLAW，长按输入框收音
- 链路：麦克风 → 板载 ASR → 文本送入 Claw 路由
- 坑：ASR 识别错误会直接改变意图，比如你说 “绘制表盘”，识别成 “回答表盘”，直接路由到`ai_create_quick`，只给文字解释，不生成代码。复杂硬件项目，**优先 IM 文字输入，规避语音识别带来的意图漂移**。
IM 远程文字输入：绑定微信 / 飞书后直接发消息
- 链路：IM 消息 → Vibe Mode 内置 IM 调度器 → 带上同一个 Session ID，送入和板端完全一致的会话上下文
- 优势：跨设备增量调试；
- 坑：**同一个会话 ID，板端和 IM 端是互通的，但新建会话会完全隔离上下文**。很多人在微信新开对话，疑惑为什么 Agent 不记得之前写的表盘代码。
> 参考配套的远程 HIL 完整链路：
## 三、六大内置技能：路由机制、定位、深度踩坑
这 6 个技能是 Claw 的意图分发核心，**路由是 LLM 自动判断的，不是你手动切换**。
这是绝大多数 ChatCoding 失败的根源：模型选错技能，哪怕指令写得没问题，也无法控制硬件。
### 技能路由底层原理（深度理解）
Claw 本身有路由规则描述，LLM 读取 6 个技能的描述，基于用户指令选择技能。**路由结果完全依赖你选用的 LLM 的工具调用能力**。
同样一条硬件控制指令，换一个弱工具调用模型，就容易跑偏到快速提问；换擅长 Function Call 的模型，路由准确率大幅提升。
> 这也是为什么我们前面设置面板里，`openai_compatible`后端非常关键：你可以自由更换模型，优化路由稳定性。
## 四、分层避坑总表（按调试链路排序，排查顺序）
### 第一层：配置层（先查，很多人直接跳过）
1. AI Model 页面 `Tools On` 是否开启：关闭 = 所有硬件控制能力失效，只能闲聊
2. Base URL + API Key 是否填写正确、接口支持 Function Call；很多兼容接口只支持聊天，不支持工具调用
3. Vision On 按需开启：不用摄像头时关闭，减少 token 消耗，避免模型强制读取画面
4. 网络：WiFi 连通、可以访问 NTP 时间服务器（定时任务必备）；IM 通道仅限局域网
### 第二层：会话与技能路由层（ChatCoding 最容易踩坑）
1. 确认当前会话是同一个 Session：IM 和板端互通，新建会话上下文清零
2. 观察返回结果：如果只有文字、没有代码，大概率路由到 ai_create_quick
3. 增量复杂度控制：不要一次性要求大量绘图、多模块联动代码，LLM 上下文窗口有上限，容易空响应、截断
4. 长期记忆污染：调试时，不要随便把临时参数存入 memory_ops，容易出现莫名其妙的行为漂移
### 第三层：Lua 沙箱与硬件执行层（脚本生成成功但是跑不起来）
1. 沙箱安全隔离：Lua 脚本有资源限制，不能直接操作底层总线、不能阻塞死循环；死循环脚本会触发沙箱看门狗，自动终止
2. 硬件快照：Claw 会自动扫描磁吸扩展模块；如果模块松动、I2C 总线冲突，快照信息错误，LLM 生成的驱动代码天然错误（V1.2 主板拆分内外 I2C 总线，就是为了缓解这个问题）
3. 脚本部署后：存入 Works，但是后续增量修改，需要在原会话继续迭代，新开会话无法自动读取已有 Idea 代码
### 第四层：HIL 远程链路专属坑（IM 远程调试）
1. 内网穿透不属于原生能力，官方 IM 通道只支持局域网；公网远程需要自行搭建内网穿透，存在延迟、丢消息
2. IM 消息是异步的，硬件执行日志回传有延迟，不要连续快速发多条指令，容易上下文错乱、消息乱序
3. 远程和本地语音混用调试，适合同一个 Session；频繁切换输入方式，会放大路由不稳定的概率
## 五、工程边界：Mosaico-Claw 能做什么、不适合做什么（建立合理预期）
这是更高维度的避坑，避免把 ChatCoding 当成万能方案：
适合：创意原型、屏幕动画、定时自动化、传感器读取、简单交互机器人、创客教学演示、快速验证想法；
不适合：微秒级实时控制、FOC 电机、高速 SLAM、上万行大型工程。Lua 是解释型沙箱脚本，有运行开销，这类场景必须切换到 VibeCoding，使用 ESP-IDF C 工程开发。
> 两条路线互补：ChatCoding 快速试错、验证创意；验证可行之后，复杂高性能需求迁移到 VibeCoding。
## 六、实战调试排错流程（标准化排查步骤，直接套用）
当你发送指令，硬件没有预期动作，按顺序排查：
1. 确认 WiFi 正常、AI 后端 API 鉴权正常，没有额度耗尽；
2. 检查 AI Model：Tools On 是否打开；
3. 看返回内容：是纯文字回答 → 路由选错技能，重新优化指令 / 更换模型；
4. 有 Lua 代码，但是运行报错：查看报错日志，检查磁吸模块是否识别、硬件快照是否正确；
5. 定时任务不触发：确认 NTP 时间同步成功；
6. 远程 IM 收不到反馈：检查 IM Channels 绑定状态，确认手机和板子同局域网。
## 七、和后文联动小结
本篇的技能路由体系，跑在我们后面讲解的【AI 后端配置 + IM 远程 HIL 链路】之前：
不管是板上语音，还是微信远程下发指令，消息先进入 Claw，由 LLM 路由分配到 6 个技能；只有 AI Create、计划任务会进入 MCP 硬件调用链路，完成真机热部署，形成硬件在环闭环。其余技能只做推理、问答、记忆读写，不会触碰硬件。
理解这套路由机制，就看懂了为什么有时候一句话就能驱动硬件，有时候只能得到文字回答，不再把 “技能路由问题” 当成板子故障。
