如果你每天和 Claude Code 打交道超过两小时，大概率经历过这种时刻：写着写着，突然被弹窗打断——“You’ve hit your usage limit.” 然后陷入等待、刷新、再等待的焦躁循环。
这不是你的问题。Claude Code 缺少一个物理的、可见的、无需切换窗口的用量指示器。Claude Code 的配额信息藏在终端日志里，藏在 ~/.claude/settings.json 的回显里，藏在 Anthropic Console 的网页里。你根本不会时刻想着去翻它。
直到某天，冰岛的一位后端开发者 Hermann Björgvin 决定把这个问题物理化——他做了一个放在桌上的小屏幕，蓝牙连着电脑，实时显示 Claude Code 用量。更妙的是，上面还有一只像素风的 Clawd 小怪兽，用量越高它就越"忙"。
这就是 Clawdmeter。
核心思路：为什么要一块物理屏？
在看技术细节之前，先想一个问题：Alfred 能查用量，终端能查用量，浏览器控制台也能查——为什么还需要一个硬件？
答案很简单：注意力的摩擦成本。
用软件查用量，你需要经历"切换窗口→输入命令→看输出→切回来"这个流程。哪怕每次只要 10 秒，一天查 20 次也是 3 分钟，更重要的是打断了心流。你真正需要的是余光一扫就能看到的那种体验——就像开车时的仪表盘，你不需要低头去摸手机查油量。
Clawdmeter 解决了这个摩擦。它是个独立的物理设备，放在显示器底座上、键盘旁边、或者任何余光能扫到的位置。蓝色的 AMOLED 屏幕上，当前会话用量以进度条的形式实时更新，旁边还有一只像素小怪兽在跑来跑去。你不需要想它，它就在那里。
硬件拆解：30 美元的 ESP32 小屏
Clawdmeter 的核心硬件是 Waveshare ESP32-S3-Touch-AMOLED-2.16，一块集成了 ESP32-S3 芯片和 2.16 英寸 AMOLED 触摸屏的开发板。
具体参数
| 组件 | 规格 |
|---|---|
| SoC | ESP32-S3R8（双核 Xtensa LX7 @ 240MHz） |
| 屏幕 | 2.16" AMOLED，368×448 分辨率 |
| 触摸 | 电容触控（FT6336） |
| 无线 | Wi-Fi 4 + BLE 5.0 |
| 存储 | 16MB Flash + 8MB PSRAM |
| 接口 | USB-C（供电 + 刷固件） |
| 尺寸 | 约 55×75mm |
| 价格 | AliExpress ~$30，Amazon ~$41 |
注意，你买的不是成品，是一块通用开发板。你需要在上面烧录 Clawdmeter 的固件，它才会变成 Claude Code 仪表盘。当然，你也可以给这块板子刷其他固件——比如当个 MQTT 监控屏、系统资源监视器、或者智能家居控制面板。这是 ESP32 生态的优势。
为什么是这个板子？
Hermann 选择了 Waveshare 这块板子有几个原因：
- AMOLED 屏效果拔群——368×448 分辨率在 2.16 寸上非常细腻，黑色像素完全关闭 OLED 的特性让 UI 显得深邃通透，远优于同价位的 TFT LCD 屏
- 触控交互潜力——除了显示，电容触控让未来的交互扩展留有空间（比如触摸切换显示模式）
- ESP32-S3 性能足够——双核 240MHz + 8MB PSRAM 让 LVGL UI 动画流畅运行，BLE 通信不卡顿
- 渠道成熟——Waveshare 的板子在 AliExpress / Amazon 上大批量供应，任何地区的开发者都能买到
如果你已经有类似开发板（比如 ESP32-S3-Touch-AMOLED-1.8），也可以尝试适配，但需要自己修改 LVGL 的分辨率和触摸驱动。
架构：一个三层系统
Clawdmeter 不是"把 Claude API 数据推到一个屏幕"那么简单。它由三个独立的子系统组成。
┌─────────────┐ BLE ┌─────────────┐ HTTP/CLI ┌──────────────┐
│ ESP32 固件 │ ◄───────────│ 桌面守护进程 │ ◄─────────────│ Claude Code │
│ (LVGL UI) │ NimBLE │ (Python) │ 60秒轮询 │ (本机CLI) │
│ Clawd动画 │ JSON传数 │ bleak+httpx │ │ /状态/会话 │
│ BLE HID │ │ 系统托盘 │ │ │
└─────────────┘ └─────────────┘ └──────────────┘
Layer 1：Claude Code 数据源
守护进程通过 Claude Code 的本地状态文件获取用量数据。它轮询 Claude Code 的 API 状态端点，提取两个关键数字：
- 当前会话用量百分比（Session %）——你本次启动 Claude Code 后消耗了多少配额
- 每周用量百分比（Weekly %）——你这周总共消耗了多少
以及对应的重置倒计时，告诉你多久后配额会刷新。
这些数据并不暴露在 Claude Code 的用户界面里，而是藏在 CLI 状态输出中。Clawdmeter 的守护进程做的事情，本质上就是把"开发者可能需要手动执行 claude status 才能看到的东西"自动化出来。
Layer 2：桌面守护进程（Daemon）
一个 Python 编写的后台服务，核心逻辑非常简单：
- 每 60 秒调用 Claude Code 状态接口获取最新用量
- 将数据编码为 JSON（
{"s": 45, "sr": 12, "w": 68, "wr": 240, "st": "ok", "ok": true}） - 通过 BLE GATT 写入特性（UUID:
4c41555a-...-000000000002）推送到 ESP32
守护进程还做了一个很重要的设计决策：它用 systemd user session 管理（Linux），或 LaunchAgent（macOS）、系统托盘程序（Windows），确保开机自启、崩溃自动重启。
不过坦白说，60 秒轮询间隔有些保守。部分开发者反映，在做大规模重构、Token 消耗较快的时候，希望看到更实时的更新。Hermann 在 issue 里回应过，考虑到 ESP32 的电池续航和蓝牙带宽，60 秒是一个平衡点。但如果你愿意接受更高的功耗，修改 POLL_INTERVAL 参数到 10 秒也不是很难。
Layer 3：ESP32 固件（Firmware）
这部分是最有意思的。固件用 ESP-IDF + LVGL 开发，整套 UI 渲染在 ESP32-S3 上原生运行。
UI 构成：
- 用量进度条——两个环形进度条分别显示 Session 和 Weekly 用量，蓝色到红色的渐变色阶告诉你"安全"还是"危险"
- 重置倒计时——以分钟为单位显示，格式
mm:hh，让你精确知道配额何时刷新 - Clawd 像素动画——一只 32×32 像素的 Clawd 小怪兽，根据用量百分比切换动画帧：0-30% 悠闲散步，30-70% 快速跑动，70-100% 疯狂忙碌
- 状态指示器——绿色表示连接正常，红色表示守护进程离线，黄色表示数据异常
BLE HID 功能——两块侧边按键模拟蓝牙键盘，触发 Claude Code 的语音模式和命令面板。这个细节说明 Hermann 不仅把 Clawdmeter 当作显示器，还当作 Claude Code 的物理控制器。
协议效率：JSON 包体一般只有 80-120 字节，通过 BLE 传输不到 50ms。整套系统的电量消耗经实测，在 60 秒轮询频率下，一块 2000mAh 电池大约能用 15-20 小时——如果你插着 USB-C 用（大多数桌面场景），续航完全不是问题。
动手搭建：从零到亮屏
我的搭建环境是 Ubuntu 24.04 LTS + Claude Code。以下是实际操作流程。
第一步：买硬件
AliExpress 搜索 “ESP32-S3-Touch-AMOLED-2.16”，挑一个带电池版（约 $32）或者不带电池版（约 $30）。如果你桌子旁边就有 USB 口，不带电池版够用。我选的是带电池版，偶尔换个位置放也方便。
顺带推荐买一根短 USB-C 线（15-20cm），桌面走线更整洁。别用 2 米长线——这块小屏配一根长线看起来很奇怪。
第二步：烧录固件
你需要 git、python3、pip 和 platformio。PlatformIO 是 VS Code 的一个插件，也是 CLI 工具，负责编译和烧录 ESP32 固件。
# 安装 PlatformIO CLI
pip install platformio
# 克隆仓库
git clone https://github.com/HermannBjorgvin/Clawdmeter.git
cd Clawdmeter
# 编译并烧录（连接 USB-C 后）
./flash.sh
flash.sh 会自动检测你的开发板 env name，省去手动配置的麻烦。如果你是 macOS 用户，使用 flash-mac.sh。
烧录过程大约 3 分钟（取决于你的机器和 USB 速度）。烧录完成后，重启开发板，屏幕上应该出现 Clawdmeter 的启动画面——一只像素 Clawd 从屏幕左边跑到右边。
一个小坑：如果你买了不同版本的 Waveshare 板子（比如 1.8 寸版本），需要手动修改 firmware/platformio.ini 中的 board_build.variant 参数。GitHub 仓库的 README 里有一个兼容性表格，先确认自己的板子型号再操作。
第三步：配对蓝牙
# 启动蓝牙扫描
bluetoothctl
scan on
# 找到 Clawdmeter 设备
# 大约 30 秒后会看到 [NEW] Device XX:XX:XX:XX:XX:XX Clawdmeter
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
配对一次即可。如果你需要重新配对（比如更换电脑），按住电源键 3 秒再松开——设备会清除已保存的配对信息并重新广播。
第四步：启动守护进程
# 安装依赖
pip install bleak httpx pystray
# 将守护进程复制到用户目录
cp daemon/claude-usage-daemon.py ~/.local/bin/
chmod +x ~/.local/bin/claude-usage-daemon.py
# 注册 systemd 用户服务
mkdir -p ~/.config/systemd/user/
cp daemon/claude-usage-daemon.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now claude-usage-daemon
# 确认运行正常
systemctl --user status claude-usage-daemon
journalctl --user -u claude-usage-daemon -f
启动后大约 60 秒钟，你应该看到 ESP32 屏幕上的数据从--%变为实际的用量数字。如果一直不更新，检查蓝牙连接状态：
bluetoothctl info XX:XX:XX:XX:XX:XX # 确认 Connected: yes
一个常见问题是 BLE 连接被系统蓝牙管理器抢占。Ubuntu 的 bluetooth 服务有时会与 bleak（Python BLE 库）冲突。如果遇到守护进程日志中出现 connection refused 或 disconnected，尝试：
# 重启蓝牙栈
sudo systemctl restart bluetooth
systemctl --user restart claude-usage-daemon
第五步（可选）：Windows 用户
Clawdmeter 原生支持 Windows，无需 WSL。使用 setup.exe 安装系统托盘程序，自带蓝牙配对界面和自动启动设置。如果你主力是 Windows，体验甚至比 Linux 更顺滑，因为 Windows 的 BLE 栈对 bleak 兼容性更好，配对过程自动化程度更高。
与纯软件方案对比
在 Clawdmeter 之前，监控 Claude Code 用量有几种方式：
| 方案 | 成本 | 实时性 | 余光体验 | 电池续航 | 维护成本 |
|---|---|---|---|---|---|
claude status 手动查 |
免费 | 查时才有 | ❌ 熄屏不可见 | N/A | 零 |
| CodexBar（macOS 菜单栏） | 免费 | 实时 | 需切换桌面/菜单栏 | N/A | 零 |
| claude-tap（API 抓包） | 免费 | 近实时 | 需打开 Web UI | N/A | 需启动服务 |
| Clawdmeter | ~$30 硬件 | 60秒延时 | ✅ 物理可见 | 15-20h | 烧录+守护进程 |
| 自定义脚本+通知 | 免费 | 可配置 | ❌ 通知消失即忘 | N/A | 需自己写 |
Clawdmeter 的不可替代之处：物理存在感。Alfred 的菜单栏图标虽然也能显示用量，但你得专门去看它。而 Clawdmeter 放在显示器旁边，你无法忽略它——就像小时后书桌上放的倒计时闹钟，物理物体的存在感是数字界面无法替代的。
不过也要诚实地说，Clawdmeter 的门槛确实高——你需要自己焊（其实不用焊，Waveshare 板子是成品）、自己刷固件、自己配蓝牙。不是每个开发者都愿意花这个时间。
Clawd 小怪兽：为什么一个像素动画这么重要？
这一点值得单独聊。
Clawdmeter 最出圈的设计不是用量监控，是那只 32×32 的像素 Clawd。它在屏幕上跑来跑去，根据你的用量调整行为。用量低的时候它悠哉悠哉地散步；用量过半它开始小跑；接近限额时它疯狂奔跑。
这不只是一个彩蛋。Hermann 在设计文档里提到了一个有趣的观察：人对抽象数字不敏感，但对拟人化行为有本能反应。
“When I saw Clawd running frantically, I actually felt the pressure. It’s different from seeing ‘87%’ in a terminal.” ——摘自项目 README
这一点我深有体会。在测试中，用量 45% 的时候 Clawd 还在悠闲散步，我甚至注意到了它的步伐。但当它开始快速移动时，我产生了一种"它很累"的错觉，下意识地放慢了编码节奏，检查有没有不必要的 API 调用。
这不是说 Clawd 在操控你的行为，而是物理抽象层的力量——一个无意义的百分比变成了一个有意义的感官信号。如果你设过闹钟、用过番茄钟，就理解这种感觉：物理对象的反馈比数字界面的反馈更能触发行动。
扩展思考：物理仪表盘的复兴
Clawdmeter 不是孤例。2025-2026 年，ESPHOME 驱动的 MQTT 显示器、Hass Panel 智能家居控制屏、基于 Inkplate 的"电子纸日历"都在开发者桌面上越来越多。
这个趋势的底层逻辑是：信息密度已经超过了大脑的实时处理能力。我们有 20 个 Slack 频道、30 个 GitHub 仓库、5 个 CI 流水线、3 个云服务控制台——它们都在争先恐后地通知你。而传统 push notification 模式已经失效：通知太多等于没有通知。
物理仪表盘做了一件反直觉的事：它把信息从"需要你主动去看"变成了"被动但永远可见"。你不需要滑动解锁、不需要打开 App、不需要切换窗口。它就在那里。
Clawdmeter 很好的诠释了这个思路。它只做一件事，只展示一个指标，而且永远可见。这种单用途仪器（Single-purpose Instrumentation）的设计哲学，值得每一个过度忙碌的开发者思考。
总结与购买建议
你应该买来搭一个，如果你：
- 每天 Claude Code 用量超过 30% 配额
- 对桌面设备 DIY 有耐心（至少能刷 ESP32 固件）
- 想体验"物理 vs 数字"的交互差异
- 30 美元对你来说不是大开销
你可能不需要，如果你：
- 只用 Claude Code 做零星的代码解释/小型修改
- 觉得"查用量"本来就不是频繁操作
- 不想在桌面上多一个小屏
改进空间：
- Wi-Fi 模式——目前只支持 BLE，但 ESP32-S3 本身有 Wi-Fi，如果支持 Wi-Fi 直连，延迟会更低、可靠性更高
- 多工具支持——Claude Code、Codex、Cursor、Gemini CLI……如果能通过配置切换数据源，受众会更大
- 更强的电量管理——2000mAh 电池在 60 秒轮询下只能撑 15-20 小时，如果实现"当屏幕无操作时深度休眠"，续航可能翻倍
- 社区主题——目前只有默认的深色主题 + Clawd 动画，如果能支持自定义壁纸和 SVG 渲染，个性化空间会更大
不过，对于一个一个人的开源项目来说，Clawdmeter 已经超出了预期。一刷固件、一个守护进程、一套蓝牙协议，不到四周就从想法变成可以每天使用的东西。这种"解决问题后顺便赚个趣味性"的做派，只能说——很冰岛。
项目地址：github.com/HermannBjorgvin/Clawdmeter
硬件清单：Waveshare ESP32-S3-Touch-AMOLED-2.16（AliExpress / Amazon 均可购买，约 $30）