heartbeat-governor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 type	Default	Configurable
`max_usd_monthly`	$5.00	Yes, per skill
`max_usd_per_run`	$0.50	Yes, per skill
`max_wall_minutes`	30	Yes, per skill
`max_runs_daily`	48	Yes, 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 type	Action
`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

Load all skill ledgers from state
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
Print summary of paused skills and budget utilisation
Save updated state

每小时监管器会运行

--check

命令：

从状态文件中加载所有skill的台账
遍历所有
```
paused: false
```
（未暂停）的skill：
- 如果30天滚动支出超出
```
max_usd_monthly
```
  → 设为
```
paused: true
```
  ，记录日志
- 如果当日运行次数超出
```
max_runs_daily
```
  → 跳过运行，记录日志
打印已暂停skill和预算使用情况的汇总信息
保存更新后的状态

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

（月度汇总）。