核心功能与定位
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 侧硬限额或预付费机制，本工具仅作为事后监控与趋势分析手段。