1. 项目概述与核心价值

如果你正在使用 OpenClaw 框架来构建和管理你的 AI 代理（Agent），那么一个绕不开的“灵魂拷问”就是：钱都花哪儿了？具体是哪个代理、哪个会话、哪个模型消耗了最多的 Token 和成本？尤其是在团队协作或复杂项目场景下，多个代理、嵌套会话同时运行，账单明细往往是一笔糊涂账。 openclaw-model-usage 这个工具，就是为解决这个痛点而生的。它是一个轻量、便携的 Python CLI 工具，核心使命是帮你从本地 OpenClaw 的会话日志（JSONL 文件）中，清晰地洞察模型使用情况。

简单来说，它把你的本地日志文件当作数据源，通过解析、聚合和关联，将原始的、零散的调用记录，转化为人性化的使用报告。你可以把它想象成一个专为 OpenClaw 设计的“本地版成本监控仪表盘”。它不依赖任何外部服务，完全在本地运行，确保了数据的私密性和即时性。无论是想快速查看当前哪个模型在活跃，还是想分析过去一周的成本大头，或是想理清复杂的会话树（Session Tree）结构，这个工具都能提供直观的答案。对于开发者、运维人员或是项目管理者而言，掌握这些数据是进行成本优化、资源分配和性能调优的第一步。

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

2.1 设计哲学：本地优先与最小化依赖

openclaw-model-usage 的设计遵循了几个非常务实的原则。首先是 本地优先（Local-First） 。所有分析都基于你机器上 ~/.openclaw/agents/ 目录下的日志文件。这意味着你的使用数据永远不会离开你的本地环境，既满足了隐私和安全需求，也避免了网络延迟或服务不可用的问题。工具运行时，就是直接读取这些 JSONL 和 JSON 文件，进行内存中的计算和聚合。

其次是 最小化依赖和便携性 。项目使用 uv 作为包管理和运行工具，这比传统的 pip + venv 组合更轻量、快速。整个工具的核心逻辑封装在一个 Python 脚本 ( scripts/model_usage.py ) 中，同时也有打包好的 CLI 入口。这种设计使得它既可以作为一个独立的脚本直接运行，也可以作为一个 AgentSkill 被集成到 OpenClaw 代理的指令集中，或者通过 uv run 以项目模式调用，非常灵活。

最后是 输出的人性化与机器可读性兼顾 。工具提供了两类视图：一类是面向命令行交互、追求信息密度的“人类友好”视图（如 overview , top-agents ），用简洁的文本表格呈现关键摘要；另一类是面向自动化脚本的“详细/原始”视图（如 agents --json ），输出结构化的 JSON 数据，方便进一步处理或集成到其他监控系统中。

2.2 数据源与关联逻辑剖析

工具的核心能力建立在准确的数据关联之上。它主要处理两类数据源：

  1. 主要使用记录源 ： ~/.openclaw/agents/*/sessions/*.jsonl 文件。每个 JSONL 文件代表一个会话，里面按行记录了该会话中发生的所有事件，其中就包含了关键的“助手消息使用行”（assistant message usage rows），里面记载了模型调用、消耗的 Token 数、模型名称等信息。
  2. 会话元数据源 ： ~/.openclaw/agents/*/sessions/sessions.json 文件。这个文件可以看作是一个会话的索引或目录，记录了每个会话的 ID、名称、创建时间、所属渠道（channel），以及最重要的——会话之间的父子关系（通过 spawnedBy 字段）。

工具的“智能”之处在于 连接（Join） 操作。它不仅仅是从 JSONL 文件中汇总 Token 和成本，还会尝试去 sessions.json 中查找对应会话的友好名称（而不仅仅是 UUID）、渠道信息，并根据 spawnedBy 字段构建出会话树（Session Tree）。这使得在输出 top-sessions 或 session-tree 时，你能看到“父会话A -> 子会话B”这样的清晰关系，而不是一堆难以理解的 ID。

注意：数据关联的局限性 ：这种关联的准确性完全依赖于 OpenClaw 运行时写入本地元数据的完整性和正确性。如果 sessions.json 文件缺失、损坏，或者某些会话没有正确记录 spawnedBy 字段，那么工具就无法建立完整的父子链路，相应的“会话树”视图就会不完整。这是所有基于日志分析工具的通用限制。

2.3 与类似工具的差异化定位

你可能会问，OpenClaw 或者模型提供商（如 OpenAI）不是本身就有用量统计吗？为什么还需要这个工具？关键在于 维度和实时性 。

  • 模型提供商后台 ：通常只提供按账号、按 API Key 的总量统计，无法细化到具体的“代理”、“会话”或“子任务”维度。你无法知道是团队中哪个成员编写的哪个代理脚本消耗了大部分预算。
  • OpenClaw 内置统计 ：可能比较简单，或者以不同形式呈现。 openclaw-model-usage 提供了更聚合、更面向运营分析的视图（如按天统计、Top N 排名），并且其输出的设计（尤其是 JSON 格式）更便于进行二次开发或告警集成。
  • 第三方监控平台 ：往往需要将数据发送到云端，存在隐私和成本问题。本工具是纯粹的自托管、零额外成本方案。

因此，它的定位非常清晰：一个为 OpenClaw 开发者/团队量身定做的、轻量级的、本地的用量审计与成本分析利器。

3. 环境准备与工具安装

3.1 前置条件检查

在开始之前，请确保你的系统满足以下条件：

  1. Python 环境 ：需要 Python 3.8 或更高版本。你可以通过 python3 --version 命令来验证。

  2. OpenClaw 环境与日志 ：你已经在本地运行过 OpenClaw 代理，并且产生了会话日志。通常日志会默认生成在 ~/.openclaw/agents/ 目录下。你可以通过 ls -la ~/.openclaw/agents/ 命令查看该目录是否存在以及是否有子目录和文件。

  3. uv 工具（推荐） ：这是项目推荐的包管理器和运行器。它的安装非常简单，且比传统虚拟环境更高效。如果你还没有安装，可以使用以下命令一键安装（适用于 Mac/Linux）：

    curl -LsSf https://astral.sh/uv/install.sh | sh

    安装完成后，重新打开终端或运行 source ~/.bashrc （或对应 shell 的配置文件）使 uv 命令生效。通过 uv --version 验证安装。

3.2 获取与安装 openclaw-model-usage

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

方式一：克隆仓库并本地运行（适合开发或深度使用）

这是最灵活的方式，你可以随时查看源码、运行测试或进行修改。

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

# 2. （可选但推荐）使用 uv 同步项目依赖
uv sync

完成这一步后，你就可以使用 uv run --project . openclaw-model-usage 来运行工具了。 uv sync 命令会创建一个独立的虚拟环境并安装所有 pyproject.toml 中声明的依赖。

方式二：直接运行捆绑的脚本（最快捷）

如果你不想处理依赖，或者只是想快速试一下，项目根目录下的 scripts/model_usage.py 是一个自包含的脚本（只要基础依赖满足，如 pandas 用于数据处理）。你可以直接运行它：

# 在克隆的仓库目录中
python3 scripts/model_usage.py --help

这种方式省去了依赖管理的步骤，但前提是你的全局 Python 环境已经安装了必要的库（如 pandas , rich 等）。如果运行报错提示缺少模块，你可能需要回到方式一使用 uv sync 。

实操心得：关于 uv 的优势 ：我强烈推荐使用 uv 。它不仅安装依赖的速度极快，而且其 --project . 参数能确保命令总是在项目正确的虚拟环境中执行，避免了全局 Python 环境混乱的问题。这对于同时维护多个 Python 项目的开发者来说是个福音。

3.3 验证安装与快速测试

安装完成后，运行帮助命令是验证一切是否正常的最佳方式：

# 使用 uv 运行（如果用了 uv sync）
uv run --project . openclaw-model-usage --help

# 或使用捆绑脚本
python3 scripts/model_usage.py --help

你应该能看到一个详细的命令行帮助信息，列出了所有可用的命令（ overview , top-agents , dashboard 等）和全局参数（如 --json , --root ）。

为了快速确认工具能正确读取你的日志，可以运行最基本的概览命令：

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

如果输出类似“No usage rows found in...”或显示了用量摘要，说明工具已经成功运行并读取了你的日志目录。

4. 核心命令详解与实战演示

工具提供了丰富的命令来满足不同场景下的查询需求。我们可以将其分为三大类： 人类友好视图 、 详细数据视图 和 报表输出 。

4.1 人类友好视图：快速获取洞察

这类命令的输出经过精心设计，力求在终端的一屏内呈现最有价值的信息，适合日常巡检和快速问答。

overview ：一站式总览 这是默认命令，也是信息密度最高的一个。运行 uv run --project . openclaw-model-usage overview ，你会得到一个类似这样的输出：

Usage overview — $0.0894, 24,150 tok, 47 calls
Agents 5 | Sessions 18 | Models 3
Current: openai/gpt-4o | data-analysis-bot | session-8f3a... | 2024-05-27 10:15:22

Top agents (by cost)
1. data-analysis-bot — $0.0561, 15,200 tok, 28 calls
2. customer-support-agent — $0.0210, 5,800 tok, 12 calls
3. code-review-helper — $0.0123, 3,150 tok, 7 calls

Top sessions (by cost)
1. session-8f3a... (data-analysis-bot) — $0.0320, 8,900 tok, 15 calls
2. session-bc7d... (customer-support-agent) — $0.0185, 5,100 tok, 10 calls
...

Top models (by cost)
1. openai/gpt-4o — $0.0780, 21,100 tok, 40 calls
2. openai/gpt-3.5-turbo — $0.0114, 3,050 tok, 7 calls

这个视图在几秒钟内告诉你：总花费、总Token、总调用次数；有多少个代理、会话和模型被涉及；当前哪个模型/代理/会话最活跃；以及按成本排名的顶级消费者。它是你每天打开终端第一个应该运行的命令。

top-agents 与 top-sessions ：聚焦核心消费者 当 overview 中的信息不足以满足深度分析时，这两个命令提供了更详细的排名列表。

  • top-agents ：专注于代理级别的聚合。它帮你回答“哪个代理最烧钱？”的问题。输出会列出每个代理的总成本、Token、调用次数以及它关联的会话数量。
  • top-sessions ：专注于会话级别的聚合。它帮你回答“哪个具体的任务或对话线程最耗资源？”的问题。如果元数据完整，它会显示会话的名称和父级关系，例如 “月度报告生成 | parent: 数据管道主会话” ，这比一个UUID直观得多。

current ：查看实时状态 这个命令显示最近一次模型调用的详细信息，包括使用的模型、所属代理和会话、以及调用的时间戳。在调试或监控一个正在长时间运行的代理时，这个命令能快速告诉你它“此刻”正在使用什么模型，对于排查意外的高消耗问题很有帮助。

4.2 详细数据与 JSON 输出：用于脚本集成

当你需要将数据导入其他系统（如 Grafana、内部监控），或者编写自动化脚本进行告警（例如“当日成本超过10美元时发送Slack通知”）时，就需要结构化的数据。这时，为任何命令加上 --json 标志即可。

# 获取 JSON 格式的概览数据，--pretty 使其更易读
uv run --project . openclaw-model-usage overview --json --pretty

# 获取所有会话的详细 JSON 数据
uv run --project . openclaw-model-usage sessions --json

# 获取指定会话 ID 的所有原始调用行
uv run --project . openclaw-model-usage rows --session-id YOUR_SESSION_UUID --json

JSON 输出包含了所有底层细节，如每个数据点的精确时间戳、完整的会话树结构、每次调用的输入/输出 Token 细分等。你可以用 jq 这样的命令行工具进一步过滤和处理这些 JSON 数据。

4.3 高级过滤与数据切片

工具支持多种过滤器，让你可以聚焦于特定的数据子集。

  • 时间过滤 ( --since-days , --until ) ：分析特定时间窗口的数据。例如， overview --since-days 7 只统计过去一周的用量，非常适合生成周报。
  • 代理/会话/模型过滤 ( --agent , --session-id , --model ) ：只查看特定实体的数据。这在分析某个特定代理或任务的表现时非常有用。
  • 渠道过滤 ( --channel ) ：如果你的 OpenClaw 代理通过不同渠道（如 Discord、CLI、Webhook）运行，可以用这个参数区分不同来源的用量。例如， top-sessions --channel discord 只看来自 Discord 交互的会话。

实战示例：生成过去3天Discord渠道的成本报告 

uv run --project . openclaw-model-usage overview \
  --channel discord \
  --since-days 3 \
  --json > discord_usage_last_3days.json

这个命令将过去3天所有通过 Discord 渠道产生的用量概览，以 JSON 格式保存到文件，便于后续分析。

5. 生成 HTML 仪表盘：可视化你的用量

命令行输出虽然强大，但视觉化报表更利于分享和呈现。 dashboard 命令就是这个功能的体现。

5.1 生成与查看仪表盘

运行以下命令，即可在本地生成一个独立的 HTML 报告：

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

默认情况下，报告会生成在项目根目录下的 dist/dashboard.html 文件中。你可以直接用浏览器打开这个文件： open dist/dashboard.html (Mac) 或 xdg-open dist/dashboard.html (Linux)。

这个 HTML 文件是 完全自包含的 ，它内嵌了所有 CSS 和 JavaScript，不需要网络连接。你可以把它通过邮件发送给同事，或者放在内部网盘中共享。

5.2 仪表盘内容解读

生成的仪表盘通常包含以下几个核心部分：

  1. 标题与汇总卡片 ：顶部醒目地显示总成本、总 Token、总调用次数、涉及的代理/会话/模型数量。让你对整体用量一目了然。
  2. 当前活动 ：显示最近一次模型调用的上下文，类似于 current 命令的增强版。
  3. Top 排行榜 ：以更美观的表格形式展示消耗最高的代理、会话和模型，通常带有简单的柱状图或颜色渐变来直观表示排名。
  4. 每日趋势图 ：一个简单的条形图，展示最近一段时间（例如过去30天）每天的成本变化趋势。这是发现用量异常波动（比如某天突然飙升）的最有效工具。
  5. 近期详细记录 ：一个可排序、可搜索的表格，列出了最近的模型调用记录，包含时间、模型、代理、会话、Token 数和估算成本。你可以在这里进行最细粒度的审查。

5.3 自定义仪表盘

你可以通过参数来自定义仪表盘的生成：

# 指定日志根目录（如果你的 OpenClaw 日志不在默认位置）
uv run --project . openclaw-model-usage dashboard --root /path/to/your/openclaw/logs

# 指定输出文件路径和标题
uv run --project . openclaw-model-usage dashboard \
  --out /tmp/my_weekly_report.html \
  --title "OpenClaw 团队周用量报告 (2024-05-27)"

# 结合过滤器生成特定视图
uv run --project . openclaw-model-usage dashboard \
  --channel cli \
  --since-days 30 \
  --out cli_monthly_dashboard.html

重要警告：区分测试与真实数据 ：项目根目录下有一个 tests/fixtures_root/ 目录，里面是用于自动化测试的模拟日志数据。 绝对不要 在正常使用时将 --root 指向这个目录，否则你生成的仪表盘将是基于假数据的样例，而不是你的真实用量！工具默认读取 ~/.openclaw/agents/ ，这才是正确的位置。

6. 作为 AgentSkill 集成到 OpenClaw

openclaw-model-usage 不仅仅是一个独立的 CLI 工具，它还可以作为一个 AgentSkill 被直接集成到你的 OpenClaw 代理中。这意味着你的 AI 代理本身就能理解和执行“检查用量”的指令。

6.1 技能集成原理

查看项目中的 SKILL.md 文件，里面包含了如何将该工具作为技能添加给你的代理的说明。核心步骤通常是在你的代理配置中，添加一个指向 scripts/model_usage.py 脚本的技能定义。这样，当用户在与代理对话时提出如“查看本周用了多少 Token？”或“哪个会话最耗钱？”的问题时，代理可以自动调用这个技能，执行相应的 openclaw-model-usage 命令，并将结果以自然语言的形式返回给用户。

6.2 技能使用场景示例

假设你有一个名为 DevOps-Bot 的 OpenClaw 代理，负责处理部署和监控任务。集成了此技能后，对话可能如下：

  • 用户 ：“@DevOps-Bot，我们上个季度在 AI 模型上花了多少钱？”
  • DevOps-Bot ：（调用 openclaw-model-usage overview --since-days 90 技能） “根据过去90天的日志分析，总支出约为 $124.50，共消耗 312,400 个 Token，涉及 540 次调用。成本最高的代理是 ci-code-review-agent ，消耗了 $67.80。需要我生成一份详细的 HTML 报告吗？”

这种集成将成本监控从被动的、离线的检查，变成了一个主动的、可对话的、嵌入到工作流中的能力，极大地提升了运维的便捷性和交互性。

7. 常见问题排查与实战技巧

在实际使用中，你可能会遇到一些问题。以下是一些常见情况的排查思路和解决技巧。

7.1 问题排查速查表

问题现象 可能原因 解决方案
运行命令报错 ModuleNotFoundError Python 依赖未安装。 确保在项目目录下运行了 uv sync 来安装依赖。如果使用脚本，确保全局环境有 pandas , rich 等包。
输出 “No usage rows found in...” 工具找不到日志文件，或日志目录为空。 1. 确认 OpenClaw 是否已运行并生成日志。检查 ~/.openclaw/agents/ 目录是否存在及是否有内容。
2. 使用 --root 参数指定正确的日志路径。
session-tree 命令显示很多“未知父级” 会话元数据文件 sessions.json 缺失或 spawnedBy 字段未记录。 这是数据源限制。确保使用的 OpenClaw 版本能正确生成会话索引。无法通过本工具修复。
dashboard 生成的 HTML 图表不显示 浏览器安全策略可能阻止加载本地文件中的某些资源。 生成的 HTML 是自包含的。尝试使用 python3 -m http.server 在 dist 目录父级启动一个本地服务器，然后通过 http://localhost:8000/dist/dashboard.html 访问。
成本计算为 0 或不准 工具依赖日志中的 Token 数和模型名称，根据内置单价估算成本。如果模型不在价格表中或单价为0，则成本为0。 查看 references/discovery.md 了解支持的成本计算模型。对于不支持的模型，成本显示为0。你可以考虑为工具贡献新的模型定价。
--since-days 过滤不生效 时间过滤是基于日志行中的时间戳。如果日志时间戳格式异常或为空，过滤可能失败。 检查原始 JSONL 文件，确认 created_at 等时间字段是否存在且格式正确（如 ISO 8601）。

7.2 实战技巧与心得

  1. 定期运行与归档 ：将 openclaw-model-usage overview --since-days 7 --json 的输出结果每周保存一次，可以建立历史基线，便于对比和发现异常趋势。你可以写一个简单的 cron 任务来自动化这个过程。
  2. 结合 jq 进行深度分析 ：JSON 输出和 jq 是绝配。例如，想找出所有单次调用消耗超过 10,000 Token 的“昂贵”记录，可以这样操作： 
    uv run --project . openclaw-model-usage rows --json | jq '[.[] | select(.usage.total_tokens > 10000)]'
  3. 为关键代理设置用量告警 ：虽然工具本身不提供告警，但你可以很容易地通过 shell 脚本实现。例如，每天检查 data-analysis-bot 的当日成本，如果超过 5 美元就发邮件： 
    #!/bin/bash
COST=$(uv run --project . openclaw-model-usage overview --agent data-analysis-bot --since-days 1 --json | jq '.total_cost_usd')
if (( $(echo "$COST > 5.0" | bc -l) )); then
    echo "警告: data-analysis-bot 今日成本已超5美元 ($$COST)" | mail -s "OpenClaw 成本告警" your-email@example.com
fi
  4. 理解“会话树”的威力 ：在分析复杂工作流时， session-tree 视图至关重要。它能帮你理解一个主任务（父会话）是如何派生出多个子任务（子会话）的，以及成本是如何在它们之间分布的。这对于优化具有递归或并行调用结构的代理逻辑非常有帮助。
  5. 开发与测试技巧 ：如果你想为工具贡献代码或测试新功能，请使用项目自带的测试夹具： python3 tests/smoke_test.py 。这个测试会使用 tests/fixtures_root/ 下的模拟数据，确保你的修改不会破坏核心功能。记住， 永远不要将生产环境的 --root 指向测试夹具目录 。

这个工具的精髓在于，它将散落在无数 JSONL 文件中的原始数据，变成了可操作的成本洞察。无论是通过命令行快速查询，还是生成可分享的 HTML 报告，或是集成到代理技能中实现对话式查询，它都以一种极简而强大的方式，填补了 OpenClaw 生态中用量监控的空白。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

原来AI、画图、导航都在用向量！

avatar 亚马逊云科技技术品牌专区
cover

害虫检测和识别3：基于深度学习YOLO26神经网络实现害虫检测和识别(含训练代码、数据集和GUI交互界面）

avatar 亚马逊云科技技术品牌专区
cover

大 硬 仗14小时：用2009年的上古亮机卡跑完深度学习，CPU满载但代码没崩

avatar 亚马逊云科技技术品牌专区