5.28 使用量追踪

核心概念核心概念

OpenClaw 的使用量追踪功能直接从提供商的 API 端点拉取实际使用数据,而非依赖估算。

核心特性

  • 真实数据: 直接从提供商 API 获取,非估算值
  • 多提供商支持: 支持多个 LLM 和服务提供商
  • 多入口展示: 在命令、CLI、GUI 等多处显示
  • 权限控制: 只在有匹配的 OAuth/API 凭证时显示

支持的提供商

Anthropic

追踪 Claude 模型的使用量和成本。

  • Token 使用量 (input/output/cacheRead/cacheWrite)
  • API 调用次数
  • 成本估算 (基于官方定价)

GitHub Copilot

追踪 GitHub Copilot API 的使用情况。

  • 请求数量
  • Token 使用量
  • 模型调用统计

Gemini CLI

追踪 Google Gemini 模型的使用。

  • API 调用次数
  • Token 消耗
  • 费用追踪

Antigravity

专有提供商的使用量追踪。

OpenAI Codex (OAuth)

通过 OAuth 认证的 OpenAI Codex 使用量。

  • Token 使用量
  • 模型调用统计
  • 成本追踪

MiniMax (API Key)

通过 API Key 认证的 MiniMax 模型使用量。

z.ai

z.ai 平台的使用量追踪。

查看使用量

聊天中查看

/status 命令

/status

显示当前会话的使用量摘要:

  • 📊 Token 使用统计
  • 💰 成本估算
  • 📈 提供商使用分布
  • 🕐 时间范围

/usage 命令

/usage         # 显示使用量摘要
/usage cost    # 显示本地成本汇总 (聚合所有聊天)

功能:

  • 切换每次回复后的使用量脚注
  • 查看跨会话的成本汇总
  • 按提供商分组的统计

CLI 查看

# 查看使用量统计
openclaw status --usage

# 详细的使用量分解
openclaw usage --detailed

# 按提供商查看
openclaw usage --by-provider

# 按时间范围查看
openclaw usage --since "2026-01-01" --until "2026-01-31"

# 导出使用量数据
openclaw usage --export usage-report.json

macOS 菜单栏

macOS 用户可以在菜单栏中直接查看实时使用量:

  • 点击菜单栏图标
  • 查看今日/本周/本月使用量
  • 快速访问详细统计

配置示例

启用使用量追踪

{
  "usageTracking": {
    "enabled": true,
    "providers": {
      "anthropic": {
        "enabled": true,
        "refreshInterval": "5m"  // 每5分钟刷新一次
      },
      "github": {
        "enabled": true,
        "refreshInterval": "10m"
      }
    }
  }
}

自定义显示

{
  "usageTracking": {
    "display": {
      "showInStatus": true,       // 在 /status 中显示
      "showFooter": false,        // 默认不显示回复脚注
      "showInMenuBar": true,      // macOS 菜单栏显示
      "currencyFormat": "USD",    // 货币格式
      "tokenPrecision": 0         // Token 显示精度 (整数)
    }
  }
}

设置阈值提醒

{
  "usageTracking": {
    "alerts": {
      "enabled": true,
      "thresholds": {
        "dailyCost": 10.00,       // 每日成本超过 $10 时提醒
        "monthlyCost": 200.00,    // 每月成本超过 $200 时提醒
        "dailyTokens": 1000000    // 每日 token 超过 100 万时提醒
      },
      "notificationMethod": "system"  // system | chat | both
    }
  }
}

权限与隐私

凭证要求

使用量追踪需要相应的认证凭证:

  • OAuth: 使用 OAuth 认证时,会自动拉取使用量数据
  • API Key: 使用 API Key 时,需要 API Key 具有读取使用量的权限
  • 无凭证: 如果没有匹配的凭证,使用量信息将被隐藏

数据隐私

隐私说明
使用量数据仅存储在本地,不会发送到 OpenClaw 服务器。数据直接从提供商 API 获取,并缓存在本地以提高性能。

使用场景

场景1: 成本监控

# 查看本月成本
openclaw usage --this-month

# 输出示例:
📊 Usage Summary (February 2026)
─────────────────────────────────
Provider: Anthropic
  Calls:     342
  Input:     5,234,123 tokens
  Output:    987,456 tokens
  Cache:     12,345,678 tokens (read)
  Cost:      $48.23

Provider: GitHub Copilot
  Calls:     89
  Tokens:    1,234,567
  Cost:      $0.00 (included in subscription)

Total Cost: $48.23

场景2: 优化建议

# 查看详细分解,识别高消耗区域
openclaw usage --detailed --sort-by cost

# 输出示例:
Top 5 Cost Contributors:
1. Session: main-chat-456     $12.34 (25.6%)
2. Session: analysis-789      $8.90  (18.5%)
3. Session: cron-daily-report $6.78  (14.1%)
...

场景3: 跨团队计费

# 按代理分组查看使用量
openclaw usage --by-agent

# 输出示例:
Agent Usage Breakdown:
─────────────────────────────────
Agent: main-assistant
  Cost: $32.10
  Tokens: 8,234,567

Agent: code-reviewer
  Cost: $16.13
  Tokens: 4,123,456
...

最佳实践

优化建议
  • 定期检查: 每周查看一次使用量趋势,及时发现异常
  • 设置阈值: 配置成本提醒,避免意外超支
  • 按需刷新: 根据实际需求调整刷新频率,避免过度 API 调用
  • 导出报告: 定期导出使用量数据用于分析和归档
  • 分配预算: 为不同代理或项目设置使用量预算

故障排除

使用量不显示

可能的原因和解决方法:

  1. 缺少凭证: 确保已配置相应的 OAuth 或 API Key
  2. 权限不足: API Key 需要具有读取使用量的权限
  3. 刷新延迟: 使用量数据有缓存,等待刷新间隔后重试
  4. 提供商限制: 某些提供商可能不支持使用量 API
# 手动刷新使用量数据
openclaw usage --refresh

# 检查凭证状态
openclaw auth status

# 查看错误日志
openclaw logs --filter usage-tracking

成本不准确

成本估算可能与实际账单略有差异:

  • 价格更新: 定期更新配置中的模型价格
  • 批量折扣: 实际账单可能包含折扣,估算值不包含
  • 汇率变化: 如果使用非美元货币,汇率波动会影响最终金额
# 更新模型价格
openclaw config set models.providers.anthropic.models.0.cost.input 3.00

API 集成

开发者可以通过 API 访问使用量数据:

// Node.js 示例
const openclaw = require('@openclaw/openclaw');

// 获取使用量摘要
const usage = await openclaw.usage.getSummary({
  since: '2026-02-01',
  until: '2026-02-28',
  groupBy: 'provider'
});

console.log(usage);
// {
//   anthropic: { tokens: 10234567, cost: 48.23 },
//   github: { tokens: 1234567, cost: 0 }
// }

// 获取详细使用量
const detailed = await openclaw.usage.getDetailed({
  provider: 'anthropic',
  includeSessionBreakdown: true
});

// 导出报告
await openclaw.usage.exportReport({
  format: 'json',
  outputPath: './usage-report.json'
});

常用命令速查

# 查看当前使用量
/status
/usage

# 查看成本汇总
/usage cost

# CLI 详细统计
openclaw status --usage
openclaw usage --detailed

# 按提供商分组
openclaw usage --by-provider

# 按时间范围
openclaw usage --this-week
openclaw usage --this-month
openclaw usage --since "2026-01-01"

# 导出报告
openclaw usage --export report.json

# 手动刷新
openclaw usage --refresh

相关概念