OpenClaw本地模型用量分析工具：从日志解析到成本监控实战

weixin_30571465

404人浏览 · 2026-05-12 09:03:23

weixin_30571465 · 2026-05-12 09:03:23 发布

1. 项目概述：一个专为OpenClaw设计的本地模型用量分析工具

如果你正在使用OpenClaw框架进行AI智能体开发，并且对“我的智能体到底用了多少算力？”、“哪个会话最烧钱？”、“最近的成本趋势如何？”这些问题感到好奇，那么 openclaw-model-usage 这个工具就是为你量身打造的。它是一个轻量级的Python命令行工具，核心功能是直接解析你本地OpenClaw运行时生成的日志文件，将零散的、原始的JSONL数据，聚合、关联并转换成人性化的用量报告。

简单来说，它就像一个专为OpenClaw打造的“仪表盘”，让你无需连接任何外部监控服务，就能对自己的AI应用成本、性能和活跃度了如指掌。这个工具的设计哲学非常明确： 本地优先、轻量便携、开箱即用 。它不依赖任何外部数据库或服务，直接读取 ~/.openclaw/agents/ 目录下的日志，通过智能关联会话元数据，为你呈现一份结构清晰的用量分析。无论是想快速看一眼当前活跃的模型，还是需要一份详细的HTML报告用于周会复盘，它都能胜任。

2. 核心设计思路与架构解析

2.1 为什么需要独立的用量分析工具？

在AI智能体开发中，尤其是像OpenClaw这样支持复杂会话树和子智能体的框架，一次用户交互可能触发多个智能体、跨越多个会话层级、调用多种模型。这些调用记录分散在数以百计的JSONL文件中。原始的日志数据虽然完整，但可读性极差，就像一本没有目录和索引的账本。开发者或运维人员想要回答“上个月哪个智能体成本最高？”这样的问题，往往需要自己写脚本去解析、聚合，费时费力。

openclaw-model-usage 的出现，正是为了解决这个痛点。它不是一个重量级的监控平台，而是一个精准的“手术刀”，聚焦于从本地日志中提取、关联并可视化用量信息。其设计目标决定了它的几个关键特性： 零外部依赖 （只需Python环境）、 数据隐私安全 （所有分析在本地完成）、 结果即时可用 （命令秒级响应）。

2.2 数据源与关联逻辑：从碎片到全景

工具的核心智慧体现在数据关联上。它主要处理两类数据源：

用量记录源 ( *.jsonl 文件) ：这些文件记录了每一次模型调用的详细信息，包括时间戳、使用的模型、消耗的令牌数（输入/输出）、会话ID等。这是成本计算的原始依据。
会话元数据源 ( sessions.json 文件) ：这个文件相当于会话的“户口本”，记录了每个会话的创建时间、所属智能体（agent）、通道（channel）、以及最重要的——会话之间的父子关系（ spawnedBy 字段）。

工具的巧妙之处在于，它通过会话ID（ session_id ）作为桥梁，将冰冷的用量记录与富含语义的会话元数据关联起来。例如，一条记录显示会话 abc123 消耗了1000个令牌。工具会去 session.json 中查找 abc123 ，发现它的 agent 是 customer-support-bot ， channel 是 slack ，并且它是由父会话 xyz789 创建的。经过这一系列关联，原本枯燥的数字就变成了：“Slack渠道上的客户支持机器人，在其某个子会话中，消耗了1000令牌”。

注意：这种关联的准确性完全依赖于OpenClaw运行时写入元数据的完整性。如果 sessions.json 文件缺失或 spawnedBy 字段为空，工具将无法构建完整的会话树，相关会话在报告中将显示为“孤儿节点”。

2.3 命令行接口（CLI）设计哲学：兼顾人类与机器

工具提供了丰富的子命令，其设计体现了清晰的分层思想：

面向人类的友好视图 ：如 overview （概览）、 top-agents （顶级智能体）、 current （当前状态）。这些命令输出格式紧凑、重点突出，去除了JSON的括号引号，适合在终端快速浏览。例如， overview 命令在一屏内展示了总成本、令牌数、调用次数以及当前活跃的模型和智能体，信息密度极高。
面向机器的原始/详细视图 ：如 rows （原始行）、 sessions （会话列表）、 agents （智能体列表）。这些命令通常配合 --json 标志使用，输出结构化的JSON数据，便于被其他脚本（如自动化告警、数据持久化）进一步处理。
自包含的HTML仪表盘 ： dashboard 命令生成一个完整的、响应式的HTML文件。这个文件包含了图表（如每日成本柱状图）和交互表格，你可以直接把它发给项目经理或存档，无需任何额外的Web服务器。

这种设计使得工具既能满足日常运维的“瞟一眼”需求，也能满足深度分析的“挖数据”需求。

3. 从零开始：环境准备与工具安装

3.1 环境与依赖检查

openclaw-model-usage 是一个Python工具，它强烈推荐使用 uv 作为Python包管理和运行工具，这比传统的 pip + venv 组合更快速、更现代。在开始之前，请确保你的系统满足以下条件：

Python 3.8+ ：这是运行的基础。在终端输入 python3 --version 或 python --version 检查。
已安装uv ：如果未安装，可以使用以下命令一键安装（以macOS/Linux为例）：
```
# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh
```
安装后，重新打开终端或运行 source ~/.bashrc （或 source ~/.zshrc ）使 uv 命令生效。通过 uv --version 验证安装。
有效的OpenClaw日志 ：工具需要读取 ~/.openclaw/agents/ 目录下的数据。请确保你已经在运行OpenClaw智能体并产生了一些日志。如果没有，可以先运行一些OpenClaw任务来生成数据。

3.2 获取与安装工具

你有两种主要方式来使用这个工具：

方式一：直接从GitHub仓库运行（推荐用于体验和临时使用）

这是最快捷的方式，适合快速尝鲜或一次性分析。

# 克隆仓库到本地
git clone https://github.com/ranasalalali/openclaw-model-usage.git
cd openclaw-model-usage

# 使用uv直接运行项目内的CLI
uv run --project . openclaw-model-usage --help

这种方式利用了 uv 的 --project 参数，它会在项目目录下自动处理依赖，而无需显式安装。

方式二：安装为全局可用的CLI工具

如果你计划频繁使用，可以将其安装到系统环境或用户环境中。

# 进入项目目录
cd openclaw-model-usage

# 使用uv将包安装到当前Python环境的site-packages中
uv pip install -e .

# 安装后，可以直接在任何地方调用
openclaw-model-usage --help

-e 参数代表“可编辑模式”安装，这意味着如果你后续拉取仓库更新，无需重新安装，工具会自动使用最新代码。

3.3 验证安装与首次运行

安装完成后，进行一个简单的验证，确保工具能正确识别你的OpenClaw环境。

# 运行最基本的概览命令，查看是否有数据输出
uv run --project . openclaw-model-usage overview

如果一切正常，你将看到类似这样的输出：

Usage overview — $0.0000, 0 tok, 0 calls
Agents 0 | Sessions 0 | Models 0
Current: (no recent activity)

“0数据”是正常的，如果你刚刚安装OpenClaw，可能还没有产生用量。此时，你可以运行几个OpenClaw智能体任务，然后再执行上述命令，就能看到真实的用量统计了。

实操心得 ：在团队协作环境中，建议将 openclaw-model-usage 的安装步骤写入项目的 README 或 Makefile 中。对于使用Docker的开发环境，可以在构建镜像时通过 uv pip install git+https://github.com/ranasalalali/openclaw-model-usage.git 一行命令完成安装，确保所有成员的分析环境一致。

4. 核心功能详解与实战命令

4.1 快速概览：掌握全局用量态势

overview 是默认命令，也是你每天打开终端可能第一个运行的命令。它提供了一个信息高度浓缩的“仪表盘视图”。

uv run --project . openclaw-model-usage overview

典型输出如下：

Usage overview — $0.1543, 42,580 tok, 127 calls
Agents 4 | Sessions 18 | Models 3
Current: openai/gpt-4o | data-analyzer-agent | session-8f3a | (no subagent)

Top agents
1. data-analyzer-agent — $0.0987, 28,100 tok, 45 sessions
2. customer-chatbot — $0.0432, 11,850 tok, 62 sessions
3. code-reviewer — $0.0124, 2,630 tok, 20 sessions

Top sessions
1. session-8f3a | data-analyzer-agent | parent (none) | depth 0 — $0.0321, 9,800 tok, 12 calls
2. session-bc2d | customer-chatbot | parent (none) | depth 0 — $0.0288, 7,200 tok, 31 calls
...

Top models
1. openai/gpt-4o — $0.1420, 39,500 tok, 118 calls
2. anthropic/claude-3-haiku — $0.0105, 2,800 tok, 8 calls
3. openai/gpt-3.5-turbo — $0.0018, 280 tok, 1 calls

输出解读与行动点 ：

第一行 ：总成本、总令牌数、总调用次数。这是你成本控制的“北极星指标”。
第二行 ：涉及的智能体、会话、模型总数。数量激增可能意味着有异常循环或未预期的智能体被触发。
Current ：当前（最近一次）活动的模型、智能体、会话。帮你快速定位“谁正在运行”。
Top agents/sessions/models ：成本排行榜。立即锁定资源消耗的“大户”，是进行性能优化或成本配额调整的首要依据。

4.2 深度下钻：按维度进行排名分析

当概览发现某个智能体成本异常高时，你需要下钻分析。

分析成本最高的智能体 ：

uv run --project . openclaw-model-usage top-agents --limit 5

这个命令会列出成本前5的智能体。结合 --since-days 参数，可以聚焦于近期活动：

uv run --project . openclaw-model-usage top-agents --since-days 1

如果发现 data-analyzer-agent 在过去24小时花费异常，你可以进一步查看它涉及的所有会话：

uv run --project . openclaw-model-usage top-sessions --agent data-analyzer-agent

分析特定渠道的用量 ：如果你的OpenClaw智能体接入了多个渠道（如Discord、Slack），可以按渠道过滤：

uv run --project . openclaw-model-usage overview --channel discord
uv run --project . openclaw-model-usage top-sessions --channel slack --limit 10

4.3 会话树洞察：理解复杂的智能体协作

OpenClaw的强大之处在于会话树，一个父会话可以派生出多个子会话（子智能体）。 session-tree 命令可以可视化这种关系。

uv run --project . openclaw-model-usage session-tree --session-id <你的根会话ID>

或者，为了看到完整的树状结构，你可以使用JSON输出并配合 jq 工具（需单独安装）进行格式化：

uv run --project . openclaw-model-usage session-tree --json | jq '.'

输出会展示会话的层级结构、每个节点的成本及子节点数量，帮助你理解一次复杂任务是如何分解执行以及成本是如何分布的。

4.4 生成专业的HTML仪表盘报告

对于周报、月度复盘或向非技术同事汇报，终端输出不够直观。 dashboard 命令可以生成一个美观的静态HTML报告。

# 生成默认报告，输出到 dist/dashboard.html
uv run --project . openclaw-model-usage dashboard

# 自定义报告标题和输出路径
uv run --project . openclaw-model-usage dashboard --out ./reports/october-usage.html --title "十月OpenClaw用量报告"

# 仅分析过去7天Discord渠道的数据
uv run --project . openclaw-model-usage dashboard --channel discord --since-days 7 --out ./discord-weekly.html

生成的HTML文件是自包含的（包含了内联的CSS和JavaScript），你可以直接用浏览器打开它，也可以通过邮件发送或部署到任何静态网站服务器上。报告通常包含：

关键指标汇总卡片
每日成本趋势柱状图
智能体、会话、模型的成本排名表
最近的详细用量记录

注意事项 ： dashboard 命令默认读取的是你真实的日志路径（ ~/.openclaw/agents ）。项目内有一个 tests/fixtures_root/ 目录存放测试数据，切勿在正常使用时通过 --root 参数指向它，否则生成的将是基于模拟数据的测试报告，而非你的真实用量。

4.5 机器可读的JSON输出与集成

所有命令都支持 --json 标志，输出结构化的数据，方便集成到自动化流程中。

# 获取JSON格式的概览数据，并用jq美化输出
uv run --project . openclaw-model-usage overview --json | jq '.'

# 获取原始用量行数据，用于自定义分析管道
uv run --project . openclaw-model-usage rows --json --pretty > usage_data.json

# 在Shell脚本中，提取总成本并判断是否超阈值
TOTAL_COST=$(uv run --project . openclaw-model-usage overview --json | jq '.total_cost')
if (( $(echo "$TOTAL_COST > 10.0" | bc -l) )); then
    echo "警告：本月成本已超过10美元！"
fi

5. 高级用法、过滤技巧与性能调优

5.1 灵活的数据过滤与切片

工具提供了强大的过滤选项，让你能像查询数据库一样分析数据。

时间范围过滤 ： --since-days 是最常用的时间过滤器。

# 查看过去30天的数据
uv run --project . openclaw-model-usage overview --since-days 30
# 查看过去24小时的数据
uv run --project . openclaw-model-usage recent --since-days 1

对于更精确的范围，你可以组合使用 --after 和 --before （接受ISO 8601格式时间戳）。

uv run --project . openclaw-model-usage rows --after 2024-10-01T00:00:00Z --before 2024-10-31T23:59:59Z --json

多维度组合过滤 ：过滤器可以组合使用，实现精准定位。

# 查看“customer-chatbot”智能体在“slack”渠道过去一周的顶级会话
uv run --project . openclaw-model-usage top-sessions --agent customer-chatbot --channel slack --since-days 7

# 查看特定模型（如GPT-4）的所有调用记录
uv run --project . openclaw-model-usage rows --model openai/gpt-4 --json --pretty

5.2 处理大规模日志的性能考量

当日志量非常大（例如数月甚至数年的数据）时，直接分析可能会较慢。你可以采取以下策略：

限制分析范围 ：始终使用 --since-days 参数，避免全量扫描。对于历史归档分析，可以编写脚本按月份分批执行。
使用更轻量的命令 ： overview 、 top-agents 等聚合命令比输出所有原始 rows 要快得多。
指向日志快照 ：如果历史日志已归档，可以使用 --root 参数指向一个拷贝出来的日志目录进行分析，而不影响正在运行的OpenClaw实例。
```
uv run --project . openclaw-model-usage overview --root /path/to/archived/logs/2024-Q3
```

5.3 集成到自动化监控与告警流程

openclaw-model-usage 的JSON输出使其能轻松融入自动化系统。

示例：每日成本报告脚本 ( daily_cost_report.sh )：

#!/bin/bash
# 每日成本报告脚本
REPORT_DATE=$(date +%Y-%m-%d)
REPORT_FILE="./reports/daily_cost_${REPORT_DATE}.json"

# 获取昨日至今的用量概览（JSON格式）
uv run --project . openclaw-model-usage overview --since-days 1 --json > $REPORT_FILE

# 从JSON中提取关键指标
TOTAL_COST=$(jq '.total_cost' $REPORT_FILE)
TOP_AGENT=$(jq -r '.top_agents[0].agent // "N/A"' $REPORT_FILE)

# 判断是否触发告警（例如单日成本超过5美元）
ALERT_THRESHOLD=5.0
if (( $(echo "$TOTAL_COST > $ALERT_THRESHOLD" | bc -l) )); then
    echo "🚨 告警：$REPORT_DATE 日OpenClaw成本为\$${TOTAL_COST}，已超过阈值\$${ALERT_THRESHOLD}。最高消耗智能体：$TOP_AGENT" | mail -s "OpenClaw成本告警" your-team@example.com
fi

# 将报告文件路径记录到日志
echo "$(date): 每日成本报告已生成 - $REPORT_FILE" >> ./report.log

可以将此脚本加入 crontab ，实现每日自动运行和成本监控。

示例：CI/CD中的用量检查 ：在持续集成流程中，可以在测试套件运行后，检查测试过程中产生的AI调用成本，防止因测试用例设计不当导致意外的高额费用。

# 假设在GitHub Actions中的某个job
- name: Analyze test usage cost
  run: |
    COST=$(uv run --project . openclaw-model-usage overview --since-minutes 30 --json | jq '.total_cost')
    # 如果30分钟内的测试成本超过1美元，则标记为失败
    if (( $(echo "$COST > 1.0" | bc -l) )); then
      echo "::error::测试阶段AI调用成本过高：\$$COST"
      exit 1
    fi

6. 常见问题排查与实战经验

在实际使用中，你可能会遇到一些典型问题。下面是一个快速排查指南。

问题现象	可能原因	解决方案
运行命令后无任何输出，或输出“0 calls”。	1. 指定的日志路径错误。 2. OpenClaw未产生日志或日志格式不符。 3. 过滤条件过于严格（如 `--since-days 1` 但今天无活动）。	1. 使用 `--root ~/.openclaw/agents` 显式指定路径。 2. 确认OpenClaw正在运行并已配置日志输出。检查 `~/.openclaw/agents/` 下是否有 `*.jsonl` 文件。 3. 先不使用 `--since-days` 参数，查看全部历史数据。
会话名称显示为会话ID，而非易读的名称。	对应的 `sessions.json` 文件中缺少该会话的元数据（如 `name` , `agent` 字段）。	这是数据源问题。确保OpenClaw应用正确配置并写入了会话元数据。对于历史数据，无法补救。
在 `session-tree` 中看不到父子关系。	会话元数据中的 `spawnedBy` 字段缺失或为空，工具无法建立树形链接。	同上，需确保OpenClaw在创建子会话时正确设置了 `spawnedBy` 。检查最新的会话日志是否包含此信息。
生成HTML仪表盘时非常慢。	分析的日志时间范围太长，数据量过大。	使用 `--since-days` 限制分析范围。对于全量历史分析，考虑在性能更强的机器上运行，或分批处理。
成本计算为0或明显偏低。	1. 日志中的 `usage` 字段可能缺失或格式不正确。 2. 工具内置的模型单价表未覆盖你使用的模型。	1. 检查一条JSONL日志，确认有 `"usage": {"prompt_tokens": ..., "completion_tokens": ...}` 结构。 2. 查看工具源码中关于模型单价配置的部分，确认你的模型是否在列表中。可能需要提交Issue或自行扩展。
命令报错 `ModuleNotFoundError` 。	Python依赖未正确安装。	在项目根目录下，尝试使用 `uv sync` 安装所有依赖。如果全局安装，请使用 `uv pip install -e .` 。

实操心得与进阶技巧 ：

定期清理与归档日志 ：OpenClaw的JSONL日志会不断增长。建议定期（如每月）将旧的日志文件压缩归档，并移动到其他目录。这不仅能释放磁盘空间，也能提升 openclaw-model-usage 分析近期数据的速度。你可以写一个简单的cron job来完成这个任务。
自定义模型单价 ：工具内置了一份模型单价映射表，用于将令牌数转换为估算成本。如果OpenClaw使用了新的或自定义模型，或者厂商调整了价格，你需要更新工具源码中的 MODEL_RATES 字典（通常在 src/openclaw_model_usage/cost.py 或类似文件中），以确保成本估算的准确性。
结合 jq 进行超级查询 ：虽然工具提供了丰富的过滤选项，但有时你需要更复杂的查询。可以将工具的JSON输出与 jq 结合，实现无限可能。例如，找出所有单次调用消耗超过5000令牌的“异常”记录：
```
uv run --project . openclaw-model-usage rows --json | jq '[.[] | select(.usage.total_tokens > 5000)]'
```
用于智能体自身的元监控 ：你可以创建一个OpenClaw智能体，其任务就是定期运行 openclaw-model-usage 命令，分析自身及其兄弟智能体的用量，并在成本超过阈值时通过消息通道（如Slack）发送告警。这实现了“自我监控”的闭环。