返回博客列表

Clawdmeter：一个 ESP32 小屏幕，让你的 Claude Code 用量一目了然

2026-05-31T09:10:00+08:00
ClawdmeterESP32Claude Code硬件IoT开源硬件

Clawdmeter：一个 ESP32 小屏幕，让你的 Claude Code 用量一目了然

先收藏，回头一定用得上。

重度 Claude Code 用户都有一个焦虑：我这个月还剩多少额度？ 每次得打开终端敲命令查，或者登录后台看。Hermann Bjorgvin 的方案更直接——在桌上放个小屏幕，扫一眼就知道。

Clawdmeter 是一个基于 ESP32 的开源桌面仪表盘，通过蓝牙连接电脑，实时显示你的 Claude Code 会话用量和周用量。GitHub 上 1.4K Stars，160+ Forks。不只是个显示器，侧边按钮还能触发 Claude Code 的语音模式和模式切换。

本文提纲

  1. 它是什么：桌上的 Claude Code 用量计
  2. 硬件：支持哪些开发板
  3. 三个屏幕：Splash、Usage、Bluetooth
  4. 工作原理：从 API 到屏幕的数据链路
  5. 物理按钮：不只是看，还能操作
  6. 安装：Linux 和 macOS
  7. 移植指南

它是什么：桌上的 Claude Code 用量计

一个 Waveshare AMOLED 小屏幕，运行 ESP32 固件，通过 BLE（低功耗蓝牙）和你的电脑配对。后台 daemon 每 60 秒轮询一次 Anthropic API，拿到用量数据，推送到屏幕上显示。

graph LR
    A[Claude Code
OAuth Token] -->|API Poll| B[Host Daemon
Linux / macOS]
    B -->|BLE JSON| C[ESP32 Firmware]
    C -->|LVGL UI| D[AMOLED Display]
    C -->|BLE HID| E[Keyboard Input
Space / Shift+Tab]
    D -->|Visual| F[Usage Meter
+ Clawd Animations]

启动画面是像素风格的 Clawd（Claude 的吉祥物）动画，动画的忙碌程度随用量变化——用量低时 Clawd 悠闲，用量高时 Clawd 忙得不可开交。动画素材来自 claudepix，@amaanbuilds 的像素风 Clawd 精灵库。

硬件：支持哪些开发板

开箱支持三款 Waveshare AMOLED 开发板：

开发板 屏幕 芯片
ESP32-S3-Touch-AMOLED-2.16 2.16" AMOLED ESP32-S3
ESP32-C6-Touch-AMOLED-2.16 2.16" AMOLED ESP32-C6
ESP32-S3-Touch-AMOLED-1.8 1.8" AMOLED ESP32-S3

固件用 C 写的（PlatformIO 构建，LVGL 做 UI），大约 180 万字符 C 代码。架构是薄 HAL 层加 per-board 文件夹——firmware/src/boards/ 下每个板子一个目录，核心代码（main.cpp、ui.cpp、splash.cpp）完全不用改。

三个屏幕：Splash、Usage、Bluetooth

设备启动进入 Splash（动画屏），按中间按钮切换：

Splash（动画屏）：像素风 Clawd 动画，根据当前用量率自动选择"情绪组"——低用量悠闲、高用量忙碌。每 20 秒自动轮换同组内不同动画。触屏可切换回 Usage，再触一下切回来。

Usage（用量屏）：显示两个关键指标——会话用量百分比（Session %）和周用量百分比（Weekly %），以及各自的倒计时（还剩多少分钟重置）。

Bluetooth（蓝牙屏）：显示连接状态和设备 MAC 地址，用于配对。还有 Reset 按钮清除蓝牙绑定。

工作原理：从 API 到屏幕的数据链路

整个数据流分 6 步：

  1. Daemon 读取 OAuth Token：macOS 从 Keychain 读，Linux 从 ~/.claude/.credentials.json 读
  2. 调一次最小 API 请求：向 api.anthropic.com/v1/messages 发一个基本免费的请求（一个 Haiku token）
  3. 从 Response Headers 拿用量：anthropic-ratelimit-unified-5h-utilization 等 header 字段直接给出用量百分比
  4. BLE 推送到 ESP32：连接设备的 GATT RX Characteristic，写入 JSON payload：
{ "s": 45, "sr": 120, "w": 28, "wr": 7200, "st": "allowed", "ok": true }
  • s：Session 用量百分比
  • sr：Session 重置剩余分钟
  • w：Weekly 用量百分比
  • wr：Weekly 重置剩余分钟
  • st：状态（allowed/paused）
  • ok：成功标志
  1. 固件解析 JSON 并更新 LVGL 界面
  2. 追踪变化率：固件用 5 分钟滑动窗口追踪 Session% 的变化速率，据此选择对应"情绪组"的 Splash 动画

这个设计的精妙之处在于用量数据是从 API Response Headers 拿的，不需要额外计费。一次几乎免费的 API 调用就把所有信息带回来了。

物理按钮：不只是看，还能操作

三个侧边按钮，左和右在所有屏幕上功能一致，中间按钮根据当前屏幕切换行为：

按钮 功能
左 长按发送 Space（Claude Code 语音模式 Push-to-Talk）
中（PWR） 切换屏幕；在 Splash 屏幕上切换动画
右 按下发送 Shift+Tab（Claude Code 模式切换）

Space 和 Shift+Tab 通过标准 BLE HID 键盘协议发出——意味着它们会在配对主机上当前焦点窗口生效，不限于 Claude Code。相当于你的桌上多了一个蓝牙快捷键小键盘。

安装：Linux 和 macOS

Linux：

# 烧录固件
./flash.sh waveshare_amoled_216

# 蓝牙配对
bluetoothctl scan le
bluetoothctl pair 
bluetoothctl trust 

# 安装后台 daemon
./install.sh
systemctl --user start claude-usage-daemon

macOS（由 Chris Davidson @lorddavidson 移植）：

# 烧录固件
./flash-mac.sh waveshare_amoled_216

# 系统设置 → 蓝牙 → 连接 "Clawdmeter"

# 安装 daemon（从 macOS Keychain 读 OAuth Token）
./install-mac.sh

macOS 版 daemon 用 Python（bleak + httpx），通过 LaunchAgent 常驻后台，首次运行会弹出蓝牙权限请求。

移植指南

想适配其他 ESP32 开发板？固件架构已经做好了隔离：

  • HAL 层：每个板子一个文件夹，实现显示驱动、按钮 GPIO、触摸输入等接口
  • 核心 UI 代码完全不用改
  • 新建一个 PlatformIO env + 板子文件夹即可

文档在 docs/porting/ 目录下，有 adding-a-board.md 和 hal-contract.md 两个指南。

有一点需要注意：项目使用了 Anthropic 的品牌字体（Tiempos Text、Styrene B）和 Clawd 吉祥物的版权素材，作者因此没有采用标准的 copyleft 许可证。fork 或复制代码时需要留意这个版权灰色地带。

Clawdmeter 展示了一个有趣的思路：当 AI 编程工具成为日常，桌上的物理小装置就能提供"低头看一眼"的即时反馈——比打开终端查日志自然得多。1.4K Stars 说明不少人想要这个。

你有在用什么硬件小工具辅助开发？评论区聊聊。觉得有意思点个赞让更多人看到。

作者: itech001
来源: 公众号：AI人工智能时代
网站: https://www.theaiera.cn/ 每日分享最前沿的AI新闻资讯和技术研究。

本文首发于 AI人工智能时代，转载请注明出处。

觉得文章不错？分享给更多人！