1. 项目概述一个轻量级的AI助手成本监控仪表盘最近在折腾各种AI助手工具像Cursor、Claude这些用起来是真爽但月底一看账单心里就有点发毛。特别是当你开了多个项目让AI助手帮你写代码、分析文档、甚至调试的时候那个Token消耗量是蹭蹭往上涨。你只知道总费用可能不低但具体是哪个模型花的钱最多每天的用量趋势如何哪个会话最“烧钱”这些细节在AI助手的官方界面里往往很难一目了然。为了解决这个痛点我动手写了一个叫Token Usage UI的本地仪表盘。它的核心目标很简单把你本地AI助手比如基于OpenClaw框架的工具产生的所有会话数据变成一个清晰、实时、可视化的成本监控面板。你不用再去翻看晦涩的日志文件也不用等月底的账单打开浏览器本地地址一输所有开销和用量尽在掌握。这个工具特别适合像我这样的独立开发者、小团队负责人或者任何深度依赖AI编程助手但又需要对成本保持敏感的用户。它能帮你回答几个关键问题我这个月或这周在AI上花了多少钱Claude-3.5-Sonnet和GPT-4o哪个更“费”最近几天的使用量是平稳还是激增有了这些数据你就能更理性地调整使用策略比如把一些非核心的代码补全任务交给更便宜的模型或者发现某个异常消耗的会话并及时优化。整个项目采用极简主义设计零外部Python依赖一个文件就能跑起来数据源就是你本地已经存在的会话日志。下面我就来详细拆解这个工具的设计思路、实现细节以及我在开发过程中踩过的坑和总结的经验。2. 核心设计思路与架构解析2.1 为什么选择本地化、轻量级的方案市面上不是没有云端监控服务但针对个人或小团队的AI助手使用监控它们要么功能过剩、配置复杂要么涉及数据隐私和额外的订阅费用。我的核心需求很明确数据安全与隐私所有会话记录、提示词、生成的代码都可能包含敏感信息。这些数据绝不能离开我的本地环境。零成本与即时性工具本身不应该产生任何费用并且监控应该是实时的延迟越低越好。极简部署最好不需要安装任何额外的包管理器如pip、npm开箱即用降低使用门槛。定制化我需要的数据视图可能很特殊比如结合OpenClaw的特定会话格式通用工具往往无法满足。因此一个读取本地日志文件、用Python标准库提供Web服务、前端用CDN引入基础库的方案就成了最自然的选择。它完美契合了“简单、直接、有效”的原则。2.2 整体架构与数据流整个系统的架构可以用一句话概括一个静态前端页面由一个极简的Python HTTP服务器动态提供数据。具体的数据流如下数据采集层已存在AI助手如Cursor/Claude在运行时会通过OpenClaw等框架将每次会话的详细信息模型名称、输入/输出token数、时间戳等以JSON格式写入本地文件通常是~/.openclaw/agents/main/sessions/sessions.json。这一步是工具运行的前提本工具不负责采集只负责消费。数据服务层Python Server我编写的server.py扮演了一个双重角色。静态文件服务器当浏览器请求HTML、CSS、JS文件时它直接读取并返回这些文件。动态API端点当浏览器前端通过JavaScript请求数据如/api/usage时server.py会实时去读取上述的sessions.json文件进行聚合计算如按模型分组、按日期汇总然后将处理好的JSON数据返回给前端。数据展示层前端HTMLJS一个单一的index.html文件包含了所有的展示逻辑。它通过Chart.js库绘制趋势图用原生JavaScript操作DOM来更新数字面板。页面通过定时器每8秒自动调用后端的API实现数据的近乎实时刷新。这种架构的优势在于解耦清晰后端只负责提供干净的数据前端只负责漂亮的展示。未来如果想增加新的图表类型或数据维度只需要修改前端页面和对应的API数据处理逻辑即可相互影响最小。2.3 技术选型背后的考量Python标准库http.server这是最关键的选择。它意味着不需要安装Flask、FastAPI等任何Web框架。虽然功能基础比如没有路由库需要手动解析URL但对于一个只有一两个API端点的工具来说完全够用并且实现了真正的“零依赖”。任何安装了Python的环境都能直接运行。Chart.js (via CDN)在前端绘制图表Chart.js是轻量且强大的选择。通过CDN引入避免了在前端项目里管理npm包的麻烦。它的配置化API足够灵活能轻松画出我们需要的折线图、柱状图等。Inter字体 (via Google Fonts CDN)仪表盘的可读性和美观性很重要。Inter是一款非常优秀的无衬线字体在数字和字母的显示上清晰易读。通过Google Fonts CDN引入同样避免了本地字体文件的管理。纯手写CSS (Dark Theme)没有使用Bootstrap、Tailwind等CSS框架。一方面是为了保持极简另一方面也是为了更好地控制深色主题的每一个细节。手写的CSS文件体积极小加载飞快。注意使用CDN会带来一定的网络依赖。但在实际使用中这些CDN的可用性极高且本工具是本地使用即使短暂无法连接CDN核心功能数据展示依然可用只是图表和字体可能回退到默认样式属于可接受的降级。3. 核心功能模块深度拆解3.1 数据读取与聚合引擎这是后端server.py最核心的部分。它的任务是把原始的、杂乱的会话日志变成前端可以直接消费的、结构化的统计数据。原始数据结构分析 通常sessions.json是一个JSON数组每个元素代表一次AI调用。关键字段可能包括{ session_id: abc123, model: claude-3-5-sonnet-20241022, input_tokens: 1500, output_tokens: 800, timestamp: 2024-04-10T14:30:00Z, cost_usd: 0.015 // 有时会直接提供有时需要根据token数和模型单价计算 }后端处理逻辑文件读取与容错首先尝试读取真实数据文件。如果文件不存在、格式错误或为空则切换到“模拟数据模式”。这个回退机制至关重要它保证了工具在开发阶段或数据文件意外丢失时依然可以运行和演示。# 伪代码逻辑 def load_sessions(): data_path os.path.expanduser(~/.openclaw/agents/main/sessions/sessions.json) try: with open(data_path, r) as f: sessions json.load(f) if not sessions: # 文件存在但为空 raise ValueError(No session data) return sessions except (FileNotFoundError, json.JSONDecodeError, ValueError): # 返回预先准备好的模拟数据 return generate_mock_sessions(days7)数据聚合遍历所有会话记录进行多重聚合计算。按模型聚合创建一个字典以model为键累加该模型的input_tokens,output_tokens,session_count并根据模型单价计算总成本。模型单价需要维护一个内部的映射字典例如{“claude-3-5-sonnet”: 0.003, “gpt-4o”: 0.005, …}。按日期聚合为了绘制7天趋势图需要将timestamp字段转换为日期然后统计每天所有会话的token总量输入输出。这里要注意时区处理通常将UTC时间转换为本地日期。API响应构造将聚合好的数据组装成一个大的JSON对象。{ total_cost: 12.34, models: [ {name: claude-3-5-sonnet, input_tokens: 50000, output_tokens: 30000, cost: 8.5, session_count: 45}, ... ], timeline: [ {date: 2024-04-04, total_tokens: 12000}, {date: 2024-04-05, total_tokens: 15000}, ... ] }3.2 前端可视化面板的实现前端index.html是一个独立的单页应用其核心是动态更新DOM和操作Chart.js图表。页面布局与样式 采用经典的仪表盘布局。顶部是醒目的总成本显示用大字体和强调色突出。下方是并排的卡片式布局左侧是按模型分解的详细列表右侧是7天Token用量趋势图。深色主题背景色#0f172a卡片背景#1e293b能减少长时间观看的视觉疲劳并且高对比度让数据更突出。数据绑定与更新定时获取使用setInterval函数每8000毫秒8秒调用一次fetchData()函数。异步请求fetchData()函数使用fetch(‘/api/usage’)向后端发起请求。这里处理了网络错误和HTTP错误避免前端因一次请求失败而崩溃。async function fetchData() { try { const response await fetch(/api/usage); if (!response.ok) throw new Error(HTTP error! status: ${response.status}); const data await response.json(); updateDashboard(data); } catch (error) { console.error(Failed to fetch usage data:, error); // 可以选择在UI上显示一个温和的错误提示而不是静默失败 document.getElementById(error-message).textContent 数据更新失败稍后重试...; } }DOM更新updateDashboard(data)函数收到新的JSON数据后会将data.total_cost格式化如$12.34后更新到总成本元素。清空模型列表的容器然后根据data.models数组动态创建新的列表项tr或div填入模型名、token数、成本和会话次数。调用Chart.js实例的update()方法将新的data.timeline数据设置到图表的数据集dataset中图表就会平滑地过渡到新的状态。Chart.js图表配置 趋势图通常配置为折线图Line Chart。X轴是日期Y轴是Token数量。一些提升体验的细节配置tension: 0.4让折线有一定的平滑曲线看起来更柔和。fill: true配合渐变色填充在折线下方形成区域填充视觉上更直观地感受量的变化。pointRadius: 3数据点显示为小圆点方便鼠标悬停查看精确值。响应式配置responsive: true和maintainAspectRatio: false让图表能适应不同大小的卡片区域。3.3 成本计算模型与单价配置成本计算是本工具准确性的基石。不同的AI模型其输入Input和输出Output的单价每百万Token的价格是不同的而且提供商可能会调整价格。单价映射表 在server.py中需要维护一个最新的模型单价字典。这个字典是成本计算的核心依据。MODEL_PRICING { # 示例价格单位美元 / 每百万Tokens (USD per million tokens) # 输入Token单价 claude-3-5-sonnet-20241022: {input: 3.00, output: 15.00}, gpt-4o: {input: 5.00, output: 15.00}, gpt-4o-mini: {input: 0.15, output: 0.60}, claude-3-haiku: {input: 0.25, output: 1.25}, # ... 其他模型 }计算逻辑 对于每一个会话其成本计算如下def calculate_session_cost(session): model_name session[model] pricing MODEL_PRICING.get(model_name) if not pricing: return 0.0 # 未知模型成本记为0但最好在日志中记录警告 input_cost (session[input_tokens] / 1_000_000) * pricing[input] output_cost (session[output_tokens] / 1_000_000) * pricing[output] return input_cost output_cost然后将所有会话的成本累加得到总成本。按模型聚合时也是累加该模型下所有会话的成本。重要提示模型单价是变动的你需要定期例如每月去OpenAI、Anthropic等官方页面核对最新价格并更新MODEL_PRICING字典。这是保证仪表盘数据准确性的最重要一步。我建议将这个字典单独放在一个配置文件如pricing_config.py中方便维护。4. 从零到一的部署与实操指南4.1 环境准备与项目获取首先确保你的系统已经安装了Python 3.6或更高版本。这个工具不依赖任何第三方Python包所以不需要创建虚拟环境或运行pip install这是它最大的便利之一。获取项目代码 假设你的AI助手如基于OpenClaw的工作区在~/.openclaw/workspace你可以直接将token-usage-ui项目克隆或放置到其projects目录下。# 进入你的工作区目录 cd ~/.openclaw/workspace/projects # 假设你已经通过git克隆或直接下载了项目 # 此时目录结构应类似 # ~/.openclaw/workspace/projects/token-usage-ui/ # ├── server.py # ├── index.html # ├── style.css # └── (可能还有其他文件如 README.md)如果还没有代码你可以创建一个简单的项目结构。核心文件只有三个server.py,index.html,style.css。4.2 核心文件详解与配置1.server.py– Python HTTP服务器这是整个应用的大脑。你需要根据你的实际会话数据路径来修改文件读取的位置。关键部分如下#!/usr/bin/env python3 import http.server import socketserver import json import os from datetime import datetime, timedelta from urllib.parse import urlparse, parse_qs # 关键配置你的会话数据文件路径 SESSIONS_FILE_PATH os.path.expanduser(‘~/.openclaw/agents/main/sessions/sessions.json’) # 模型单价配置必须定期更新 MODEL_PRICING { ... } # 如前文所述 class MyRequestHandler(http.server.SimpleHTTPRequestHandler): def do_GET(self): # 解析请求路径 parsed_path urlparse(self.path) # 如果请求的是API端点 if parsed_path.path ‘/api/usage’: self.send_response(200) self.send_header(‘Content-type’, ‘application/json’) self.send_header(‘Access-Control-Allow-Origin’, ‘*’) # 简单处理CORS self.end_headers() # 调用函数获取处理后的数据 usage_data get_usage_data() self.wfile.write(json.dumps(usage_data).encode(‘utf-8’)) else: # 否则交给父类处理静态文件index.html, style.css等 super().do_GET() def get_usage_data(): # 1. 加载会话数据真实或模拟 sessions load_sessions() # 2. 进行聚合计算... # 3. 返回结构化的数据字典 return aggregated_data # ... 其他辅助函数load_sessions, calculate_cost, aggregate_by_model等... if __name__ ‘__main__’: PORT 8765 with socketserver.TCPServer((“”, PORT), MyRequestHandler) as httpd: print(f“Token Usage UI 服务已启动访问 http://localhost:{PORT}”) print(“按 CtrlC 停止服务。”) httpd.serve_forever()2.index.html– 前端主页面这个文件包含了所有的HTML结构和JavaScript逻辑。你需要确保Chart.js和Inter字体的CDN链接有效。JavaScript中请求的API地址 (/api/usage) 与后端server.py中定义的一致。HTML元素的ID与JavaScript中document.getElementById查找的ID匹配。3.style.css– 样式表定义仪表盘的外观。你可以根据自己的喜好调整颜色、字体大小、间距等打造个性化的监控面板。4.3 运行与访问配置好文件后运行就非常简单了# 进入项目目录 cd ~/.openclaw/workspace/projects/token-usage-ui # 启动Python服务器 python server.py # 或者如果你的Python3命令是python3 # python3 server.py如果一切正常终端会打印出提示信息。此时打开你常用的浏览器Chrome, Firefox, Edge等在地址栏输入http://localhost:8765并回车。你应该立即看到一个深色主题的仪表盘上面显示着总成本、模型列表和趋势图。由于设置了8秒自动刷新数据会保持最新。4.4 适配不同AI助手或数据源你的AI助手可能不是OpenClaw或者会话数据不在默认路径。这时就需要修改server.py中的SESSIONS_FILE_PATH以及load_sessions()函数。步骤找到你的数据文件首先确定你的AI助手如Cursor、某特定Claude客户端将会话日志存储在什么地方。它可能是一个JSON文件也可能是SQLite数据库甚至是某个特定格式的日志文件。查看该工具的文档或配置文件。编写适配器函数在server.py中修改或重写load_sessions()函数。如果数据格式不同你还需要编写一个解析函数将原始数据转换成工具内部统一的会话字典格式包含model,input_tokens,output_tokens,timestamp等字段。def load_sessions_custom(): # 你的自定义数据加载逻辑 # 例如从SQLite读取 # import sqlite3 # conn sqlite3.connect(‘your_sessions.db’) # cursor conn.cursor() # cursor.execute(‘SELECT model, input_tokens, output_tokens, timestamp FROM sessions’) # rows cursor.fetchall() # sessions [{‘model’: r[0], ‘input_tokens’: r[1], …} for r in rows] # return sessions pass更新模型单价确保MODEL_PRICING字典包含你使用的所有模型及其最新价格。5. 常见问题排查与优化心得在实际开发和使用的过程中我遇到了不少问题也总结出一些让工具更稳定、更好用的技巧。5.1 问题排查速查表问题现象可能原因解决方案浏览器访问http://localhost:8765显示“无法连接”或空白页。1. Python服务器没有成功启动。2. 防火墙或安全软件阻止了8765端口。3. 服务器脚本有语法错误提前退出。1. 回到终端检查是否有“服务已启动”的提示。如果没有查看具体的错误信息。2. 尝试更换端口如修改PORT 8766或临时关闭防火墙测试。3. 在命令行直接运行python -m py_compile server.py检查语法。页面能打开但数据显示“无数据”或一直是模拟数据。1.SESSIONS_FILE_PATH路径配置错误。2. 会话数据文件格式不是有效的JSON。3. 文件权限不足Python无法读取。1. 在server.py中打印SESSIONS_FILE_PATH确认路径。使用os.path.exists()检查文件是否存在。2. 尝试用json.load()单独加载该文件看是否报错。检查文件内容。3. 检查文件读权限 (ls -l ~/.openclaw/.../sessions.json)。图表不显示或显示错误。1. Chart.js库没有成功从CDN加载。2. 前端JavaScript代码有错误导致图表初始化失败。3. 传递给Chart.js的数据格式不正确。1. 打开浏览器开发者工具F12查看“网络(Network)”标签确认chart.js的请求是否成功状态码200。2. 查看“控制台(Console)”标签是否有JavaScript报错。根据错误信息修复代码。3. 在updateDashboard函数中console.log打印收到的数据检查其结构是否与Chart.js配置期望的匹配。成本数字看起来明显不对过高或过低。1.MODEL_PRICING字典中的单价过时或错误。2. Token数量单位弄错应该是百万Token。3. 数据聚合逻辑有bug重复计算或漏算。1. 去AI模型供应商官网核对最新价格更新MODEL_PRICING。2. 检查calculate_session_cost函数中的计算式确认除以了1,000,000。3. 写一个小测试脚本用少量已知数据的会话记录手动计算成本与仪表盘显示对比。自动刷新不起作用。1. 前端JavaScript中的setInterval时间设置错误或被清除。2. 网络请求/api/usage持续失败导致没有新数据更新界面。1. 检查index.html中setInterval(fetchData, 8000)这行代码。2. 在fetchData函数的catch块中增加更明显的错误提示或查看网络请求是否返回错误状态。5.2 性能与使用优化技巧数据文件监控与缓存每次API请求都读取并解析整个JSON文件如果会话历史非常庞大例如数万条可能会影响响应速度。一个优化方案是使用缓存在server.py中设置一个全局变量_cached_data和_last_modified_time。每次请求时检查数据文件的最后修改时间如果文件没有变化则直接返回缓存的数据如果文件已更新则重新加载、计算并更新缓存。这能极大减少不必要的IO和计算。import os import time _data_cache None _cache_timestamp 0 CACHE_DURATION 5 # 缓存5秒 def get_usage_data_with_cache(): global _data_cache, _cache_timestamp current_time time.time() file_mtime os.path.getmtime(SESSIONS_FILE_PATH) if _data_cache is None or (current_time - _cache_timestamp) CACHE_DURATION or file_mtime _cache_timestamp: # 需要重新加载数据 sessions load_sessions() _data_cache aggregate_data(sessions) _cache_timestamp current_time return _data_cache处理超大数据集如果会话数据真的巨大全部加载到内存可能吃力。可以考虑分页或时间范围查询修改API支持?days30这样的参数只聚合最近N天的数据。使用更高效的数据结构如果数据格式固定可以考虑使用pandas虽然这会引入依赖进行快速聚合或者将历史数据导入小型数据库如SQLite进行查询。增强前端体验加载状态提示在数据刷新时可以在总成本旁边显示一个旋转的加载图标或“更新中...”的文字提升体验。手动刷新按钮除了自动刷新增加一个按钮允许用户随时手动点击刷新。时间范围选择器将固定的“7天”趋势图改为让用户可以选择“今天”、“最近7天”、“本月”等不同时间范围后端API相应地进行数据过滤。部署为系统服务可选如果你希望这个仪表盘在开机后自动启动并在后台运行可以将其配置为系统服务如Linux的systemd服务或macOS的launchd plist。这样就不需要每次都手动打开终端运行python server.py了。5.3 安全注意事项虽然这是一个本地工具但仍有几点需要注意端口暴露服务默认运行在localhost:8765只监听本机回环地址外部网络无法访问这是安全的。切勿将服务器绑定到0.0.0.0除非你清楚知道后果这可能会让你的本地数据在局域网甚至公网上被访问到。数据文件权限确保sessions.json及其父目录的权限设置合理避免其他用户读取你的AI会话记录。模拟数据在开发或演示时使用模拟数据是好的但在正式使用前务必确认切换到了真实数据源否则监控将失去意义。这个Token Usage UI项目虽然代码量不大但它精准地解决了一个特定场景下的痛点。通过亲手搭建它你不仅能实现对AI使用成本的透明化掌控还能深入理解一个完整的数据可视化小应用从前到后的运作逻辑。最重要的是它完全受你控制可以根据你的需求任意定制和扩展。如果你也在频繁使用各类AI助手不妨花点时间搭建一个属于自己的成本监控中心它带来的洞察和节省可能会远超你的预期。