openclaw-cost-guard

核心用法

OpenClaw Cost Guard 是一款专为 OpenClaw/Clawdbot 用户设计的成本追踪与预算管控工具。其核心工作流程是从本地 session JSONL 日志文件中提取真实的 token 使用量和 USD 成本数据，生成多维度的成本分析报告。

用户可通过命令行快速获取关键指标：使用 --last-days 7 查看近7日成本趋势，，--today 或 --yesterday 聚焦单日支出，，--top-sessions 10 识别最昂贵的会话记录。对于需要集成到数据看板的场景，，--json 参数可输出结构化数据。当日志中缺少实际成本字段时，工具支持通过环境变量配置各模型的 per-1M-token 价格进行估算回退。

预算管控是该工具的另一核心能力。通过 --budget-usd 参数设定日/周预算阈值，配合 --budget-mode 选择告警或强制退出模式（exit code 2），用户可轻松将成本监控接入 cron 定时任务或外部告警系统（如 Telegram Bot），实现自动化成本守护。

此外，工具内置了一套「Token-Saving Playbook」最佳实践，指导 AI 在响应长度、提问策略、工具调用批量化等方面优化，从源头降低 token 消耗。

显著优点

1. 数据真实可靠：直接读取 session 日志中的 usage.cost 字段，而非基于上下文窗口的估算，确保成本数据与实际账单一致。
2. 零侵入式设计：纯只读操作，不修改任何系统配置或日志文件，使用安全无负担。
3. 灵活的预算机制：支持硬阈值（exit code 2）与软告警两种模式，便于集成到各类自动化工作流。
4. 开源可审计：代码结构清晰、注释充分，所有逻辑透明可见，无隐藏行为。
5. 实用的节token指南：不仅监控成本，更提供可落地的优化策略，帮助用户建立长效的成本意识。

潜在缺点与局限性

1. 数据源依赖：仅能分析已生成的 session 日志，无法实时监控进行中的会话成本。
2. 价格配置门槛：当日志缺少成本字段时，用户需手动维护各模型的 token 单价，存在配置负担和误差风险。
3. 告警渠道缺失：工具本身仅通过退出码传递状态，需用户自行搭建外部通知渠道（如 Telegram、Slack）。
4. 平台局限性：专为 OpenClaw/Clawdbot 生态设计，无法直接适配其他 AI 平台或通用 OpenAI 兼容接口的日志格式。

适合的目标群体

• 高频 AI 用户：日均调用量大的开发者、研究员、内容创作者，需要精细化成本管控。
• 团队/企业管理员：负责多账号、多项目成本分摊与预算审批的运维或财务人员。
• 自动化爱好者：希望将成本监控纳入现有 DevOps 或 FinOps 工作流的技术用户。
• 成本敏感型用户：个人开发者或初创团队，需在有限预算内最大化 AI 工具价值。

使用风险

1. 日志解析性能：长期积累的大量 JSONL 文件可能导致分析耗时增加，建议定期归档历史日志。
2. 价格估算偏差：依赖环境变量回退时，若未及时更新模型价格，估算结果可能与实际账单存在差异。
3. 预算告警延迟：基于定时任务（cron）的监控存在最小执行间隔限制，无法做到秒级实时告警。
4. 环境变量冲突：PRICE_* 变量可能被系统中其他工具误读或覆盖，建议在独立 shell 会话或容器中运行。