OpenClaw Cost Guard (Budgets + Token-Saving Playbook)

核心功能与定位

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

核心用法

OpenClaw Cost Guard 是一款专注于 AI 代理会话成本追踪的轻量级工具，通过解析本地 JSONL 日志文件（~/.openclaw/agents/*/sessions/*.jsonl 或兼容的 ~/.clawdbot 路径），提取真实的 usage.cost 字段生成精确报告。

主要功能模块：

• 多维度报表：支持 --last-days 7、--today、--yesterday 时间窗口，以及 --top-sessions 10 高消费会话排行
• JSON 输出：--json 标志可对接外部仪表盘系统
• 预算守卫：--budget-usd 5 配合退出码 2 实现 cron/告警集成，--budget-mode warn 提供非中断式提醒
• 价格回退：当日志缺失成本字段时，可通过环境变量 PRICE_INPUT、PRICE_OUTPUT、PRICE_CACHE_READ、PRICE_CACHE_WRITE 手动配置模型定价进行估算

Token 节省策略（AI 行为优化）：

• 强制 1–6 行简洁回复，优先使用 bullet 而非段落
• 单次任务最多 1 个澄清问题，采用渐进式披露原则
• 工具调用批量化，禁止重复状态查询
• 日志内容禁止直接贴入对话，改为摘要+文件路径指引
• 硬性限制：单次任务最多 3 次网络迭代（搜索/抓取）

显著优点

1. 极致安全：零第三方依赖，纯 Python 标准库实现（argparse/dataclasses/datetime/glob/json/os/sys/collections），彻底规避供应链攻击风险
2. 隐私优先：所有数据处理本地完成，零网络请求、零外部 API 调用，符合 GDPR 数据最小化原则
3. 可信来源：BSS 平台发布，安全评级 S（95分），静态与动态分析双通过，无危险函数、无动态代码执行、无敏感信息硬编码
4. 运维友好：退出码设计便于 CI/cron 集成，轻量 442 行代码易于审计和定制

潜在局限

• 数据完整性依赖：成本准确性取决于 OpenClaw/Clawdbot 是否在日志中写入 usage.cost 字段，部分第三方模型提供商可能缺失该数据
• 手动定价门槛：回退估算模式需要用户自行配置模型价格参数，对非技术用户不够友好
• 平台锁定：日志路径硬编码为 OpenClaw/Clawdbot 目录结构，其他 AI 代理框架需手动适配
• 功能单一：专注成本统计，不提供实时拦截或自动降配等主动成本控制功能

适合人群

• 使用 OpenClaw/Clawdbot 的个人开发者或小团队，需要精细化成本监控
• 有 cron/告警自动化需求的运维人员
• 对供应链安全和数据隐私高度敏感的用户
• 希望优化 AI 交互 Token 消耗、降低 API 账单的技术团队

常规风险

• 日志误读风险：若本地日志文件被损坏或篡改，可能导致成本计算偏差（虽代码已处理 JSON 解析异常）
• 预算告警延迟：基于事后日志分析，非实时流式拦截，大额超支可能在告警触发前已发生
• 环境变量泄露：PRICE_* 定价配置以明文环境变量存在，共享环境可能暴露商业敏感信息
• T3 来源限制：个人开发者账号发布，虽当前版本安全，但长期维护承诺和更新频率存在不确定性