Back to Details

heartbeat-governor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Heartbeat Governor

Heartbeat Governor

What it does

功能介绍

Cron skills run autonomously. A skill with a bug — an infinite retry, an unexpectedly large context, a model call inside a loop — can silently consume hundreds of dollars before you notice.
Heartbeat Governor tracks cumulative execution cost and wall-clock time per scheduled skill on a rolling 30-day basis. When a skill exceeds its budget, the governor pauses it and sends an alert. The skill won't fire again until you explicitly review and resume it.
It runs every hour to catch budget overruns within one cron cycle.
Cron skill会自动运行。存在bug的skill（比如无限重试、上下文意外过大、循环内调用模型）可能在你察觉之前就悄无声息地消耗掉数百美元。
Heartbeat Governor会以30天滚动周期为单位，追踪每个定时skill的累计执行成本和运行时长。当skill超出预算时，监管器会将其暂停并发送告警。在你明确审核并恢复它之前，该skill不会再次触发。
它每小时运行一次，可在一个cron周期内检测到预算超支情况。

When to invoke

触发场景

  • Automatically, every hour (cron)
  • Manually after noticing an unexpected API bill spike
  • When a cron skill has been running unusually long
  • 自动每小时触发（cron调度）
  • 发现API账单意外飙升后手动触发
  • 当某个cron skill运行时间异常过长时触发

Budget types

预算类型

Budget typeDefaultConfigurable
max_usd_monthly
$5.00Yes, per skill
max_usd_per_run
$0.50Yes, per skill
max_wall_minutes
30Yes, per skill
max_runs_daily
48Yes, per skill
预算类型默认值是否支持配置
max_usd_monthly
$5.00是，按skill配置
max_usd_per_run
$0.50是，按skill配置
max_wall_minutes
30是，按skill配置
max_runs_daily
48是，按skill配置

Actions on budget breach

预算超支处理动作

Breach typeAction
monthly_usd
exceeded		Pause skill, log breach, alert
per_run_usd
exceeded		Abort current run, log breach
wall_clock
exceeded		Abort current run, log breach
daily_runs
exceeded		Skip remaining runs today, log
超支类型处理动作
monthly_usd
超支		暂停skill、记录超支日志、发送告警
per_run_usd
超支		终止当前运行、记录超支日志
wall_clock
超支		终止当前运行、记录超支日志
daily_runs
超支		跳过当日剩余运行计划、记录日志

How to use

使用方法

bash
python3 governor.py --status               # Show all skills and budget utilisation
python3 governor.py --record <skill> --usd 0.12 --minutes 4   # Record a run
python3 governor.py --pause <skill>        # Manually pause a skill
python3 governor.py --resume <skill>       # Resume a paused skill after review
python3 governor.py --set-budget <skill> --monthly 10.00       # Override budget
python3 governor.py --check                # Run hourly check (called by cron)
python3 governor.py --report               # Full monthly spend report
python3 governor.py --format json
bash
python3 governor.py --status               # Show all skills and budget utilisation
python3 governor.py --record <skill> --usd 0.12 --minutes 4   # Record a run
python3 governor.py --pause <skill>        # Manually pause a skill
python3 governor.py --resume <skill>       # Resume a paused skill after review
python3 governor.py --set-budget <skill> --monthly 10.00       # Override budget
python3 governor.py --check                # Run hourly check (called by cron)
python3 governor.py --report               # Full monthly spend report
python3 governor.py --format json

Cron wakeup behaviour

Cron唤醒执行逻辑

Every hour the governor runs 
--check
:
  1. Load all skill ledgers from state
  2. For each skill with 
    paused: false
    :
    • If 30-day rolling spend exceeds 
      max_usd_monthly
      → 
      paused: true
      , log
    • If runs today exceed 
      max_runs_daily
      → skip, log
  3. Print summary of paused skills and budget utilisation
  4. Save updated state
每小时监管器会运行
--check
命令：
  1. 从状态文件中加载所有skill的台账
  2. 遍历所有
    paused: false
    （未暂停）的skill：
    • 如果30天滚动支出超出
      max_usd_monthly
      → 设为
      paused: true
      ，记录日志
    • 如果当日运行次数超出
      max_runs_daily
      → 跳过运行，记录日志
  3. 打印已暂停skill和预算使用情况的汇总信息
  4. 保存更新后的状态

Procedure

使用流程

Step 1 — Set sensible budgets
After installing any new cron skill, set its monthly budget:
bash
python3 governor.py --set-budget daily-review --monthly 2.00
python3 governor.py --set-budget morning-briefing --monthly 3.00
Defaults are conservative ($5/month) but explicit is better.
Step 2 — Monitor utilisation
bash
python3 governor.py --status
Review the utilisation column. Any skill above 80% monthly budget warrants investigation.
Step 3 — Respond to pause alerts
When the governor pauses a skill, investigate why it's over budget:
  • Was there a one-time expensive run (large context)?
  • Is there a bug causing repeated expensive calls?
  • Does the budget simply need to be raised?
Resume after investigating:
bash
python3 governor.py --resume <skill>
步骤1 — 设置合理预算
安装任何新的cron skill后，设置其月度预算：
bash
python3 governor.py --set-budget daily-review --monthly 2.00
python3 governor.py --set-budget morning-briefing --monthly 3.00
默认值比较保守（每月5美元），但显式设置总归更好。
步骤2 — 监控使用情况
bash
python3 governor.py --status
查看使用率列，任何月度预算使用率超过80%的skill都需要排查原因。
步骤3 — 响应暂停告警
当监管器暂停某个skill时，排查超支原因：
  • 是否是单次运行成本过高（上下文过大）？
  • 是否存在bug导致重复发起高成本调用？
  • 是否只是需要提高预算额度？
排查完成后恢复运行：
bash
python3 governor.py --resume <skill>

State

状态存储

Per-skill ledgers and pause flags stored in 
~/.openclaw/skill-state/heartbeat-governor/state.yaml
.
Fields: 
skill_ledgers
map, 
paused_skills
list, 
breach_log
, 
monthly_summary
.
单skill台账和暂停标记存储在
~/.openclaw/skill-state/heartbeat-governor/state.yaml
。
包含字段：
skill_ledgers
映射表、
paused_skills
列表、
breach_log
（超支日志）、
monthly_summary
（月度汇总）。