OpenClaw用量追踪（Usage Tracking）

OpenClaw 的用量追踪（Usage Tracking）功能，可实时监控 Agent 的 Token 消耗、API 调用次数及相关成本，帮助用户清晰掌握运营开支，同时支持设置预算限制，避免意外超支，为 Agent 运营提供精准的数据支撑。

一、Token 计数：精准记录每一次调用

OpenClaw 会在每次调用 LLM（大语言模型）时，精确记录 Token 的使用详情，其数据记录遵循统一的 UsageRecord 接口规范，具体包含以下核心信息：

interface UsageRecord {
timestamp: string // 调用时间戳
sessionKey: string // 会话唯一标识
model: string // 所使用的模型名称
provider: string // 模型提供商
tokens: {
input: number // 输入Token数量
output: number // 输出Token数量
total: number // Token总消耗
}
cost: {
input: number // 输入部分成本（单位：美元）
output: number // 输出部分成本（单位：美元）
total: number // 单次调用总成本（单位：美元）
}
latency: number // 接口响应延迟（单位：毫秒）
status: ‘success’ | ‘error’ | ‘failover’ // 调用状态
}

需要注意的是，Token 数据并非 OpenClaw 自行估算，而是直接取自 LLM 提供商接口响应头或响应体中的 usage 字段，确保每一条记录的准确性，避免因估算偏差导致成本统计失误。Token 作为模型处理文本的基本单位，不同模型的分词方式存在差异，计数规则也有所不同，实际消耗以模型返回结果为准。

二、成本跟踪：透明核算，清晰可控

OpenClaw 支持按模型配置定价规则，自动核算每一次调用的成本，目前已适配主流模型的定价标准，具体配置如下：

pricing:
openai/gpt-4o:
input: 2.50 # 每百万输入Token价格（美元）
output: 10.00 # 每百万输出Token价格（美元）

anthropic/claude-3-5-sonnet:
input: 3.00
output: 15.00

deepseek/deepseek-chat:
input: 0.14
output: 0.28

google/gemini-2.0-flash:
input: 0.10
output: 0.40

成本计算遵循固定公式，可精准核算单次调用的总成本：

单次调用成本 = （输入Token数 ÷ 1,000,000 × 输入单价） + （输出Token数 ÷ 1,000,000 × 输出单价）

举例说明：使用 GPT-4o 模型，输入2000个Token、输出500个Token，单次调用成本计算如下：

（2000 ÷ 1,000,000 × 2.50） + （500 ÷ 1,000,000 × 10.00） = 0.005 + 0.005 = 0.01美元

三、用量报告：多方式查询，多维度统计

1. 命令行查询

OpenClaw 提供便捷的命令行工具，可快速查询不同维度的用量数据，常用命令如下：

# 查看今日用量
openclaw usage today

# 查看本月用量
openclaw usage month

# 按Agent分类查看用量
openclaw usage –by agent

# 按渠道分类查看用量
openclaw usage –by channel

# 导出指定日期范围的用量数据（CSV格式）

openclaw usage export –format csv –from 2025-01-01 –to 2025-01-15

其中，查询今日用量的输出示例如下：

# 📊 Today’s Usage (2026-01-15)
# ─────────────────────────────────────────
# MODEL CALLS TOKENS COST
# openai/gpt-4o 45 234,567 $1.23
# deepseek/deepseek-chat 120 890,123 $0.15
# anthropic/claude-3-5 12 56,789 $0.48
# ─────────────────────────────────────────
# TOTAL 177 1,181,479 $1.86

2. 多维度聚合分析

用量数据支持按多种维度进行聚合统计，方便用户从不同视角掌握消耗情况，具体维度及说明如下：

四、预算告警：灵活管控，避免超支

1. 预算限制设置

用户可根据自身运营需求，设置每日和每月的预算上限，并指定预算达到后的执行动作，具体配置示例如下：

budget:
daily: 10.00 # 每日预算上限（单位：美元）
monthly: 200.00 # 每月预算上限（单位：美元）

action: warn # 预算达到后的执行动作
# warn — 发送告警通知，继续提供服务
# throttle — 自动降级到更便宜的模型
# stop — 停止Agent服务，避免继续超支

2. 告警通知配置

可设置多阈值告警，当预算消耗达到指定比例时，通过指定渠道发送告警通知，提醒用户关注用量情况。其中，紧急告警可配置网页通知，示例中的网页链接因解析失败无法正常访问，若需使用该告警渠道，请检查链接有效性或更换其他通知方式。具体配置如下：

budget:
alerts:
– threshold: 0.80 # 预算消耗达到80%时触发普通告警
notify:
– channel: telegram
user: admin
– threshold: 0.95 # 预算消耗达到95%时触发紧急告警
notify:
– channel: telegram
user: admin

3. 预算超限与自动降级

当预算配置的 action 为 stop 时，一旦用量达到预算上限，Agent 将停止响应所有消息，避免产生额外成本，建议用户合理设置预算并配置告警，及时掌握用量动态。

若希望在接近预算时避免服务中断，可设置自动降级功能，当预算消耗达到指定阈值时，自动切换到更便宜的模型（如 DeepSeek），具体配置如下：

budget:
daily: 10.00
action: throttle
throttleModel: deepseek/deepseek-chat # 降级后使用的模型
throttleThreshold: 0.85 # 预算消耗达到85%时开始降级

五、用量存储：本地持久化，数据可追溯

OpenClaw 的用量数据会持久化存储在本地文件系统中，便于用户随时追溯和查询，存储路径及结构如下：

~/.openclaw/usage/
├── 2025-01/
│ ├── 01.jsonl # 每日用量明细（JSONL格式）
│ ├── 02.jsonl
│ ├── …
│ └── summary.json # 月度用量汇总
├── 2025-02/
│ └── …
└── current.json # 当前用量统计缓存

其中，每日用量明细采用 JSONL 格式存储，每条记录对应一次 LLM 调用的用量信息，示例如下：

{“ts”:”2025-01-15T14:30:00Z”,”model”:”openai/gpt-4o”,”in”:2345,”out”:678,”cost”:0.0126,”session”:”general::user123″}

六、用量API：便捷查询，灵活集成

OpenClaw 提供 Gateway API 接口，用户可通过 API 便捷查询用量数据，支持查询今日用量和指定日期范围的用量，具体调用示例如下：

# 查询今日用量
curl http://localhost:18789/api/usage/today \
-H “Authorization: Bearer $TOKEN”

# 查询指定日期范围的用量（2025-01-01至2025-01-15）
curl “http://localhost:18789/api/usage?from=2025-01-01&to=2025-01-15” \
-H “Authorization: Bearer $TOKEN”

七、配置示例与中国用户须知

针对不同使用场景，提供以下配置示例，用户可根据自身需求调整：