高级教程

架构差异

Wi-Fi 版

架构特点如下：

• 设备运行 HTTP 服务
• Codex hook 把状态发到 /event?s=<state>
• 设备还能提供网页控制器与 Wi-Fi 配网界面

有线 USB 版

架构特点如下：

• 设备不启动 Wi-Fi，不启动 WebServer
• 电脑侧通过 USB 串口 115200 写入状态字
• 一条 USB 数据线承担供电、烧录、运行时事件传输

蓝牙 BLE 版

架构特点如下：

• 设备通过 BLE GATT 暴露可写 characteristic
• 电脑侧桥接常驻并持有连接
• hook 与桥接之间只走本机 127.0.0.1:49374
• 桥接按 GATT service UUID 扫描设备，并缓存连接地址以加速重连

为什么需要桥接

蓝牙版采用桥接的主要原因：

• BLE 不是 IP 网络，不能像 Wi-Fi 版那样直接 curl 设备
• 每次事件都重新建 BLE 连接会慢到 1 至 3 秒
• 为了不阻塞 Codex，需要桥接常驻保持一条热连接

状态分类逻辑

三种版本都遵循一个原则：不要让设备影响 Codex 本体。

因此整体设计都遵循：

• 事件发送必须快速失败
• 设备是被动状态指示器
• thinking、reading、coding、running、delegating、planning、waiting、compacting、notify 等状态由 hook 分类得到
• 读取型命令归为 reading，写文件型命令归为 coding，其他命令归为 running
• 工具或子代理明确失败时显示 error，正常停止时显示约 5 秒的 done
• Esc 中断没有可靠 hook 时，需要依赖后续状态或超时自恢复

高级自定义点

可进一步调整的内容包括：

• 待机表情 face:0 / 1 / 2
• 待机背景 bg:#RRGGBB
• 背光 light:on / light:off
• Wi-Fi 版网页控制器中的画布、字符输入和速度调节

自定义接线和外壳

新版三套 02-hardware-wiring.md 都写到：

• 使用 8 根线连接 ST7789 与 ESP32-C3
• 建议橙色主体、黑色背板的 3D 打印外壳
• 屏幕用 2 个 M2 螺丝固定

高级排查思路

• Wi-Fi 版先用 /state 确认设备是否已经联网
• 有线版先确认电脑是否识别出 ESP32-C3 串口
• 蓝牙版先查桥接日志，看是否已经 BLE connected
• 三个版本都可以先用手动测试命令排除 Codex hooks 以外的问题

跨平台脚本

• Windows 使用 clawd-mochi-codex.cmd、clawd-mochi-codex.ps1 与 hooks.json
• macOS / Linux 使用零 PowerShell 依赖的 clawd-mochi-codex.sh 与 hooks.macos.json
• macOS / Linux 的 Wi-Fi 版依赖系统自带的 Bash、curl、Perl
• macOS / Linux 的有线版还使用 stty 写串口
• BLE 版桥接在三个平台上都需要 Python 3.9+ 与 bleak

补充说明

• 当前版本未提供多设备联动的统一 UI
• Codex 安装资料位于 clawd-mochi-cx/，不要与 clawd-mochi-cc/ 的 Claude Code hooks 混装