快速开始

本页用于说明 ClawdMochi 首次接入的最短流程。

先下载 ClawdMochi 最新资料包（2026-07-14）。解压外层压缩包后，进入 Clawd/ 并继续解压与你设备对应的版本包。

第一步：先确认版本

ClawdMochi 目前提供三种接入方式。成品默认出厂为 Wi-Fi 版；如需改为有线 USB 版或蓝牙 BLE 版，请重新烧录对应固件。

• Wi-Fi 版：设备接入 2.4G Wi-Fi，电脑与设备在同一网络，通过 HTTP /event 同步状态
• 有线 USB 版：设备用 USB 数据线直接连接电脑，通过串口接收状态字
• 蓝牙 BLE 版：电脑运行本地 BLE 桥接进程，再由桥接把状态写入设备

如需先比较差异，可先阅读 使用手册 的版本对照部分。

如果购买的是已装好的成品设备，一般可跳过第 2、3、4 步，直接查看 第五步：按版本完成连接。

第二步：准备硬件

三套资料中的硬件主体基本一致：

• ESP32-C3 Super Mini
• ST7789 TFT 1.54 寸 240×240 屏幕
• 8 根杜邦线
• 2 根 M2 螺丝固定屏幕
• USB 线

接线表在三套参考文档中保持一致：

第三步：准备软件环境

准备工具如下：

• Arduino IDE 2.x 或 arduino-cli
• ESP32 开发板支持包
• Adafruit GFX Library
• Adafruit ST7735 and ST7789 Library
• 蓝牙 BLE 版额外需要 NimBLE-Arduino 2.x（h2zero）
• 蓝牙 BLE 版桥接额外需要 Python 3.9+ 和 bleak

第四步：烧录固件

三种版本都要求先把对应 clawd_mochi.ino 烧录到 ESP32-C3。请保持 clawd_mochi.ino、rle_sprite.h 与全部 13 个 sprite_*.h 文件在同一个 clawd_mochi/ 草图目录中。

• Wi-Fi 版：Clawd/资料-wifi版.zip → clawd_mochi/clawd_mochi/clawd_mochi.ino
• 有线版：Clawd/资料-有线版.zip → 资料-有线版/clawd_mochi/clawd_mochi/clawd_mochi.ino
• 蓝牙版：Clawd/资料-蓝牙版.zip → clawd_mochi/clawd_mochi/clawd_mochi.ino

通用板卡设置如下：

• Board: ESP32C3 Dev Module
• USB CDC On Boot: Enabled
• CPU Frequency: 160 MHz
• Upload Speed: 921600
• Partition Scheme: Huge APP (3MB No OTA/1MB SPIFFS)

特别说明：

• 13 个表情资源约占 1MB，默认分区可能报程序过大，必须选择 Huge APP
• 有线版必须启用 USB CDC On Boot，否则电脑侧串口事件不会到达固件
• Wi-Fi 与 BLE 版也建议保持 USB CDC On Boot 为 Enabled，方便查看烧录日志

第五步：按版本完成连接

Wi-Fi 版

1. 首次启动后设备会进入 ClaWD-Mochi 配网热点，密码 clawd1234。
2. 手机连接热点后打开配网页面；如未自动弹出，请访问 http://192.168.4.1。
3. 在网页中选择 2.4GHz Wi-Fi、输入密码并保存。
4. 设备重启后会显示 IP，可通过 http://clawd-mochi.local 或设备 IP 访问。

有线 USB 版

1. 用数据线把设备直接接到运行 Codex 的电脑。
2. 设备通过 Espressif VID_303A&PID_1001 自动识别串口。
3. 不需要配网，不需要桥接。

蓝牙 BLE 版

1. 安装 Python 3.9+ 与 bleak，再启动 clawd-mochi-ble-bridge.py 桥接进程。
2. 桥接在本机监听 127.0.0.1:49374。
3. 设备通过 BLE 广播 Clawd Mochi 服务，桥接连接后负责写入状态字。

第六步：安装 Codex hooks

每个版本包里都要选择 clawd-mochi-cx/（Codex 版），不要误用 clawd-mochi-cc/（Claude Code 版）。

Windows

1. 把 clawd-mochi-codex.cmd 和 clawd-mochi-codex.ps1 放进 ~/.codex/hooks/
2. 用提供的 hooks.json 合并到 ~/.codex/hooks.json
3. 把 __HOOKS_DIR__ 替换成实际的 hooks 目录路径
4. Wi-Fi 版另把设备地址写入 ~/.codex/hooks/clawd-mochi.url
5. BLE 版还要复制并启动桥接文件
6. 重启 Codex，执行 /hooks 并信任这些 hook

macOS / Linux

1. 把 clawd-mochi-codex.sh 放入 ~/.codex/hooks/ 并执行 chmod +x
2. 把 hooks.macos.json 的 hooks 对象合并到 ~/.codex/hooks.json
3. Wi-Fi 版把设备地址写入 ~/.codex/hooks/clawd-mochi.url
4. BLE 版同时复制并运行 clawd-mochi-ble-bridge.py 与 start-bridge.sh
5. 重启 Codex，执行 /hooks 并信任这些 hook

第七步：做一次联调测试

推荐测试方式如下：

• Wi-Fi 版：curl "http://<设备IP>/event?s=coding"
• 有线版：执行 PowerShell 脚本并传 -State coding
• 蓝牙版：Invoke-RestMethod "http://127.0.0.1:49374/event?s=coding"

测试通过后，正常使用 Codex 时就会看到桌宠跟随状态切换表情。

补充说明

• 新版资料已同时提供 Windows、macOS 和 Linux 的 Codex 接入脚本
• 正常状态包括 thinking、reading、coding、running、delegating、planning、waiting、compacting、notify、done、error 与 sleep