onWatch：AI API 配额监控的全链路工程实践

场景切入：当 Star 余额见底，Claude Code 在凌晨 2 点断了

凌晨 2 点，你正在调试一个关键功能，Claude Code 突然弹出一条冷冰冰的报错："Rate limit exceeded"。你打开 Anthropic 控制台，发现只剩下 2% 的 5 小时窗口配额——但你不知道它什么时候重置，也不知道这周还会不会触发月额上限。

这就是 onWatch 诞生的直接原因。

大多数 AI 开发者都经历过类似的"盲操作"时刻：只能看到当前快照，看不到历史趋势；只能被动等限流，无法提前预警。onWatch 的作者 prak3rsh 做了一个开发者本该早就有的工具——一个持续在后台运行的轻量级守护进程，把所有 AI API 的配额变化记录下来，以可视化仪表盘呈现，让用户对自己的 AI 资源消耗了如指掌。

图1：Anthropic 配额监控面板（Dark Mode）

背景：多 Agent 时代的配额焦虑

随着 Claude Code、Codex、GitHub Copilot、Cursor 等 AI 编程工具在 2025-2026 年迅速普及，开发者日常使用的 AI 服务提供商数量急剧增加。每个平台都有自己独立的配额体系、重置周期和通知机制——Anthropic 有 5 小时窗口、7 天滚动窗口、月度配额；Codex 有 LLM 请求数和 Review 配额；GitHub Copilot 有 Premium Interactions、Chat、Completions 三个维度……

这种碎片化带来了真实的痛点：预算规划困难、团队无法共享使用数据、寅吃卯粮导致关键任务受阻。onWatch 正是瞄准这个空白——一个统一视图，把所有主流 AI 编程工具的配额数据汇聚到一处。

核心功能：从"当前快照"到"历史全览"

onWatch 真正解决的是"历史数据缺失"这个根本问题。官方控制台只给你一个实时数字，onWatch 则记录每一个采样点，让你看到：

配额趋势与周期检测：通过持续记录每日快照，onWatch 能自动识别每个平台的配额重置周期（5 小时窗口、每日窗口、每周窗口、月度窗口），并显示距离下次重置的精确倒计时。这是原始 API 根本不提供的信息。

消费速率预测：基于历史数据，onWatch 计算当前消费速率，预测配额何时耗尽。用户可以提前知道"按目前使用速度，5 小时窗口还剩 47 分钟"——这比等到限流报错才行动要体面得多。

会话级追踪：每个 API 会话的开始、活跃时长和结束都被单独记录，便于统计单个功能模块或工作日的 AI 资源消耗。这对研究人员和需要向 grant 汇报经费使用情况的开发者尤其有价值。

多提供商统一视图：Synthetic（搜索配额、工具调用配额）、Z.ai（Token/时间/工具调用三维配额）、Anthropic（Claude Code）、Codex（GPT-4o、Review）、GitHub Copilot（Premium Interactions、Chat、Completions）、MiniMax（共享资源池）、Gemini CLI、Antigravity（IDE Probe 或 agy CLI 两种数据源）、Cursor（个人/团队/企业）、Grok（xAI 积分）、OpenRouter——九大平台同时追踪，一个仪表盘搞定。

图2：Z.ai 配额监控面板（Light Mode）

架构解析：单二进制、SQLite WAL、Go 并发 Agent

onWatch 的工程实现有不少值得学习的地方。

代码结构采用标准 Go 项目布局：436 个文件分布在 internal/ 下，按职责分为 Agent 层（轮询各平台 API）、API 层（各平台 HTTP 客户端）、Store 层（SQLite 持久化）、Tracker 层（配额数据聚合）、Web 层（仪表盘服务）和 Notify 层（邮件/推送通知）。

并发模型是关键设计。每个平台的轮询逻辑运行在独立的 goroutine 中，所有 Agent 并行执行。实测内存占用：8 个 Agent 同时运行时空闲约 34MB，高负载约 43MB，远低于作者设定的 50MB 上限。这主要得益于单进程单 SQLite 连接（WAL 模式保障并发安全）和轻量级 HTTP 请求。

SQLite WAL 模式值得展开：WAL（Write-Ahead Logging）允许多个读操作与一个写操作并发进行，这对 onWatch 的"多个 Agent 写入 + Web 仪表盘读取"场景非常理想。每次轮询只写入增量快照，数据量可控，查询效率高。

单二进制部署是另一个亮点。Go 1.25 编译的静态二进制（CGO_ENABLED=0），所有 Web 静态资源（JS/CSS/HTML/Icons）通过 go:embed 打包进二进制，安装后只有一个可执行文件，无外部依赖。

Docker 镜像构建采用多阶段 Dockerfile：builder 阶段用 Alpine + Go 1.25 编译，最终阶段提供两个选择——distroless/static-debian12（非 root、最小化镜像，约 10-12MB）和 Alpine shell variant（有 shell、方便调试）。内存限制在 Docker Compose 中设为 64MB 软上限、32MB 硬下限，展示了极佳的资源控制意识。

部署体验：三条命令即可上线

onWatch 的部署体验设计得非常友好。三种部署方式：

Docker（推荐，一条命令）：cp .env.docker.example .env 填入 API Key，docker-compose up -d 搞定。数据通过 volume 持久化到 ./onwatch-data/。

一键安装脚本：Linux/macOS：curl -fsSL https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.sh | bash，PowerShell：irm https://raw.githubusercontent.com/onllm-dev/onwatch/main/install.ps1 | iex。安装脚本自动下载二进制、创建 systemd 服务（Linux）或自守护进程（macOS）。

Homebrew（macOS/Linux）：brew install onllm-dev/tap/onwatch，适合已熟悉 Homebrew 生态的开发者。

安装完成后打开 http://localhost:9211，用 .env 中的管理员账号登录即可。

Anthropic 限流绕过的工程细节

一个有意思的技术细节是 onWatch 如何处理 Anthropic 的 API 限流。Anthropic 的使用量 API 有严格的请求频率限制（约每 Token 5 次请求，超出后返回 429 并封禁约 5 分钟）。onWatch 的解决方案是：当检测到 429 响应时，自动刷新 OAuth Token——每个新的 Access Token 都有全新的频率限制窗口，从而实现"绕过限流"的效果。

实现涉及三个文件：internal/agent/anthropic_agent.go（检测 429 并触发刷新）、internal/api/anthropic_oauth.go（调用 console.anthropic.com 的 OAuth Token 刷新端点）、internal/api/anthropic_token_unix.go（macOS Keychain + 文件双重持久化）。Refresh Token 采用 OAuth 轮换机制（一次性使用），刷新后必须保存新的 Refresh Token。

局限与争议

平台锁定风险：onWatch 目前紧耦合各平台 API，Anthropic/Codex/Copilot 等任何一方修改 API 端点或认证机制都可能导致轮询失效。虽然代码中有完整的测试覆盖（大量 _coverage_test.go 文件），但维护成本会随着平台数量增加而增长。

数据本地化依赖：没有云端同步，团队协作场景下每人需要单独安装和配置 API Key，无法共享配额视图。

安全考量：.env 文件包含明文 API Key，虽然有 .gitignore 保护，但本地 SQLite 数据库中的历史数据没有加密，敏感企业场景下需要自行评估。

行业意义

onWatch 的增长轨迹（2026 年 2 月建库，6 月已达 668+ Star）是 AI 编程工具大规模普及的一个缩影。随着 Claude Code、Cursor、Codex 成为越来越多开发者的日常工具，"配额焦虑"从个人问题演变为群体痛点，催生了对专业监控工具的需求。这个赛道还在早期，onWatch 目前是难得的高质量开源方案——代码规范（TDD、race detector、SQL 注入防护）、文档完善（多平台安装指南、FAQ、架构图）、发布流程自动化（GitHub Actions 跨平台编译），展现了一款成熟开源工具的专业度。

图3：Antigravity 多模型配额面板（Light Mode）

总结

onWatch 解决了一个非常具体但广泛存在的痛点：多 AI 编程工具的配额可视化。它以轻量级单二进制 + SQLite 本地存储 + Material Design 3 仪表盘的组合，提供了比官方控制台更完整的历史视角和消费预测。部署门槛低（Docker 一行命令），资源占用极低（<50MB RAM），支持平台最多（9 大平台），对于每天重度使用 AI 编程工具的开发者来说，是一个值得长期运行在后台的实用工具。