mcpField
H
heartbeat-governor

heartbeat-governor

github.com/archieindianエージェントワークフロー7358 回インストール26 週間前に更新
リポジトリ

heartbeat-governor について

Heartbeat Governor は、スケジュール実行されるスキルの累積コスト、実行時間、日次実行回数を監視します。設定した上限を超えると、スキルの一時停止や実行中止、記録、通知を行います。

主な機能

  1. 01直近 30 日間の実行コストを追跡
  2. 02実行時間と日次実行回数を監視
  3. 03スキルごとに予算上限を設定
  4. 04上限超過時に一時停止または中止
  5. 05状態と月次支出レポートを表示

活用シーン

  1. 01定期実行スキルの月間支出を制限
  2. 02予期しない請求や長時間実行を調査
  3. 03一時停止の理由を確認してスキルを再開

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/archieindian/openclaw-superpowers --skill heartbeat-governor

インストール後、Claude Code で/heartbeat-governorを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

example-state.yaml
governor.py
STATE_SCHEMA.yaml

詳細

ハートビートガバナー

機能

Cron スキルは自律的に実行されます。無限リトライ、予想外に大きなコンテキスト、ループ内のモデル呼び出しなどのバグがあるスキルは、気付かないうちに数百ドルを消費する可能性があります。

ハートビートガバナーは、スケジュールされたスキルごとに、累積実行コストと実行時間をローリング30日間で追跡します。スキルが予算を超えると、ガバナーはそのスキルを一時停止し、アラートを送信します。明示的に確認して再開するまで、そのスキルは再度実行されません。

予算超過を1回の cron サイクル内に検出できるよう、毎時実行されます。

呼び出すタイミング

  • 毎時、自動的に（cron）
  • API の請求額が予想外に急増したことに気付いたときに、手動で
  • cron スキルの実行時間が異常に長いとき

予算の種類

予算の種類デフォルト設定可能
max_usd_monthly$5.00はい、スキルごと
max_usd_per_run$0.50はい、スキルごと
max_wall_minutes30はい、スキルごと
max_runs_daily48はい、スキルごと

予算超過時のアクション

超過の種類アクション
monthly_usd 超過スキルを一時停止し、超過を記録してアラートを送信
per_run_usd 超過現在の実行を中止し、超過を記録
wall_clock 超過現在の実行を中止し、超過を記録
daily_runs 超過本日の残りの実行をスキップして記録

使用方法

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 のウェイクアップ動作

毎時、ガバナーが --check を実行します。

  1. state からすべてのスキルの台帳を読み込む
  2. paused: false の各スキルについて、以下を確認します。
    • ローリング30日間の支出が max_usd_monthly を超えている場合 → paused: true にして記録
    • 本日の実行回数が max_runs_daily を超えている場合 → スキップして記録
  3. 一時停止中のスキルと予算使用率の概要を出力
  4. 更新した state を保存

手順

ステップ 1 — 適切な予算を設定する

新しい cron スキルをインストールしたら、月間予算を設定します。

python3 governor.py --set-budget daily-review --monthly 2.00
python3 governor.py --set-budget morning-briefing --monthly 3.00

デフォルトは控えめな金額（$5/月）ですが、明示的に設定することをおすすめします。

ステップ 2 — 使用率を監視する

python3 governor.py --status

使用率の列を確認します。月間予算の80％を超えているスキルは、調査する必要があります。

ステップ 3 — 一時停止アラートに対応する

ガバナーがスキルを一時停止したら、予算を超えた原因を調査します。

  • 一時的にコストの高い実行（大きなコンテキスト）があったのでしょうか？
  • 高コストの呼び出しを繰り返すバグがあるのでしょうか？
  • 単に予算を引き上げる必要があるのでしょうか？

調査後に再開します。

python3 governor.py --resume <skill>

状態

スキルごとの台帳と一時停止フラグは ~/.openclaw/skill-state/heartbeat-governor/state.yaml に保存されます。

フィールド：skill_ledgers マップ、paused_skills リスト、breach_log、monthly_summary。

コメント

Markdown 対応