使用手册

完整使用流程

1. 组装硬件并按接线表连好屏幕与 ESP32-C3。
2. 从 2026-07-14 资料包选择对应版本，使用 Huge APP 分区烧录 clawd_mochi.ino。
3. 按版本完成 Wi-Fi 配网、USB 直连或 BLE 桥接。
4. 把 Codex 侧 hook 脚本与 hooks.json 安装到 ~/.codex/。
5. 在 Codex 执行 /hooks，信任 ClawdMochi 相关 hook。
6. 通过 coding / done / waiting 等状态测试设备联动。

三种连接方式怎么选

Wi-Fi 版

适合已经有稳定 2.4G Wi-Fi 的桌面环境。

• 电脑与设备通过局域网通信
• 设备侧有网页控制器
• 支持 http://clawd-mochi.local
• 支持 /event、/cmd、/redraw、/state、/wifi 等接口

有线 USB 版

适合不想配网，或者希望一根线同时解决供电和通信的人。

• 设备没有 Wi-Fi、没有 HTTP 服务
• 通过 USB 串口 115200 接收状态字
• 一根数据线同时负责供电、烧录和运行时事件传输
• 使用时不要让 Arduino Serial Monitor 等程序占用串口

蓝牙 BLE 版

适合不想依赖路由器、但又希望运行时无线化的人。

• 设备没有 Wi-Fi、没有手机网页控制器
• 电脑侧必须运行 BLE 常驻桥接进程
• hook 先请求本机 127.0.0.1:49374，再由桥接写 BLE GATT
• 运行时 USB 只负责供电，不负责数据；也可使用充电器或移动电源

软件运行方式

Codex hooks

三套资料都围绕 Codex hook 事件做状态同步，适配器还会根据工具名称、命令内容和执行结果判断具体表情。典型事件包括：

• SessionStart
• UserPromptSubmit
• PermissionRequest
• PreToolUse
• PostToolUse
• PreCompact
• PostCompact
• SubagentStart
• SubagentStop
• Stop

这些事件最终会驱动桌宠切换到 13 种不同表情。正常结束后的 Codex App 内部提示词、标题与摘要辅助会被过滤，避免完成动画结束后闪烁。

电脑侧脚本

• Wi-Fi 版：PowerShell / CMD 脚本把事件发到设备 HTTP /event
• 有线版：PowerShell / CMD 脚本直接向串口写状态字
• 蓝牙版：PowerShell / CMD 脚本把状态发到本地桥接，桥接再写 BLE
• macOS / Linux：三种版本均使用 clawd-mochi-codex.sh 与 hooks.macos.json；BLE 桥接本身仍使用 Python + bleak

设备侧显示逻辑

三种版本在设备端都采用相似的表情状态机：

状态切换规则

状态切换规则如下：

• thinking 会至少停留约 1.1 秒，防止一发起请求就被后续工具状态覆盖
• done 会保留约 5 秒，与新版 happy 动画时长匹配，然后自动回到 idle
• 如果长时间没有新事件，设备会从工作状态自动退回待机
• 工作态使用固定的橙色风格，待机态保留用户自定义外观
• 等待选择类工具在用户提交答案后会从 waiting 回到 thinking

待机态和自定义

Wi-Fi 版

Wi-Fi 版提供网页控制器，可设置：

• 待机表情
• 背景色
• 背光
• 画布模式

有线版 / 蓝牙版

有线版与蓝牙版没有手机网页控制器，但支持以下文本命令：

• face:0
• face:1
• face:2
• bg:#RRGGBB
• light:on
• light:off

这些命令只影响待机态，不会改掉 coding、running 等工作态的固定风格。

图文教程资源

• Wi-Fi 使用教程：Clawd/资料-wifi版.zip 内的 图文教程②·使用版.png
• 有线使用教程：Clawd/资料-有线版.zip 内的 资料-有线版/图文教程②·使用版.png
• 蓝牙使用教程：Clawd/资料-蓝牙版.zip 内的 图文教程②·使用版.png

补充说明

• 本产品不提供单独的手机 App
• Windows 主要使用 .cmd / .ps1，macOS 与 Linux 使用 .sh
• 安装时请选择每个版本包里的 clawd-mochi-cx/；clawd-mochi-cc/ 是 Claude Code 版