Usage Visualizer

核心用法

Usage Visualizer 是专为 OpenClaw 设计的分析引擎，通过解析会话日志生成专业级可视化报告。核心工作流程包含四步：首先自动扫描 ~/.openclaw/agents/*/sessions/*.jsonl 提取原始数据；其次将多厂商元数据标准化为统一 Schema（涵盖 Token、缓存命中、成本）；然后持久化至本地 SQLite 数据库实现幂等同步；最终通过 HTML/SVG 模板渲染高保真 PNG 报告。

主要功能模块包括：

• 可视化报告生成：generate_report_image.py 支持今日/周/月多周期视图，输出 PPT 风格卡片含 30 天趋势折线
• 文本摘要：report.py 提供控制台友好的 emoji 富文本输出及 JSON 格式供集成
• 预算监控：alert.py 支持阈值告警（如单日超 $10 触发通知）
• 成本计算：calc_cost.py 内置模型定价表，自动计算百万 Token 成本与缓存节省率

显著优点

1. 零配置开箱即用：自动检测 OpenClaw 日志路径，无需手动指定数据源
2. 专业级视觉输出：采用 SVG 矢量图表与 PPT 卡片布局，适合汇报场景
3. 深度 Token 分析：超越基础成本统计，细化至 Anthropic Prompt Caching 的读写命中率
4. 数据幂等性：SQLite 存储层确保重复同步不重复计数，支持增量更新
5. 轻量可扩展：纯 Python 实现，依赖仅 html2image + 浏览器引擎，易于二次开发

潜在局限

• 渲染依赖外部环境：PNG 生成需本地 Chrome/Chromium 及 Linux 服务器的 Xvfb 支持，容器化部署需额外配置
• 数据源单一：仅支持 OpenClaw 原生日志格式，不兼容其他 LLM 工具链
• 无实时流式能力：基于批处理架构，最小粒度为今日汇总，非秒级监控
• 告警渠道有限：当前仅支持控制台输出，无原生邮件/Slack/Webhook 集成

适合人群

• OpenClaw 重度用户，需量化 Agent 使用成本与效率
• 技术团队管理者，需向非技术 stakeholders 呈现 LLM 支出报告
• 模型选型决策者，需对比不同模型在真实场景下的 Token 效率

常规风险

• 数据隐私：日志可能包含敏感 Prompt 内容，SQLite 本地存储虽避免云端泄露，但需确保文件系统权限控制
• 路径遍历风险：若 OPENCLAW_WORKSPACE 环境变量被恶意篡改，可能导致非预期目录扫描
• 依赖供应链：html2image 及浏览器依赖引入额外攻击面，建议锁定依赖版本并定期更新

核心用法

Usage Visualizer 是一款专为 OpenClaw 生态打造的高保真分析引擎，核心功能是将本地会话日志转化为专业级可视化报告。用户只需克隆仓库并安装依赖，即可通过 fetch_usage.py 完成历史日志的全量同步，随后利用 generate_report_image.py 生成当日、本周或近30天的 PNG 报告卡片。工具同时支持轻量级的文本摘要输出（report.py）以及预算告警功能（alert.py），满足不同场景下的用量监控需求。

技术实现上，该工具采用「提取-标准化-持久化-渲染」四步流水线：自动扫描 ~/.openclaw/agents/*/sessions/*.jsonl 路径下的会话文件，将分散的提供商元数据统一映射为标准化 schema，存入本地 SQLite 数据库确保幂等查询，最终通过 HTML/SVG 模板引擎配合无头浏览器生成高分辨率 PNG 图片。

显著优点

纯本地架构，隐私零风险：所有数据处理均在本地完成，不调用任何外部 API，API 密钥等敏感信息采用 SHA256 哈希后存储，从根本上杜绝数据泄露隐患。

专业级视觉输出：生成的 PPT 风格卡片配备 30 天 SVG 趋势线和多维度图表，可直接用于团队汇报或决策参考，远超同类工具的简陋文本输出。

深度 token 级分析：不仅追踪成本，更聚焦 input/output token 明细及 Anthropic prompt caching 的读写性能，帮助用户识别缓存优化空间。

零配置开箱即用：自动检测 OpenClaw 工作目录，无需复杂初始化即可同步历史数据，大幅降低上手门槛。

潜在缺点与局限性

环境依赖较重：PNG 渲染依赖 html2image 及 Chrome/Chromium 浏览器，Linux 服务器需额外配置 Xvfb 等无头环境，对容器化部署不够友好。

平台支持有限：当前仅支持 macOS（darwin）和 Linux，Windows 用户需借助 WSL 运行。

数据源单一：仅兼容 OpenClaw/Clawdbot 的会话日志格式，无法直接接入其他 LLM 平台（如直接使用 OpenAI API 的独立脚本）。

告警功能基础：预算告警仅支持阈值触发，缺少多维度智能预测或异常检测能力。

适合的目标群体

该工具尤其适合以下用户：OpenClaw/Clawdbot 重度使用者，需要向团队或管理层展示用量趋势的技术负责人，关注 Anthropic 缓存机制优化效果的高级开发者，以及对数据隐私有严格要求、拒绝使用云端分析服务的企业用户。

使用风险

性能风险：大规模历史日志同步时可能产生较多 I/O 操作，建议在非高峰时段执行 --full 同步；数据库长期未清理可能膨胀，需定期维护。

依赖风险：html2image 及其浏览器依赖可能因版本差异导致渲染失败，建议在稳定环境中锁定依赖版本。

路径权限风险：若自定义 OPENCLAW_WORKSPACE 环境变量，需确保路径可读且数据库目录（~/.llm-cost-monitor）权限设置为 700，避免其他用户访问统计信息。

预留依赖隐患：requirements.txt 中声明了未实际使用的 requests 库，虽无直接安全风险，但建议后续版本清理以减少攻击面。