使用注意

通用注意事项

• ClawdMochi 是状态指示设备，设计目标是不能阻塞 Codex
• 工作状态与待机状态分离，待机自定义不会覆盖 coding、running 等工作态表现
• 同一设备不建议同时被多个程序驱动，谁最后发状态谁覆盖画面
• 固件与电脑端适配器应来自同一个 2026-07-14 版本包，不要与旧 hooks 脚本混用
• Codex 使用 clawd-mochi-cx/，Claude Code 使用 clawd-mochi-cc/

Wi-Fi 版注意事项

• 仅支持 2.4GHz Wi-Fi
• 建议使用英文 / 数字 SSID
• 设备与电脑必须在同一网络
• 如果网络切换，可用 /wifi 或页面中的换网入口重新配置
• Windows 建议在 clawd-mochi.url 中使用数字 IP，避免 .local 解析拖慢每次事件

有线 USB 版注意事项

• 必须使用数据线，不是充电线
• 设备运行时要接在电脑 USB 口上，不能只接充电头
• 不要同时打开 Arduino Serial Monitor 等会占用串口的程序

蓝牙 BLE 版注意事项

• 设备需要在桥接进程的 BLE 覆盖范围内
• 桥接需要常驻运行
• 建议只保留一个桥接实例，避免端口 49374 冲突
• macOS 首次启动桥接时必须允许终端访问蓝牙
• Linux 需具备可用的 BlueZ；bleak 安装失败时先检查 Python 版本和系统蓝牙组件

烧录注意事项

• Board 选择 ESP32C3 Dev Module
• Partition Scheme 必须选择 Huge APP (3MB No OTA/1MB SPIFFS)
• 三个版本均建议启用 USB CDC On Boot，有线版则是必须启用
• BLE 版需要 NimBLE-Arduino 2.x
• 请保持 13 个 sprite_*.h、rle_sprite.h 与 clawd_mochi.ino 在同一草图目录

故障排查

设备能手动测试，Codex 不跟随

• 大概率先检查 /hooks 是否已信任
• 再检查 hooks.json 中 __HOOKS_DIR__ 是否替换成真实路径
• 确认修改配置后已经重启 Codex，并重新执行 /hooks 信任

设备完全不在线

• Wi-Fi 版：看 http://<设备IP>/state
• 有线版：看设备是否枚举串口
• 蓝牙版：看桥接日志是否出现 BLE connected

烧录失败

• 更换 USB 线
• 重新进入下载模式
• 重启 Arduino IDE 后重新选择 ESP32C3 Dev Module

售后反馈建议

• 先保存你正在使用的是 Wi-Fi / 有线 USB / 蓝牙 BLE 哪个版本
• 记录你执行的测试命令和现象
• 同时附上是否已经完成 /hooks 信任
• 附上操作系统、资料包日期以及手动测试结果

补充说明

• 如需售后支持，请以购买渠道或实际提供的服务方式为准