AI 调用成本精准追踪与预算守护 - OpenClaw Cost Guard (Budgets + Token-Saving Playbook)

从 OpenClaw/Clawdbot 会话 JSONL 日志精准追踪 token 消耗与真实成本，支持日/周汇总、TOP 高消费会话查询及预算超限告警，配套 token 节省策略 playbook 帮助降低 AI 调用开支。

基本信息

• 技能名称?OpenClaw Cost Guard (Budgets + Token-Saving Playbook)
• 中文名称?AI 调用成本精准追踪与预算守护
• 作者?dasweltall
• 分类?专业技能
• 版本?0.1.0
• 标签?cost-monitoring, budget-alert, openclaw, token-optimization, jsonl-parsing, cli-tool, finops, automation

使用方法

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