ClawdMochi Docs

使用手册

ClawdMochi 客户交付包的完整使用流程、图文教程、Codex Skill 与三种连接方式说明。

ClawdMochi 展示图

使用手册

完整使用流程

  1. 组装硬件并按接线表连好屏幕与 ESP32-C3。
  2. 从 2026-08-08 客户交付包选择对应的设备版本，按包内图文教程完成烧录。
  3. 按版本完成 Wi-Fi 配网、USB 直连或 BLE 桥接。
  4. 将对应版本的完整 clawd-mochi-cx/ 文件夹安装到 ~/.codex/skills/，让 Codex 按 Skill 配置 hooks。
  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 只负责供电，不负责数据；也可使用充电器或移动电源

交付包图文教程

请只查看与你设备版本一致的图文教程。烧录图适用于 Windows 与 macOS；使用图包含该版本的连接方法与 Skill 安装步骤。

Wi-Fi 版

Wi-Fi 版使用教程

有线 USB 版

有线 USB 版使用教程

蓝牙 BLE 版

蓝牙 BLE 版使用教程

安装 Codex Skill

  1. 从所选版本目录复制整个 clawd-mochi-cx/ 文件夹，而不是只复制 SKILL.md。
  2. Windows 放到 %USERPROFILE%\.codex\skills\clawd-mochi-cx\；macOS / Linux 放到 ~/.codex/skills/clawd-mochi-cx/。
  3. 重启 Codex，告诉它“配置 Clawd Mochi”。Wi-Fi 版提供设备数字 IP；有线版保持设备通过数据线连接；蓝牙版允许电脑蓝牙并按提示安装桥接依赖。
  4. 配置完成后重启 Codex，执行 /hooks 并信任 Clawd Mochi hooks。

软件运行方式

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

设备侧显示逻辑

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

状态说明
idle待机，显示用户选择的静态外观
thinking新一轮开始，思考表情
reading读代码 / 搜索状态
coding写代码 / 编辑文件
running运行命令
delegating启动子代理、任务或线程交接
planning更新或展示计划
waiting等待用户确认或回复
compacting压缩上下文
notify通知或外部服务需要注意
done本轮完成，短暂庆祝后回到待机
error出错
sleep长时间空闲后休眠

状态切换规则

状态切换规则如下：

  • 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 等工作态的固定风格。

补充说明

  • 本产品不提供单独的手机 App
  • Windows 主要使用 .cmd / .ps1，macOS 与 Linux 使用 .sh
  • Codex 使用 clawd-mochi-cx/；clawd-mochi-cc/ 是 Claude Code 版
快速开始查看说明使用手册当前页面固件 / 安装查看说明散件安装查看说明高级教程查看说明常见问题查看说明使用注意查看说明