构建本地AI Token用量监控面板：零依赖实现成本可视化

1. 项目概述一个轻量级的本地AI Token用量监控面板最近在深度使用Cursor、Claude等AI编程工具时我遇到了一个很实际的问题虽然这些工具极大地提升了开发效率但它们的API调用成本却像是一个“黑盒”。你只知道自己在不停地用但具体用了多少Token每个模型花了多少钱每天的消耗趋势如何心里完全没底。尤其是当你在一个复杂的项目上让AI助手比如我常用的OpenClaw进行多轮、长时间的会话时这种不确定性带来的焦虑感会越来越强。于是我动手写了一个极简的本地监控面板就叫它Token Usage UI。它的核心目标非常明确把你本地的AI会话数据实时、直观地转换成成本图表和用量分析。它不依赖任何外部服务不需要数据库甚至不需要安装额外的Python包就是一个纯静态的HTML页面加上一个用Python标准库写的微型HTTP服务器。你把它放在本地启动服务打开浏览器就能看到一个清晰的Dashboard上面展示着总花费、每个模型的Token消耗明细以及过去7天的用量趋势图。这个工具特别适合像我这样习惯在本地运行AI Agent例如OpenClaw并且希望对自己的使用情况有精细掌控的开发者。它帮你从“凭感觉用”过渡到“用数据驱动决策”比如“今天Claude-3.5-Sonnet的用量是不是有点超标了”或者“我这个项目的AI辅助成本主要花在哪个模型上了”。接下来我会详细拆解这个工具的设计思路、实现细节并分享我在搭建和使用过程中踩过的坑和总结的经验。2. 核心设计思路与架构解析2.1 为什么选择“纯本地零依赖”的方案在设计之初我考虑过几种方案。比如直接使用云监控服务如Grafana Cloud, Datadog或者用更重的Web框架如Flask, FastAPI来构建后端。但最终都被我否决了原因如下数据隐私与安全性AI会话数据可能包含代码片段、问题描述甚至部分业务逻辑属于敏感信息。将这些数据发送到第三方云服务存在潜在风险。本地处理能确保数据不出你的机器这是最重要的底线。极致的轻量与便捷这个工具的核心价值是“快速洞察”而不是一个功能庞杂的管理系统。使用Python标准库的http.server意味着在任何安装了Python的环境macOS, Linux, 甚至WSL下的Windows都能直接运行无需处理复杂的依赖冲突或环境配置。用户只需要git clone或下载代码然后一条命令就能启动。成本与维护负担零外部依赖等于零维护成本。我不需要担心某个第三方库版本更新导致接口不兼容也不需要用户额外安装任何东西。整个项目就两个核心文件server.py和一个index.html结构清晰任何人拿到手都能在5分钟内理解并运行起来。注意这里说的“零依赖”是指运行时不依赖第三方Python包。前端图表库Chart.js和字体Inter是通过CDN引入的这是前端的常规做法不影响本地的部署复杂度。2.2 数据流设计从原始日志到可视化图表整个工具的数据流非常简洁是一个典型的“读取 - 转换 - 呈现”管道~/.openclaw/agents/main/sessions/sessions.json ↓ (读取) Python Server (server.py) ↓ (解析、聚合、计算) 生成包含聚合数据的JSON API响应 (/api/data) ↓ (请求) 浏览器端 (index.html) ↓ (渲染) Dashboard 图表 (Chart.js) 数据面板关键设计点解析数据源定位工具硬编码了OpenClaw默认的会话日志路径~/.openclaw/agents/main/sessions/sessions.json。这是一个有意的设计选择因为它针对的是OpenClaw用户这一特定场景。如果你用的其他AI Agent框架只需要修改这个路径即可。Mock数据回退机制这是提升用户体验的一个细节。如果目标路径没有找到真实的会话文件服务器不会报错崩溃而是会生成一套结构合理的模拟数据。这保证了工具在任何情况下都是“可用的”方便新用户第一时间看到界面效果也便于开发调试。计算逻辑成本计算是核心。server.py中需要内置一份模型定价表例如claude-3-5-sonnet-20241022: {input: 3.0, output: 15.0}单位是美元/百万Token。程序会遍历每条会话记录根据其使用的模型和输入/输出Token数累加计算出总成本和每个模型的细分成本。这个计算过程是实时的每次API请求都会重新计算确保看到的是最新数据。2.3 前端技术选型在简单与美观间平衡前端部分的目标是用最小的开销实现一个信息清晰、视觉舒适的监控面板。Chart.js这是图表库的不二之选。它轻量通过CDN引入一个脚本文件即可、功能强大支持线图、柱图、饼图等、配置灵活。我们的7天时间线图用它来实现非常合适。相比于D3.js这样的底层库Chart.js的抽象程度更高几行配置就能出一个漂亮的图表更适合这种工具类项目。Inter字体这是一个细节但很重要。Inter是一款现代、开源、在屏幕上可读性极高的无衬线字体。通过Google Fonts CDN引入能让Dashboard的数字和文字显示更加清晰、专业。虽然系统默认字体也能用但这一点点提升能显著改善整体的观感。纯CSS与响应式布局我没有使用任何CSS框架如Bootstrap。所有样式都手写在HTML的style标签里。这样做虽然前期多写几行代码但最终产出的HTML文件是完全自包含的没有任何外部CSS依赖。响应式设计通过CSS媒体查询media实现确保在从桌面大屏到笔记本小屏上图表和数据都能合理排布不会出现错位或重叠。这种技术栈选择使得整个index.html文件可以保持在一个相对较小的体积通常几十KB加载瞬间完成体验非常流畅。3. 核心模块实现与实操要点3.1 后端服务器 (server.py) 深度拆解server.py是这个项目的大脑它主要做三件事提供静态文件HTML/CSS/JS、提供数据API、处理模拟数据。我们一段段来看关键代码和其中的门道。#!/usr/bin/env python3 import http.server import socketserver import json import os from datetime import datetime, timedelta from pathlib import Path import threading # 1. 关键配置 PORT 8765 SESSIONS_FILE_PATH Path.home() / .openclaw / agents / main / sessions / sessions.json API_REFRESH_INTERVAL 8 # 前端自动刷新间隔单位秒 # 2. 模型定价表核心需要你根据实际使用的模型更新 MODEL_PRICES { # 格式: model-id: {input: 每百万Token输入价格(美元), output: 每百万Token输出价格(美元)} claude-3-5-sonnet-20241022: {input: 3.0, output: 15.0}, claude-3-opus-20240229: {input: 15.0, output: 75.0}, claude-3-sonnet-20240229: {input: 3.0, output: 15.0}, claude-3-haiku-20240307: {input: 0.25, output: 1.25}, gpt-4o: {input: 5.0, output: 15.0}, gpt-4o-mini: {input: 0.15, output: 0.60}, # 你可以在这里添加更多模型 }实操要点一模型定价表的维护这是整个成本计算准确性的基石。MODEL_PRICES字典必须与你实际使用的模型ID严格对应。OpenClaw或Cursor在会话日志中记录的模型ID你需要去对应AI服务商Anthropic, OpenAI的官方定价页面核对。价格单位是每百万Token的美元价格。请注意模型定价可能会随时更新特别是当新模型版本发布时。一个建议的做法是将这个定价表单独提取到一个config.py文件中方便后期维护。接下来是请求处理类class TokenUsageHandler(http.server.SimpleHTTPRequestHandler): def do_GET(self): # 路由处理 if self.path /: self.path /index.html return super().do_GET() elif self.path /api/data: self.serve_api_data() else: # 处理其他静态文件请求如favicon.ico super().do_GET() def serve_api_data(self): 核心API读取、分析会话数据返回JSON try: sessions_data self.load_sessions_data() processed_data self.process_sessions(sessions_data) self.send_response(200) self.send_header(Content-Type, application/json) self.send_header(Access-Control-Allow-Origin, *) # 简单CORS处理 self.end_headers() self.wfile.write(json.dumps(processed_data).encode(utf-8)) except Exception as e: # 错误处理返回一个包含错误信息的空数据结构避免前端崩溃 error_data { total_cost: 0, models: [], timeline: [], error: str(e) } self.send_error(500, json.dumps(error_data))实操要点二健壮的错误处理注意serve_api_data方法中的try...except块。在读取本地文件、解析JSON、计算数据时任何一步都可能出错文件不存在、格式错误、价格表缺失对应模型。我们的原则是服务器绝不能因为单次API请求失败而崩溃。捕获异常后我们返回一个携带错误信息的基本数据结构这样前端页面至少能加载出来并显示一个错误提示用户体验远比看到一个空白页或连接错误要好。数据加载与模拟逻辑def load_sessions_data(self): 加载会话数据如果文件不存在则生成模拟数据 if SESSIONS_FILE_PATH.exists(): with open(SESSIONS_FILE_PATH, r, encodingutf-8) as f: return json.load(f) else: # 生成过去7天的模拟数据 print(fWarning: Real sessions file not found at {SESSIONS_FILE_PATH}. Using mock data.) return self.generate_mock_sessions() def generate_mock_sessions(self): 生成结构合理的模拟会话数据用于演示和开发 mock_sessions [] base_time datetime.now() models list(MODEL_PRICES.keys()) for i in range(100): # 生成100条模拟会话 session_date base_time - timedelta(daysi % 7, hoursi % 24) model models[i % len(models)] # 模拟合理的输入输出Token范围 input_tokens 500 (i * 23) % 4500 output_tokens 100 (i * 17) % 2500 mock_sessions.append({ timestamp: session_date.isoformat(), model: model, input_tokens: input_tokens, output_tokens: output_tokens, session_id: fmock_session_{i} }) return mock_sessions实操要点三模拟数据的真实性generate_mock_sessions函数不是随便生成随机数。我刻意让数据模拟了真实场景的某些特征时间分布数据分布在过去7天内而不是全部挤在一天这样时间线图表才有看头。模型轮换按顺序循环使用定价表中的模型确保每个模型都有数据。Token量范围输入Token500-5000通常大于输出Token100-2600这符合大多数AI对话尤其是代码生成的模式用户的问题描述输入较长AI的回复输出相对精炼。 这样的模拟数据能让第一次使用的用户立即看到一个有参考价值的、接近真实的Dashboard而不是一个比例失调的“玩具示例”。3.2 数据处理与聚合逻辑这是后端最核心的计算部分在process_sessions方法中实现。def process_sessions(self, sessions_data): 处理原始会话数据聚合出前端需要的格式 # 初始化数据结构 model_breakdown {} timeline_data {} total_cost 0.0 # 假设sessions_data是一个会话对象列表 for session in sessions_data: model session.get(model) if not model or model not in MODEL_PRICES: continue # 跳过无法识别或未定价的模型 input_tokens session.get(input_tokens, 0) output_tokens session.get(output_tokens, 0) timestamp_str session.get(timestamp) if not timestamp_str: continue # 1. 按模型聚合 if model not in model_breakdown: model_breakdown[model] { input_tokens: 0, output_tokens: 0, session_count: 0, cost: 0.0 } mb model_breakdown[model] mb[input_tokens] input_tokens mb[output_tokens] output_tokens mb[session_count] 1 # 计算本次会话成本并累加 input_cost (input_tokens / 1_000_000) * MODEL_PRICES[model][input] output_cost (output_tokens / 1_000_000) * MODEL_PRICES[model][output] session_cost input_cost output_cost mb[cost] session_cost total_cost session_cost # 2. 按天聚合用于时间线 try: dt datetime.fromisoformat(timestamp_str.replace(Z, 00:00)) day_key dt.strftime(%Y-%m-%d) # 例如 2024-01-15 except ValueError: continue if day_key not in timeline_data: timeline_data[day_key] 0 timeline_data[day_key] (input_tokens output_tokens) # 将模型数据转换为前端需要的列表格式并按成本排序 models_list [] for model_id, data in model_breakdown.items(): models_list.append({ model: model_id, input_tokens: data[input_tokens], output_tokens: data[output_tokens], session_count: data[session_count], cost: round(data[cost], 4) # 保留4位小数 }) models_list.sort(keylambda x: x[cost], reverseTrue) # 处理时间线数据取最近7天填充可能缺失的日期 end_date datetime.now().date() start_date end_date - timedelta(days6) timeline_list [] current_date start_date while current_date end_date: date_key current_date.strftime(%Y-%m-%d) timeline_list.append({ date: date_key, tokens: timeline_data.get(date_key, 0) }) current_date timedelta(days1) return { total_cost: round(total_cost, 4), models: models_list, timeline: timeline_list, last_updated: datetime.now().isoformat() }计算过程详解单次会话成本计算这是最基本的公式。会话成本 (输入Token数 / 1,000,000) * 输入单价 (输出Token数 / 1,000,000) * 输出单价。这里除以100万是因为定价单位是“每百万Token”。计算时使用浮点数最后呈现时再四舍五入。模型聚合遍历所有会话用一个字典model_breakdown按模型ID累加各自的输入/输出Token总数、会话次数和总成本。这样我们就能知道哪个模型“最烧钱”。时间线聚合同样遍历会话将每条会话的Token总数输入输出累加到其发生日期对应的键值上。这里的关键是日期格式化和缺失日期填充。我们使用strftime(%Y-%m-%d)来获得统一的日期字符串作为键。最后为了确保图表连续我们生成从今天往前推6天共7天的日期列表如果某天没有数据则Token数记为0。排序与格式化模型列表按成本降序排列让用户一眼看到开销大头。所有成本数字都经过round处理避免出现一长串无意义的小数位。3.3 前端界面 (index.html) 构建细节前端页面是一个单文件HTML包含了所有样式和脚本。布局采用经典的Dashboard卡片式设计。HTML结构骨架!DOCTYPE html html head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleAI Token Usage Dashboard/title !-- 引入Chart.js和Inter字体 -- script srchttps://cdn.jsdelivr.net/npm/chart.js/script link hrefhttps://fonts.googleapis.com/css2?familyInter:wght300;400;500;600;700displayswap relstylesheet style /* 所有CSS样式都写在这里 */ :root { --bg-color: #0f172a; --card-bg: #1e293b; ... } body { font-family: Inter, sans-serif; background: var(--bg-color); color: #e2e8f0; ... } .dashboard { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; } .card { background: var(--card-bg); border-radius: 0.75rem; padding: 1.5rem; } /* ... 更多样式 */ /style /head body headerh1 AI Token Usage Dashboard/h1pMonitoring local OpenClaw/Cursor sessions/p/header main section classdashboard div classcard summary-card.../div div classcard chart-card.../div div classcard table-card.../div /section /main script // 所有JavaScript逻辑都写在这里 const API_URL /api/data; const REFRESH_INTERVAL 8000; // 8秒 let timelineChart; async function fetchData() { ... } function updateSummary(data) { ... } function updateChart(data) { ... } function updateTable(data) { ... } // 初始化 fetchData(); setInterval(fetchData, REFRESH_INTERVAL); /script /body /html关键实现技巧CSS Grid布局.dashboard使用grid-template-columns: repeat(auto-fit, minmax(300px, 1fr))这一行代码就实现了完美的响应式布局。在宽屏上卡片会并排显示如三列当屏幕宽度小于某个阈值时会自动折行始终保持卡片有至少300px的最小宽度阅读体验很好。CSS自定义属性变量在:root中定义颜色变量如--bg-color,--card-bg使得整个应用的暗色主题保持一致并且未来如果想切换成亮色主题只需要修改这几个变量值即可维护性极高。Chart.js图表配置这是前端最复杂的部分。创建时间线图表时需要精心配置选项以符合监控面板的调性。function renderChart(timelineData) { const ctx document.getElementById(timelineChart).getContext(2d); if (timelineChart) timelineChart.destroy(); // 销毁旧图表实例 const dates timelineData.map(d d.date); const tokens timelineData.map(d d.tokens); timelineChart new Chart(ctx, { type: line, data: { labels: dates, datasets: [{ label: Total Tokens, data: tokens, borderColor: #60a5fa, // 蓝色线条 backgroundColor: rgba(96, 165, 250, 0.1), // 浅蓝色填充 borderWidth: 2, fill: true, tension: 0.4 // 让线条稍微平滑不是完全的折线 }] }, options: { responsive: true, maintainAspectRatio: false, plugins: { legend: { display: false } }, scales: { x: { grid: { color: rgba(255,255,255,0.1) } }, y: { beginAtZero: true, grid: { color: rgba(255,255,255,0.1) }, ticks: { callback: function(value) { if (value 1000000) return (value / 1000000).toFixed(1) M; if (value 1000) return (value / 1000).toFixed(0) K; return value; } } } } } }); }配置亮点tension: 0.4让折线图变得平滑视觉上更柔和。beginAtZero: trueY轴从0开始能更准确地反映数据比例。ticks.callback这是一个非常实用的技巧。Y轴标签的格式化函数当Token数很大时自动转换为“K”千或“M”百万单位显示让图表更简洁易读。例如1,500,000会显示为1.5M。自动刷新与数据更新通过setInterval(fetchData, REFRESH_INTERVAL)设置一个8秒一次的定时器不断从/api/data拉取最新数据然后调用updateSummary,updateChart,updateTable来更新DOM。这里要注意更新图表时必须先调用timelineChart.destroy()销毁旧的Chart实例再创建新的否则会导致内存泄漏和图表错乱。4. 部署、使用与自定义指南4.1 一键部署与运行使用这个工具极其简单几乎没有任何前置条件。获取代码你可以直接从GitHub仓库克隆或者下载ZIP包解压。git clone https://github.com/Walliiee/token-usage-ui.git cd token-usage-ui或者如果你只是想在OpenClaw的工作空间里快速使用项目本身也建议了路径~/.openclaw/workspace/projects/token-usage-ui你可以直接把文件放到那里。启动服务确保你的终端位于项目目录下然后运行python server.py如果系统中有多个Python版本可能需要使用python3。访问面板服务器启动后你会看到类似Serving HTTP on 0.0.0.0 port 8765 (http://0.0.0.0:8765/) ...的输出。此时打开你的浏览器访问http://localhost:8765即可。注意默认端口是8765。如果该端口被占用你需要修改server.py开头的PORT变量并确保防火墙允许该端口的本地访问。4.2 适配其他AI Agent或日志格式这个工具默认是为OpenClaw设计的。如果你使用的是其他本地AI Agent比如自定义的脚本、或其他框架只需要修改两个地方修改数据源路径在server.py中找到SESSIONS_FILE_PATH变量将其值改为你的AI Agent存储会话日志的JSON文件路径。适配数据格式检查你的日志JSON结构。server.py的process_sessions函数期望从每条会话记录中读取model、input_tokens、output_tokens、timestamp这几个字段。如果你的日志格式不同你需要调整process_sessions函数中访问这些数据的键名。例如如果你的日志中模型字段叫model_nameToken字段叫prompt_tokens和completion_tokens那么你需要将代码中的session.get(model)改为session.get(model_name)以此类推。4.3 自定义与扩展思路这个基础版本已经非常实用但你完全可以基于它进行扩展打造更符合个人需求的监控面板。增加更多图表成本饼图用Chart.js的doughnut或pie类型直观展示每个模型成本占总成本的比例。模型对比柱状图横向柱状图对比不同模型的平均每次会话Token消耗或成本。实现方法在前端fetchData成功后除了现有的更新函数再调用新的图表渲染函数并在HTML中增加对应的canvas画布容器。数据持久化与历史趋势当前工具只分析现有的会话文件重启后历史数据仍在但缺乏更长期如月度、年度的聚合视图。思路可以修改server.py让它每次启动时将当前聚合结果总成本、各模型用量追加写入一个本地的CSV或SQLite数据库文件。然后新增一个历史报表页面从这些持久化数据中生成月度报告。设置成本预算告警思路在server.py中设定一个每日或每周的成本预算阈值。在process_sessions函数中计算当天或当周的成本如果超过阈值可以在返回的JSON数据中添加一个alert字段。前端检测到这个字段后在页面上用醒目的颜色显示警告信息甚至播放提示音。美化与主题切换目前是深色主题。你可以在CSS中定义另一套浅色主题的变量并通过一个按钮在前端切换:root上的CSS类来实现主题切换。使用更精美的图标库如Font Awesome或Heroicons替换简单的文字标题。5. 常见问题与故障排查实录在实际使用和分享给朋友的过程中我遇到并总结了一些典型问题。这里列出来方便你快速排查。5.1 启动服务时遇到的问题问题1python server.py命令报错ModuleNotFoundError或SyntaxError。原因Python版本不兼容。项目使用了datetime.fromisoformat()等较新的方法需要Python 3.7。解决确认你的Python版本python --version或python3 --version。如果版本低于3.7请升级Python。在macOS/Linux上可以尝试使用python3 server.py命令。问题2服务启动成功但浏览器访问http://localhost:8765显示“无法连接”或“拒绝访问”。原因A端口冲突。8765端口可能被其他程序占用。解决A修改server.py中的PORT变量换一个不常用的端口如8766,8080重启服务并用新端口访问如http://localhost:8080。原因B防火墙或安全软件阻止。解决B确保你的防火墙允许本地回环地址localhost上的该端口通信。对于个人开发这通常不是问题。问题3页面能打开但图表和数据区域一直显示“Loading...”或空白。原因前端JavaScript无法从/api/data获取数据。打开浏览器的开发者工具F12查看“网络”(Network)标签页找到对/api/data的请求。状态码404后端路由没配置对。检查server.py中TokenUsageHandler.do_GET方法确保有elif self.path /api/data:这个分支并且调用了self.serve_api_data()。状态码500后端处理数据时出错。查看开发者工具的“控制台”(Console)标签页或后端终端输出通常会有详细的Python错误堆栈信息。常见原因sessions.json文件格式不是有效的JSON或者文件中某些记录的字段缺失导致计算错误。5.2 数据展示相关的问题问题4总成本显示为0或者某个模型的成本为0。原因A模型定价表MODEL_PRICES中缺少你正在使用的模型ID。解决A检查你的sessions.json文件找到实际使用的模型ID例如claude-3-5-sonnet-20250227然后将其和正确的定价添加到MODEL_PRICES字典中。务必去Anthropic或OpenAI官网核对最新价格。原因B会话日志中的input_tokens或output_tokens字段值为0或不存在。解决B检查原始数据格式。有些AI工具可能将Token数放在嵌套字段里或者字段名不同。你需要根据实际情况调整process_sessions函数中获取Token数的代码。问题5时间线图表只显示最近一两天有数据其他天是0。原因你的会话日志中可能只包含最近一两天的数据。OpenClaw等工具可能会定期清理或滚动更新日志文件。解决这是正常现象说明你的历史数据不多。工具会填充最近7天的日期没有数据的天数自然显示为0。如果你想分析更久远的数据需要确保你的会话日志文件包含了那个时间段的数据。问题6使用了模拟数据但觉得数据看起来“不真实”或太规律。原因generate_mock_sessions函数生成的模拟数据是基于简单算法的目的是演示难免有规律可循。解决如果你想获得更逼真的模拟数据用于测试可以修改这个函数引入random库让Token数量、模型选择、日期分布更加随机化。或者更好的方法是用你一小段真实的历史日志数据作为基础来生成模拟数据。5.3 性能与使用技巧技巧1自动刷新间隔调整默认8秒刷新一次对于实时监控可能有点频繁。如果你只是偶尔查看或者觉得浏览器CPU/网络占用稍高可以在前端JavaScript中修改const REFRESH_INTERVAL 8000;这个值比如改为3000030秒或600001分钟。技巧2处理超大会话日志文件如果你的sessions.json文件非常大比如超过100MB每次API请求都读取、解析、计算整个文件可能会导致服务器响应变慢前端加载卡顿。优化思路可以修改load_sessions_data和process_sessions函数只读取和分析最近一段时间比如最近30天的数据。这可以通过在读取JSON后根据timestamp字段过滤会话记录来实现。技巧3长期运行与开机自启如果你希望这个监控面板一直开着可以将其设置为后台服务。Linux/macOS可以使用nohup python server.py 命令在后台运行。或者更专业一点创建一个systemd服务单元文件。Windows可以将其包装成一个批处理文件并使用计划任务或第三方工具将其设置为开机启动。这个工具的本质是一个帮你“看见”AI使用成本的窗口。它没有复杂的安装过程没有依赖地狱所有代码一目了然。你可以把它当作一个即插即用的辅助工具也可以把它当作一个学习Web开发和数据可视化的小项目模板根据自己的需求任意修改和扩展。最重要的是它让你在享受AI带来的生产力提升时对自己的开销有了清晰的掌控感这种掌控感本身就是高效和可持续使用新技术的基础。