Clawdmeter：用 ESP32 打造 Claude Code 桌面用量仪表盘

📅 2026年05月18日 · 技术

Clawdmeter：用 ESP32 打造 Claude Code 桌面用量仪表盘

引言

重度使用 Claude Code 的开发者常常会遇到一个烦恼：不知道这个月的额度还剩多少，也不知道今天的编码会话用了多少比例。与其每次都切到浏览器去看，不如直接在桌面上放一个实时显示的物理仪表盘——这就是 Clawdmeter 的设计初衷。这款基于 ESP32 的小型桌面设备通过蓝牙连接你的电脑，实时显示 Claude 使用量，还内置了可爱的像素风 Clawd 动画，让监控用量变成一件有趣的事。

项目介绍

Clawdmeter 由开发者 Hermann Björgvin 制作，基于 Waveshare ESP32-S3-Touch-AMOLED-2.16 开发板，配备 2.16 英寸 480×480 AMOLED 触摸屏。设备通过蓝牙 BLE 与电脑配对，由后台守护进程每 60 秒轮询一次 Claude API 获取用量数据，然后推送到屏幕上实时显示。

除了用量显示，设备还内置了来自 claudepix（由 @amaanbuilds 创作）的像素风 Clawd 动画——当你的使用率升高时，动画会变得更加忙碌活跃，让枯燥的额度监控多了一份趣味。

核心特性

1. 三屏切换设计

设备启动后停留在启动画面（Splash），按下中间按钮可在 用量屏（Usage） 和 蓝牙屏（Bluetooth） 之间切换：

Splash 画面：像素风 Clawd 动画，根据使用率自动切换不同心情组的动画，每 20 秒轮换一次
Usage 画面：显示当前会话用量百分比和本周累计利用率
Bluetooth 画面：显示蓝牙连接状态和 MAC 地址，支持重置绑定

2. 物理按键作为 Claude Code 快捷键

三个侧边按钮不只是导航用途：

左侧按钮（GPIO 0）：长按发送 Space 键——对应 Claude Code 语音模式的 Push-to-Talk
右侧按钮（GPIO 18）：按下发送 Shift+Tab——对应 Claude Code 的模式切换
中间按钮：循环切换屏幕，在 Splash 画面下则切换动画

按键通过标准 BLE HID 键盘协议发送，所以在配对主机上任何聚焦的窗口都能响应。

3. 自定义 BLE 数据协议

设备除了 HID 键盘服务外，还暴露了一个自定义 GATT 服务（UUID: 4c41555a-...），守护进程通过写入 JSON 负载来更新用量数据：

{ "s": 45, "sr": 120, "w": 28, "wr": 7200, "st": "allowed", "ok": true }

其中 s=会话百分比，w=周百分比，st=状态（allowed/blocked）。

4. 跨平台支持

固件用 PlatformIO 开发，基于 LVGL 图形库。守护进程同时支持 Linux（systemd user service）和 macOS（LaunchAgent + Python venv），macOS 版本由 Chris Davidson 移植。

适用人群

Claude Code 重度用户：随时掌握使用额度，避免超额
嵌入式开发爱好者：学习 ESP32 + LVGL + BLE 的完整项目实践
桌面美化玩家：AMOLED 触摸屏 + 像素动画，颜值在线
硬件折腾党：从固件烧录到字体重编译，DIY 空间很大

快速上手

硬件准备：Waveshare ESP32-S3-Touch-AMOLED-2.16 开发板 + USB-C 线 + 可选锂电池。

Linux 安装：

# 烧录固件
cd firmware
pio run -t upload --upload-port /dev/ttyACM0

# 蓝牙配对
bluetoothctl scan le
bluetoothctl pair F4:12:FA:xx:xx:xx   # 使用你的设备 MAC
bluetoothctl trust F4:12:FA:xx:xx:xx

# 安装守护进程
./install.sh
systemctl --user start claude-usage-daemon

macOS 安装：

./flash-mac.sh                        # 自动检测 USB 串口
# 在系统设置 → 蓝牙中连接 "Clawdmeter"
./install-mac.sh                      # 安装 LaunchAgent

总结

Clawdmeter 是一个精巧的硬件 hack 项目，它把 Claude Code 的 API 额度监控从"打开网页查看"变成了一块放在桌上的 AMOLED 小屏幕。像素风 Clawd 动画、BLE HID 快捷键、自定义 GATT 协议——这些细节让它不仅实用，还好玩。对于每天和 Claude Code 打交道的开发者来说，这是一个有温度的生产力小工具。如果你喜欢动手做硬件，这个项目值得一试。

参考来源

Clawdmeter — GitHub