从 OpenClaw/Clawdbot 会话 JSONL 日志精准追踪 token 消耗与真实成本，支持日/周汇总、TOP 高消费会话查询及预算超限告警，配套 token 节省策略 playbook 帮助降低 AI 调用开支。
说明：
## 核心功能与定位
OpenClaw Cost Guard 是一款面向开发者的成本监控工具，专注于从 OpenClaw/Clawdbot 的会话日志中提取真实 token 消耗与 USD 成本数据，解决“AI 调用费用不可见”的痛点。与基于上下文窗口估算的方案不同，它直接读取 `usage.cost` 等计费字段，确保数据准确性。
### 主要用法
– **周期性成本报告**：支持 `–today`、`–yesterday`、`–last-days 7/30` 等时间维度，输出文本或 JSON 格式便于集成到仪表板
– **高消费会话追踪**：`–top-sessions N` 快速定位成本黑洞，优化最昂贵的对话模式
– **预算硬约束**：`–budget-usd X` 配合退出码 2 实现自动化熔断，可接入 cron + Telegram/PagerDuty 等告警通道
– **成本回算**：当 provider 未返回真实 cost 时，支持通过环境变量注入 per-1M-token 单价进行估算
### 显著优点
1. **数据源真实可靠**：直接解析 JSONL 日志中的 `usage` 对象，而非推测性估算
2. **工程友好**：纯 Python 脚本，零依赖部署，JSON 输出便于 CI/CD 集成
3. **预算即代码**：退出码机制让成本 guardrail 可嵌入任意自动化流程
4. **附带优化指南**：内置 token-saving playbook，从响应长度、工具调用批量化、渐进披露等维度提供可落地的降本策略
### 局限性与风险
– **日志依赖**：若 OpenClaw 未持久化会话日志或格式变更，工具将失效
– **估算偏差**：fallback 模式基于固定单价，未考虑 tiered pricing 或动态折扣
– **安全实践待明**：技能文档提示“do not embed secrets in scripts”，但未提供 secret 管理的具体方案（如引用外部 vault）
– **单点故障**：cron 告警依赖本机任务调度，无内置高可用或重试机制
### 适合人群
– 使用 OpenClaw/Clawdbot 的个人开发者与小型团队
– 需要为 AI 调用建立成本可观测性的 SRE/FinOps 角色
– 希望通过轻量脚本而非 SaaS 方案实现预算管控的技术用户
### 常规风险提示
预算告警退出码 2 是**软性提醒**，非实时拦截——超支发生在告警之前。对于严格的成本控制，建议结合 provider 侧硬限额或预付费机制，本工具仅作为事后监控与趋势分析手段。
