快速开始
本页用于说明 ClawdMochi 首次接入的最短流程。
先下载 ClawdMochi 客户交付包（2026-08-08）。解压后先按设备版本进入 资料-wifi版/、资料-有线版/ 或 资料-蓝牙版/。每个文件夹都已有烧录图、使用图、Codex Skill、Claude Code Skill 和 Windows/macOS 一键烧录包。
第一步：先确认版本
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 线
接线表在三套参考文档中保持一致：
| 屏幕引脚 | ESP32-C3 GPIO | 说明 |
|---|---|---|
| VCC | 3V3 | 只能接 3.3V |
| GND | GND | 地线 |
| SDA | GPIO 10 | SPI MOSI |
| SCL | GPIO 8 | SPI SCK |
| RST | GPIO 2 | 复位 |
| DC | GPIO 1 | 数据 / 命令 |
| CS | GPIO 4 | 片选 |
| BL | GPIO 3 | 背光 |
第三步：准备烧录文件
资料包已经包含预编译固件和烧录工具，无需 Arduino IDE 或编译环境。先打开所选版本文件夹中的 图文教程①·烧录版.png，再保留烧录目录中的全部文件：
- Windows：
firmware.bin、esptool.exe、flash-windows.bat - macOS：
firmware.bin、esptool.py、flash-mac.sh、双击烧录.command
第四步：烧录固件
用支持数据传输的 USB 线连接设备，选择正确的系统与设备版本目录后烧录：
- Windows：进入
烧录-Windows/，双击flash-windows.bat，按提示选择 COM 口。 - macOS：进入
烧录-macOS/，推荐双击双击烧录.command；若没有权限，先在终端对该文件和flash-mac.sh执行chmod +x。也可进入目录后运行bash flash-mac.sh。
烧录前请关闭 Arduino IDE、串口监视器等可能占用串口的软件。烧录完成后重新插拔设备再测试；蓝牙版也必须通过 USB 数据线烧录。
第五步：按版本完成连接
Wi-Fi 版
- 首次启动后设备会进入
ClaWD-Mochi配网热点，密码clawd1234。 - 手机连接热点后打开配网页面；如未自动弹出，请访问
http://192.168.4.1。 - 在网页中选择 2.4GHz Wi-Fi、输入密码并保存。
- 设备重启后会显示 IP，可通过
http://clawd-mochi.local或设备 IP 访问。
有线 USB 版
- 用数据线把设备直接接到运行 Codex 的电脑。
- 设备通过 Espressif
VID_303A&PID_1001自动识别串口。 - 不需要配网，不需要桥接。
蓝牙 BLE 版
- 安装 Python 3.9+ 与
bleak，再启动clawd-mochi-ble-bridge.py桥接进程。 - 桥接在本机监听
127.0.0.1:49374。 - 设备通过 BLE 广播
Clawd Mochi服务，桥接连接后负责写入状态字。
第六步：安装 Codex hooks
每个版本均已附带 clawd-mochi-cx/（Codex）与 clawd-mochi-cc/（Claude Code）。两者不要混用。
Codex Skill（推荐）
- 将与你设备版本对应的完整
clawd-mochi-cx/文件夹复制到 Codex Skill 目录。
- Windows：
%USERPROFILE%\.codex\skills\clawd-mochi-cx\ - macOS / Linux：
~/.codex/skills/clawd-mochi-cx/
- 重启 Codex，然后直接告诉它“配置 Clawd Mochi”。Wi-Fi 版还需提供设备屏幕或路由器中显示的数字 IP；有线 USB 版不需要 IP；蓝牙版需保证电脑蓝牙可用。
- Skill 会引导安装对应的 hooks。完成后重启 Codex，运行
/hooks并信任 Clawd Mochi hooks。
手动安装 hooks（Windows）
Wi-Fi / 有线 USB 版：将 clawd-mochi-cx/assets/ 中的 clawd-mochi-codex.cmd、clawd-mochi-codex.ps1 和 hooks.json 复制到 %USERPROFILE%\.codex\hooks\；把 hooks.json 内的 __HOOKS_DIR__ 替换为实际绝对路径，再将其 hooks 对象合并进 %USERPROFILE%\.codex\hooks.json。
Wi-Fi 版另在 %USERPROFILE%\.codex\hooks\clawd-mochi.url 写入 http://<设备IP>。蓝牙版需要复制 assets/ 的全部文件、安装 Python 3.9+ 后执行 pip install bleak，再运行 start-bridge.cmd。
第七步：做一次联调测试
推荐测试方式如下：
- 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