使用手册 · 洞察

成本追踪

监控、分析和优化你的 OpenClaw Agent 运营成本。

/cost

概述#

成本追踪提供按 Agent 的成本归因，支持按模型、任务类型和时间段的分解。数据从 OpenClaw 网关的会话日志中自动同步。

功能包括 7 天趋势可视化、速率异常告警（当小时成本超过日均 3 倍时触发）、以及多实例分组（适用于运行多个 OpenClaw 网关的组织）。

前置条件#

前置条件
  • 至少同步了一个有 Agent 的连接器
  • Agent 正在活跃运行任务（产生成本数据）
  • 成本同步间隔已配置（连接器自动处理）

OpenClaw 侧配置#

OpenClaw 在会话日志文件中存储每次调用的成本数据。每条助手消息包含来自模型提供商的实际 USD 成本。

会话日志存储路径：

text
~/.openclaw/agents/{agentId}/sessions/*.jsonl

每个 JSONL 条目包含 message.usage.cost.total —— 来自提供商的实际 USD 成本。

提示
重要：ClawButler 使用 sessions.usage RPC 方法读取成本数据。该方法扫描所有 Agent 目录并返回按 Agent 的成本分解。旧的 usage.cost 方法仅读取 'main' Agent，不被使用。

ClawButler 侧配置#

连接器活跃时，成本数据会自动同步。无需手动配置。

对于基于日期的查询，ClawButler 使用 COALESCE(period_start, created_at)——其中 period_start 保存 OpenClaw 的实际成本日期，created_at 是同步时间戳。

使用反馈#

成本页面显示四个部分：

  • -统计行：今日成本、本周总计、本月预估（周费用 × 4.3）和活跃告警数量
  • -速率异常告警：小时成本超过日均 3 倍时显示橙色横幅
  • -7 天成本趋势：按日显示的柱状图，高度自适应归一化
  • -分解表格：按 Agent 和按任务类型分组的成本，带水平进度条

多实例：连接多个 OpenClaw 网关时，成本按连接器名称分组。顶部出现总计行，显示所有实例的汇总成本。

Web 端操作#

在侧边栏的「洞察」分区中点击「成本追踪」进入页面。

  • -顶部统计行可快速查看成本概览
  • -向下滚动查看趋势图和分解表格
  • -触发速率异常时，告警横幅出现在统计和趋势之间
  • -数据自动刷新，无需手动操作

CLI 端操作#

显示成本摘要（可选日期范围）

Terminal
$ ap cost summary --date-from 2024-01-01 --date-to 2024-01-31

按 Agent 分组显示成本

Terminal
$ ap cost by-agent

按模型分组显示成本

Terminal
$ ap cost by-model

按任务类型分组显示成本

Terminal
$ ap cost by-task-type

显示成本趋势（按日/周/月）

Terminal
$ ap cost trend --granularity week

检查成本数据新鲜度

Terminal
$ ap cost freshness

移动端操作#

在移动端，成本数据在「洞察」标签页（第三个标签）中。选择顶部的「成本」分段。

  • -按 Agent / 按模型 / 按类型切换标签查看不同视图
  • -迷你折线图显示成本趋势
  • -水平柱状图显示分解视图
  • -下拉刷新更新数据

常见问题#

问：某些 Agent 的成本数据缺失或显示 $0。
答：确保 Agent 已活跃处理过请求（成本数据来自会话日志）。用 'ap cost freshness' 检查数据新鲜度——如数据过时，请验证连接器是否正常同步。
问：月度预估为什么看起来不准确？
答：月度预估将当周总计乘以 4.3。这是一个粗略估算——实际成本取决于每周可能不同的使用模式。
问：成本数据多久同步一次？
答：成本数据通过连接器的 WebSocket 隧道自动同步。新的成本记录在 OpenClaw 中产生后数秒内即可显示。
成本追踪 — ClawButler 用户手册