ClawMeter — 成本追踪仪表板

实时跟踪 OpenClaw API 使用量与支出，并支持预算超支告警。

概览

ClawMeter 是一款可自托管的成本追踪仪表板，用于监控您的 OpenClaw 会话日志，自动计算 Token 使用量与 API 费用，并提供实时分析能力及可定制的预算告警功能。

适用于以下场景：

• 希望清晰掌握 AI 相关支出的用户
• 需对 OpenClaw 部署进行预算管控的团队
• 基于成本表现优化模型选型的开发者
• 希望避免意外 API 账单的任何人

安装

前提条件

• 已安装并正在运行 OpenClaw
• Node.js v18+（用于运行仪表板服务端）
• OpenClaw 中已启用会话日志（默认开启）

配置步骤

1. 克隆或下载 ClawMeter：

   cd ~/.openclaw/workspace
   git clone https://github.com/yourusername/clawmeter.git
   cd clawmeter
   

2. 安装依赖：

   npm install
   

3. 配置（可选）：

   cp .env.example .env
   # 编辑 .env 文件以自定义路径、预算限额或告警设置
   

4. 导入现有日志：

   npm run ingest
   

5. 启动仪表板：

   npm start
   

6. 打开仪表板： 访问 http://localhost:3377

命令支持

安装该技能后，您的 OpenClaw 智能体可响应以下指令：

支出查询

• “我今天花了多少钱？”

  • 显示当日总支出及预算使用百分比

• “我本月的支出是多少？”

  • 显示当月累计支出及预算状态

• “显示本周的费用”

  • 汇总过去 7 天的支出情况

成本分析

• “哪个模型最贵？”

  • 按模型（Claude、GPT、Gemini 等）拆分成本

• “显示我最贵的会话”

  • 按总成本排序列出 Top 会话

• “我的日均支出是多少？”

  • 计算最近 30 天的日均支出

仪表板与报告

• “打开我的成本仪表板”

  • 提供指向 http://localhost:3377 的链接

• “生成一份成本报告”

  • 导出汇总数据（今日 / 本周 / 本月 / 历史总计）

数据管理

• “刷新成本数据”

  • 手动触发会话日志重新导入

• “清理旧的成本数据”

  • （可选）归档或删除 X 天前的数据

API 接口

ClawMeter 提供 REST API，供智能体调用查询：

汇总统计

GET http://localhost:3377/api/summary

响应示例：

{
  "today": 2.15,
  "week": 8.42,
  "month": 32.76,
  "allTime": 127.89,
  "sessions": 234,
  "messages": 1842,
  "budgetDaily": 5.0,
  "budgetMonthly": 100.0
}

每日明细

GET http://localhost:3377/api/daily?days=30

响应示例：

[
  {
    "date": "2026-02-14",
    "cost": 2.15,
    "input_tokens": 45820,
    "output_tokens": 12340,
    "messages": 18
  }
]

会话列表

GET http://localhost:3377/api/sessions?limit=50&offset=0

响应示例：

[
  {
    "id": "abc123",
    "agent": "main",
    "model": "claude-sonnet-4-5",
    "total_cost": 0.842,
    "message_count": 12
  }
]

模型成本拆分

GET http://localhost:3377/api/models

响应示例：

[
  {
    "model": "claude-sonnet-4-5",
    "provider": "anthropic",
    "total_cost": 45.62,
    "message_count": 324
  }
]

Top 会话

GET http://localhost:3377/api/top-sessions?limit=10

预算告警

GET http://localhost:3377/api/alerts

手动导入

POST http://localhost:3377/api/ingest

配置

环境变量

编辑 .env 文件来自定义各项参数：

# 路径配置
OPENCLAW_AGENTS_DIR=/home/youruser/.openclaw/agents
CLAWMETER_DB=/home/youruser/.openclaw/workspace/clawmeter/data/clawmeter.db

# 服务端配置
PORT=3377

# 预算配置（单位：美元）
BUDGET_DAILY_LIMIT=5.00
BUDGET_MONTHLY_LIMIT=100.00

# Telegram 告警（可选）
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# 邮件告警（可选）
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@email.com
SMTP_PASS=your_app_password
ALERT_EMAIL_TO=notify@yourdomain.com

预算告警

ClawMeter 将自动比对当前支出与配置的阈值，并通过以下方式发送告警：

• Telegram — 向您的手机即时推送通知
• 邮件 — 通过 SMTP 发送

告警触发条件：

• 当日支出超过 BUDGET_DAILY_LIMIT
• 当月支出超过 BUDGET_MONTHLY_LIMIT

告警限频策略：每类告警每天最多触发一次（防止信息刷屏）。

智能体集成示例

示例 1：日支出检查

用户：“我今天花了多少钱？”

智能体响应：

让我为您检查支出情况...

📊 今日支出：$2.15  
预算：$5.00（已使用 43%）

您今日剩余额度为 $2.85。

实现代码：

const res = await fetch('http://localhost:3377/api/summary');
const data = await res.json();
const pct = (data.today / data.budgetDaily * 100).toFixed(0);
return `📊 今日支出：$${data.today.toFixed(2)}\n预算：$${data.budgetDaily.toFixed(2)} (${pct}% 已使用)\n\n您今日剩余额度为 $${(data.budgetDaily - data.today).toFixed(2)}。`;

示例 2：模型成本对比

用户：“为节省成本，我该选用哪个模型？”

智能体响应：

根据您的历史使用数据：

💰 每千条消息成本：
• Claude Haiku 3-5：$0.12  
• GPT-4o-mini：$0.18  
• Claude Sonnet 4-5：$0.45  
• Claude Opus 4：$1.23  

建议：简单任务使用 Haiku，复杂任务使用 Sonnet。

示例 3：预算超支预警

智能体（主动推送）：

⚠️ 预算告警

您今日已支出 $5.52，超出 $5.00 的日预算限额。

今日 Top 会话：
1. 代码审查任务 — $2.10  
2. 研究项目 — $1.85  
3. 邮件撰写 — $0.98  

建议切换至更低成本模型，或暂停非紧急任务。

仪表板功能

概览页

• 今日支出 及预算进度条
• 周/月累计总额
• 历史总支出 与消息总数
• 预算状态指示器（绿色/黄色/红色标识）

分析页

• 日成本图表（柱状图，支持 7 / 14 / 30 / 90 天视图）
• 模型成本占比（饼图，含百分比）
• Top 会话（按成本排序）
• 近期活动流

告警历史

• 查看所有已触发的预算告警
• 了解告警触发时间与原因
• 长期追踪支出趋势

典型应用场景

1. 个人预算管理

场景：您希望将 OpenClaw 月度成本控制在 $100 以内。

配置方式：

• 设置 BUDGET_MONTHLY_LIMIT=100.00
• 启用 Telegram 告警
• 每周定期查看仪表板

效果：预算超支前即收到提醒，及时调整使用策略。

2. 团队成本分摊

场景：多个团队成员共用同一套 OpenClaw 实例。

配置方式：

• ClawMeter 按智能体/会话维度分别追踪成本
• 通过 API 导出数据用于财务报告
• 分析各智能体/项目的成本分布

效果：实现公平的成本分摊，识别潜在优化点。

3. 模型选型优化

场景：您不确定不同任务应选用哪种模型。

配置方式：

• 针对不同任务尝试多种模型
• 在 ClawMeter 仪表板中横向对比成本
• 分析每条消息/每个 Token 的平均成本

效果：基于数据驱动决策，平衡成本与质量。

4. 生产环境监控

场景：OpenClaw 在生产环境中运行，需具备成本可视性。

配置方式：

• ClawMeter 实时自动导入日志
• 设置更激进的预算告警阈值
• 持续监控仪表板异常波动

效果：第一时间发现成本激增，避免不可控支出。

故障排查

仪表板显示 $0.00

原因：未找到会话日志，或尚未完成导入。

解决方法：

1. 确认 OPENCLAW_AGENTS_DIR 指向正确路径
2. 手动执行 npm run ingest
3. 检查 agents/*/sessions/ 目录下是否存在 .jsonl 文件

文件自动监听失效

原因：文件监视器未能捕获变更事件。

解决方法：

1. 确保服务正在运行（npm start）
2. 检查终端是否输出 📥 X new events 日志
3. 验证会话目录的文件权限是否正确

预算告警未发出

原因：凭证缺失或配置错误。

解决方法：

1. 再次核对 .env 中的 TELEGRAM_BOT_TOKEN 和 TELEGRAM_CHAT_ID
2. 若使用邮件告警，请验证 SMTP 配置
3. 查阅服务端日志中的报错信息

数据库错误

原因：数据库文件损坏或被锁定。

解决方法：

1. 停止服务进程
2. 备份 data/clawmeter.db
3. 删除数据库文件并重新执行 npm run ingest

高级配置

自定义模型定价

若您使用了自定义模型，或官方定价发生变更：

1. 编辑 src/pricing.mjs
2. 向 MODEL_PRICING 对象中添加新条目：

   'your-custom-model': {
     input: 2.50,    // 每百万 Token 成本
     output: 10.00,  // 每百万 Token 成本
     cacheRead: 0.25,   // 可选
     cacheWrite: 3.75   // 可选
   }
   

3. 重启服务

定时报告

使用 cron 定期生成日报/周报：

# 每日 9:00 发送摘要
0 9 * * * curl -s http://localhost:3377/api/summary | mail -s "每日成本报告" you@example.com

数据导出

导出原始数据供外部分析：

# 将全部会话导出为 CSV
sqlite3 data/clawmeter.db "SELECT * FROM sessions" -csv > sessions.csv

作为系统服务运行

创建 systemd 服务以实现持久化运行：

# /etc/systemd/system/clawmeter.service
[Unit]
Description=ClawMeter 成本追踪仪表板
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/.openclaw/workspace/clawmeter
ExecStart=/usr/bin/npm start
Restart=always

[Install]
WantedBy=multi-user.target

启用并启动服务：

sudo systemctl enable clawmeter
sudo systemctl start clawmeter

安全注意事项

仅限本地访问

默认情况下，ClawMeter 绑定至 localhost:3377，不对外网暴露。

如需远程访问，请使用 SSH 隧道：

ssh -L 3377:localhost:3377 your-server

敏感数据处理

会话日志可能包含对话内容。ClawMeter 的设计原则如下：

• 仅存储用量元数据（Token 数、费用、时间戳）
• 不保存消息正文或提示词（prompts）
• 数据库采用本地 SQLite（无云端同步）

API 认证

ClawMeter 当前不提供认证机制。生产环境建议：

1. 部署于带身份验证的反向代理（如 nginx/caddy）之后
2. 使用防火墙规则限制访问来源
3. 部署在私有网络内

性能表现

资源占用

• CPU：极低（事件驱动式日志摄入）
• 内存：约 50–100 MB
• 磁盘：数据库增长约每条消息 1 KB（SQLite 效率极高）
• 网络：无外网通信（纯本地运行）

可扩展性

ClawMeter 可轻松支持：

• 10 万+ 条消息
• 多年历史数据，性能无明显衰减
• 多个智能体（通过目录结构隔离）

对于超大规模部署（百万级消息），建议：

• 定期归档数据库
• 迁移至 PostgreSQL 后端（需修改代码）

路线图

计划新增功能：

• 多用户身份认证
• 支持 PostgreSQL（面向大规模部署）
• 导出为 CSV / JSON 格式
• 成本预测（预估月度支出）
• Slack / Discord Webhook 支持
• Token 使用热力图
• 模型性能追踪（延迟、质量指标）
• 基于使用模式的预算建议

支持

• 文档：GitHub README
• 问题反馈：GitHub Issues
• 社区交流：OpenClaw Discord

许可证

MIT — 永久免费且开源。

由 OpenClaw 社区倾力打造 ⚡

追踪您的支出 · 优化您的成本 · 掌控全局