5.6 Token与成本

OpenClaw 追踪 token 使用情况和相关成本,帮助你优化 API 调用和控制费用。

Token 基础

什么是 Token?

• OpenClaw 追踪的是 tokens,不是字符数
• 英文平均约 4 个字符 = 1 个 token
• 中文、表情符号等通常每个字符占用更多 tokens
• Token 是 LLM API 计费的基本单位

Token 来源

系统提示词包含的 token 来源:

• 工具定义: 所有可用工具的 JSON Schema
• 技能列表: 技能文件路径 (完整内容通过 read 按需加载)
• 时间信息: 当前时间戳和时区
• Bootstrap 文件: AGENTS.md, SOUL.md, USER.md 等
• 元数据: 工作区路径、运行时信息等

上下文中的所有内容都计费

发送给 LLM 的所有内容都计入 token 使用量:

• 系统提示词
• 对话历史 (用户消息 + 助手回复)
• 附件 (图片、文件)
• 工具调用和结果
• 裁剪后的占位符 (如 [旧工具结果内容已清除])
• 提供商添加的隐藏包装器内容

成本计算

价格配置

成本从 models.providers..models[].cost 配置中估算:

{
  "models": {
    "providers": {
      "anthropic": {
        "models": [
          {
            "id": "claude-3-5-sonnet-20241022",
            "cost": {
              "input": 3.00,        // 每百万输入 tokens 的美元成本
              "output": 15.00,      // 每百万输出 tokens 的美元成本
              "cacheRead": 0.30,    // 每百万缓存读取 tokens 的成本
              "cacheWrite": 3.75    // 每百万缓存写入 tokens 的成本
            }
          }
        ]
      }
    }
  }
}

成本类型

• input: 发送给模型的新内容 (提示词、消息、工具结果)
• output: 模型生成的内容 (回复、推理)
• cacheRead: 从缓存读取的内容 (Anthropic 的 Prompt Caching)
• cacheWrite: 写入缓存的内容 (首次缓存或更新)

成本显示规则

• 缺失价格: 如果模型没有配置价格,只显示 token 数量,不显示美元成本
• OAuth 认证: 使用 OAuth 时隐藏美元成本,只显示 token 使用量
• API Key 认证: 使用 API Key 时显示完整的 token 和成本信息

查看 Token 和成本

/status 命令

在聊天中使用 /status 查看富文本摘要:

/status

显示内容包括:

• 📊 当前会话的 token 使用情况
• 💰 估算成本 (如果配置了价格)
• 📈 输入/输出/缓存读写的分项统计
• 🎯 上下文窗口使用率

/usage 命令

切换每次回复后的使用量脚注:

/usage         # 切换脚注显示
/usage on      # 开启脚注
/usage off     # 关闭脚注

脚注示例:

---
📊 Tokens: 12,543 in / 1,287 out / 8,234 cached
💰 Cost: $0.0523 (~¥0.38)

CLI 命令

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

# 查看详细的 token 分解
openclaw usage --detailed

# 查看成本汇总
openclaw cost --summary

优化策略

1. 使用压缩命令

/compact

压缩长时间对话,移除冗余内容,保留关键摘要。

2. 修剪工具输出

{
  "session": {
    "pruning": {
      "mode": "cache-ttl",
      "ttl": "5m",
      "softTrimRatio": 0.3
    }
  }
}

自动修剪旧的工具结果,减少上下文大小。

3. 精简技能描述

• 保持技能文件标题简短清晰
• 在系统提示词中只列出路径,模型按需加载完整内容
• 避免在技能文件中包含大量示例代码

4. 使用更小的模型

{
  "agents": {
    "helper-agent": {
      "model": "claude-3-5-haiku-20241022"  // 更便宜的模型
    }
  }
}

对于简单任务,使用更小、更便宜的模型。

5. 启用缓存 TTL 裁剪

缓存 TTL 裁剪可以:

• 在缓存过期后重置缓存,减少 cacheWrite 成本
• 保持缓存内容新鲜,提高缓存命中率
• 配合心跳机制保持缓存温暖

{
  "session": {
    "pruning": {
      "mode": "cache-ttl",
      "ttl": "5m"
    }
  },
  "heartbeat": {
    "interval": "55m"  // 对于 1 小时 TTL,在 55 分钟时发送心跳
  }
}

6. 监控和调整

• 定期检查 /status 了解 token 使用趋势
• 识别高 token 消耗的工具或操作
• 调整裁剪阈值和 TTL 设置
• 优化 Bootstrap 文件大小

Anthropic 缓存机制

缓存优势

• cacheRead 比 input 便宜约 10 倍
• 系统提示词和长对话历史可以被缓存
• 缓存命中率越高,成本越低

缓存成本

• cacheWrite 比 input 略贵 (约 1.25 倍)
• 首次写入或 TTL 过期后重写需要 cacheWrite 成本
• 频繁更新缓存会增加成本

优化建议

成本估算示例

场景1: 短对话 (无缓存)

Input tokens:  2,000  × $3.00  / 1M = $0.006
Output tokens:   500  × $15.00 / 1M = $0.0075
Total:                               $0.0135

场景2: 长对话 (有缓存)

Input tokens:     1,000  × $3.00  / 1M = $0.003
Cache read:      25,000  × $0.30  / 1M = $0.0075
Output tokens:    1,200  × $15.00 / 1M = $0.018
Total:                                   $0.0285

# 如果没有缓存,成本会是:
Input tokens:    26,000  × $3.00  / 1M = $0.078
Output tokens:    1,200  × $15.00 / 1M = $0.018
Total without cache:                     $0.096

# 节省: $0.096 - $0.0285 = $0.0675 (约 70%)

场景3: 缓存写入

Cache write:     20,000  × $3.75  / 1M = $0.075
Input tokens:     1,000  × $3.00  / 1M = $0.003
Output tokens:      500  × $15.00 / 1M = $0.0075
Total:                                   $0.0855

# 后续请求只需 cacheRead,成本大幅降低

常用命令速查

# 实时查看 token 和成本
/status

# 切换使用量脚注
/usage

# 压缩对话以减少 token
/compact

# CLI 查看详细统计
openclaw status --usage
openclaw cost --summary

# 检查上下文使用情况
/context list

最佳实践

相关概念

• 上下文管理: 理解上下文窗口和内容组织
• 会话裁剪: 自动优化上下文大小
• 压缩机制: 手动压缩对话历史
• 系统提示词: 系统提示词的 token 占用