TokenTelemetry：AI Agent 的本地可观测性仪表盘

当你在凌晨三点盯着屏幕，看着 Claude Code 疯狂烧 token...

你有没有过这种经历：半夜跑了一个重构任务，早上起来一看 Claude Code 账单——45 美元。你甚至不记得它干了什么。

或者你在用三个不同的 Agent（Claude Code 写代码、Copilot 查文档、Gemini CLI 做分析），每个工具的 token 计费方式都不一样，根本没法横向比较。

TokenTelemetry 就是来解决这个问题的。

它是什么

TokenTelemetry 是一个完全本地运行的 AI Agent 可观测性仪表盘，追踪所有主流 AI 编程 Agent 的 token 用量、LLM API 费用、工具调用次数、Session 轨迹和推理步骤。

核心特点：

• 100% 本地：数据永不离开你的机器，不上传到任何云端
• 多 Agent 聚合：Claude Code、Codex、Cursor、Copilot、Gemini CLI、OpenCode、Qwen 等 18+ 个 Agent 的数据统一展示
• 费用追踪：按模型、按项目、按会话的精确 API 费用统计
• 零配置：自动从各 Agent 默认日志路径读取数据

支持的 Agent

TokenTelemetry 目前已支持 18 个编程 Agent 和 1 个自主 Agent（Hermes Agent）：

Agent	状态
Claude Code (Anthropic)	✅ 完全支持
Gemini CLI (Google)	✅ 完全支持
OpenAI Codex CLI	✅ 完全支持
Cursor	✅ 完全支持
GitHub Copilot	✅ 完全支持
OpenCode	✅ 完全支持
Qwen (阿里通义)	✅ 完全支持
Kimi Code (Moonshot)	✅ 完全支持
Hermes Agent (Nous Research)	✅ 专属仪表盘

特别值得一提的是 Hermes Agent 专属仪表盘——因为 Hermes Agent 本身是个跨平台自主 Agent（支持 CLI、Telegram、Discord、Cron、Webhook 等 38 个平台），TokenTelemetry 为其专门设计了 /hermes 路由，追踪每个 API 调用的延迟、缓存命中率、delegate_task 子 Agent 的 token 消耗等。

技术架构

TokenTelemetry 采用前后端分离架构：

• 后端：Python + FastAPI + SQLite，数据存储轻量化
• 前端：TypeScript + Next.js，提供现代化 Web UI
• 数据采集：直接读取各 Agent 的本地日志文件（无需 API key）
• 支持 Docker 一键部署

架构亮点在于它的多代理 harness 框架（harness_panels 模块）：每个支持的 Agent 都有一个对应的 harness 实现，负责解析该 Agent 的日志格式、提取 token 计量信息，并标准化为统一数据模型。这使得添加新 Agent 支持时只需实现新的 harness 而不影响现有代码。

核心功能

1. 实时 Token 仪表盘

按 Agent、按模型、按项目实时展示 token 输入/输出量，对比不同 Agent 的效率。

2. 费用追踪与告警

设置月度/周度 token 或消费上限，在达到 80% 和 100% 时自动告警（非侵入式，只提醒不阻止 Agent 运行）。

3. Session 轨迹追踪

瀑布视图展示每次 prompt、推理链、工具调用和响应的完整链路。

4. 预算与配额管理

读取各 Agent 的计划配额信息（周度/月度窗口），侧边栏实时显示各配额的消耗进度。

5. Hermes Agent 深度集成

专属 /hermes 路由展示 38 个平台的 Agent 活动、gateway 健康状态、cron 调度状态、skills 和 memory 使用情况，以及 cost anomaly 检测。

部署方式

方式一：一键安装脚本（推荐）

macOS / Linux：

curl -fsSL https://tokentelemetry.com/install.sh | bash

Windows：

irm https://tokentelemetry.com/install.ps1 | iex

方式二：Docker Compose（适合服务器部署）

项目根目录包含 docker-compose.prod.yml，一行命令启动完整服务：

docker-compose -f docker-compose.prod.yml up -d

前后端均有独立 Dockerfile，backend 基于 Python 3.9+，frontend 基于 Node.js 18+。

方式三：Hermes Agent 插件模式

如果你是 Hermes Agent 用户，可以直接将 TokenTelemetry 安装为 Hermes 的插件，在 Hermes Dashboard 中以 Tab 形式访问：

hermes plugins install VasiHemanth/tokentelemetry-hermes-plugin

技术栈

层级	技术
后端框架	FastAPI (Python)
前端框架	Next.js + TypeScript
数据库	SQLite（本地存储）
数据采集	直接读取 Agent 日志文件
部署方式	Docker / 脚本安装
费用计算	pricing_data.json（实时同步官方定价）
测试	pytest（91 个测试文件，覆盖关键模块）

局限与注意事项

• 数据依赖本地日志：如果 Agent 没有写入日志或日志路径被修改，TokenTelemetry 无法采集数据
• 仅支持已实现 harness 的 Agent：新上线的 Agent 需要等待社区贡献 harness
• Hermes Agent 深度功能需要同机部署：读取 $HERMES_HOME 本地路径，暂不支持远程数据库模式
• 云端部署需注意：如果你把 TokenTelemetry 部署在服务器上而 Agent 运行在本地机器，数据采集会失效

行业意义

随着 Claude Code、Codex 等 AI 编程 Agent 快速普及，token 消费的可视化和成本控制正在成为开发团队的刚需。TokenTelemetry 的出现填补了这一空白——它是目前支持 Agent 种类最多的本地可观测性工具，且完全免费开源。

对于同时使用多个 Agent 的开发者来说，TokenTelemetry 提供了一种无摩擦的方式来理解每个 Agent 的真实成本，从而做出更明智的选型决策。