用量追踪
Usage Tracking（用量追踪）监控 Agent 的 Token 消耗、API 调用次数和成本，帮助你了解运营开支并设置预算限制。
Token 计数
OpenClaw 在每次 LLM 调用中精确记录 Token 使用量：
typescript
interface UsageRecord {
timestamp: string // 调用时间
sessionKey: string // 会话键
model: string // 使用的模型
provider: string // 提供商
tokens: {
input: number // 输入 Token 数
output: number // 输出 Token 数
total: number // 总 Token 数
}
cost: {
input: number // 输入成本（USD）
output: number // 输出成本（USD）
total: number // 总成本（USD）
}
latency: number // 响应延迟（毫秒）
status: 'success' | 'error' | 'failover'
}Token 来源
Token 数据来自 LLM Provider 的响应头或响应体中的 usage 字段。OpenClaw 不自行估算，确保数据准确。
成本跟踪
每个模型的定价配置：
yaml
pricing:
openai/gpt-4o:
input: 2.50 # 每百万 Input Token 的价格（USD）
output: 10.00 # 每百万 Output Token 的价格（USD）
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成本计算：
单次调用成本 = (input_tokens / 1,000,000 × input_price)
+ (output_tokens / 1,000,000 × output_price)
示例（GPT-4o, 2000 input + 500 output tokens）：
= (2000 / 1M × $2.50) + (500 / 1M × $10.00)
= $0.005 + $0.005
= $0.01用量报告
命令行报告
bash
# 查看今日用量
openclaw usage today
# 输出：
# 📊 Today's Usage (2025-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.86bash
# 查看本月用量
openclaw usage month
# 查看按 Agent 分类的用量
openclaw usage --by agent
# 查看按渠道分类的用量
openclaw usage --by channel
# 导出用量数据
openclaw usage export --format csv --from 2025-01-01 --to 2025-01-15按维度统计
用量可按多种维度聚合分析：
| 维度 | 说明 |
|---|---|
| 模型 | 每个模型的 Token 和成本 |
| Agent | 每个 Agent 的消耗 |
| 渠道 | 每个渠道的消耗 |
| 用户 | 每个用户的消耗 |
| 时间 | 按小时/天/周/月的趋势 |
预算告警
预算限制
设置成本预算，防止意外超支：
yaml
budget:
daily: 10.00 # 每日预算上限（USD）
monthly: 200.00 # 每月预算上限（USD）
action: warn # 达到预算时的动作
# warn — 发送告警通知，继续服务
# throttle — 降级到更便宜的模型
# stop — 停止 Agent 服务告警通知
yaml
budget:
alerts:
- threshold: 0.80 # 消耗 80% 预算时告警
notify:
- channel: telegram
user: admin
- threshold: 0.95 # 消耗 95% 预算时紧急告警
notify:
- channel: telegram
user: admin
- webhook: https://hooks.example.com/alert预算超限
当 action: stop 时，达到预算上限后 Agent 将停止响应所有消息。请确保设置了合理的预算并配置告警。
自动降级
当接近预算时自动切换到更便宜的模型：
yaml
budget:
daily: 10.00
action: throttle
throttleModel: deepseek/deepseek-chat # 降级后使用的模型
throttleThreshold: 0.85 # 85% 时开始降级用量存储
用量数据持久化在本地文件系统：
~/.openclaw/usage/
├── 2025-01/
│ ├── 01.jsonl # 每日用量明细
│ ├── 02.jsonl
│ ├── ...
│ └── summary.json # 月度汇总
├── 2025-02/
│ └── ...
└── current.json # 当前统计缓存每条记录为 JSONL 格式：
json
{"ts":"2025-01-15T14:30:00Z","model":"openai/gpt-4o","in":2345,"out":678,"cost":0.0126,"session":"general::user123"}用量 API
通过 Gateway API 查询用量数据：
bash
# 查询今日用量
curl http://localhost:18789/api/usage/today \
-H "Authorization: Bearer $TOKEN"
# 查询指定日期范围
curl "http://localhost:18789/api/usage?from=2025-01-01&to=2025-01-15" \
-H "Authorization: Bearer $TOKEN"配置示例
yaml
budget:
daily: 5.00
monthly: 50.00
action: warn
alerts:
- threshold: 0.90
notify:
- channel: telegram
user: selfyaml
budget:
daily: 50.00
monthly: 1000.00
action: throttle
throttleModel: deepseek/deepseek-chat
throttleThreshold: 0.80
alerts:
- threshold: 0.70
notify:
- webhook: https://slack.example.com/hook
- threshold: 0.95
notify:
- webhook: https://pagerduty.example.com/alertyaml
budget:
daily: 2.00
monthly: 30.00
action: stop
alerts:
- threshold: 0.50
notify:
- channel: telegram
user: admin🇨🇳 中国用户须知
- 国产模型的定价通常远低于国际模型，使用 DeepSeek 等可大幅降低成本
- 预算建议以人民币计算后转换为 USD 配置
- 国产模型的 Token 计数方式可能与 OpenAI 不同，注意对比实际消耗
参考成本对比（每百万 Token）：
| 模型 | Input 价格 | Output 价格 |
|---|---|---|
| GPT-4o | $2.50 | $10.00 |
| Claude 3.5 Sonnet | $3.00 | $15.00 |
| DeepSeek Chat | $0.14 | $0.28 |
| Gemini 2.0 Flash | $0.10 | $0.40 |