Agent Budget Governance

Trust-based budget system for multi-agent teams — daily token limits with automatic midnight resets, yellow/red/demotion thresholds, audit logging, and mesh...

Security Scan

The documentation and governance prose claim stronger enforcement (editing openclaw.json, different JSON schema) than the included script actually does — the code only reads/writes local BUDGET.json files and a governance log, which is internally inconsistent and deserves caution.

Purpose & Capability

Name/description promise: a trust-based budget system that can demote agents by removing mesh spawn rights (editing openclaw.json). What’s delivered: a Python audit script that reads/writes per-agent BUDGET.json files and appends to a governance log. The script does NOT modify openclaw.json or gateway policies. Also the SKILL.md and references show different BUDGET.json field names than the script expects (documentation uses fields like daily_limit/used_today while the code expects daily_limit_output_tokens/used_output_tokens), which is an incoherence.

Instruction Scope

SKILL.md instructs running the audit and describes demotion removing subagents.allowAgents in openclaw.json; the runtime script only resets counters, logs warnings/demotions to its governance log, and updates BUDGET.json. There is no code to enforce spawn-blocking at the gateway or to modify openclaw.json — the instructions overstate enforcement scope.

Install Mechanism

No install spec (instruction-only) and only requires python3 on PATH. No external downloads or archive extraction. Low install risk.

Credentials

No environment variables or external credentials are requested. The script operates on a hard-coded local path (~/.openclaw/workspace/agents) which is proportional to a local governance tool, but the hard-coded path and AGENT_MAP may not match every user's layout and could cause it to silently ignore or overwrite files.

Persistence & Privilege

always:false and no network access are good. The script persists changes to per-agent BUDGET.json and governance/log.jsonl (expected for a budget auditor). However, the documentation claims changes to openclaw.json for demotion — if a user expects automatic mesh-revocation, that will not happen with the provided script. No indication the skill modifies other skills' config files or gains elevated privileges.

What to consider before installing

This skill contains useful local audit code, but the documentation and governance docs over-claim its enforcement capabilities. Before installing or running: 1) Inspect and test the script in a safe environment (backup ~/.openclaw/workspace/agents). 2) Note schema mismatch: ensure your existing BUDGET.json uses the fields the script expects (daily_limit_output_tokens, used_output_tokens, consecutive_overbudget_days, status, warnings, spawns) or update the script or files accordingly. 3) If you expect automatic spawn-blocking/demotion at the gateway (modifying openclaw.json or session spawn middleware), know that the provided script does not perform those changes — additional enforcement code or gateway middleware is required. 4) Run the script with --json or --reset-only in a sandbox to observe behavior and confirm it only updates local files. 5) If you plan to rely on demotion for security/cost control, implement or review the separate mechanism that enforces spawn restrictions (and audit it). 6) Because the AGENTS_DIR is hard-coded, confirm it matches your installation or modify the script to point to the correct workspace path. If you want me to, I can produce a short patch to (a) align the code with the SKILL.md demotion claim (e.g., safely modify openclaw.json with backups) or (b) make the script accept a configurable agents directory and schema mapping.

Prevent runaway API spending in multi-agent systems. Each agent gets a daily output token budget. Exceed it and you get warnings. Keep exceeding it and you lose mesh spawn privileges.

How It Works

Agent completes task → tokens logged to BUDGET.json
                          ↓
Heartbeat runs budget_audit.py
                          ↓
├── Under 80%: ✅ Green — business as usual
├── 80-100%: 🟡 Yellow — warning logged
├── 100-200%: 🔴 Red — alert to orchestrator
└── 200%+ or 3 consecutive days over: ⛔ Demotion — mesh privileges revoked

Budget File Format

Each agent has agents/<name>/BUDGET.json:

{
  "daily_limit": 50000,
  "today": "2026-03-01",
  "used_today": 23450,
  "consecutive_over_days": 0,
  "demoted": false
}

Running the Audit

python3 scripts/budget_audit.py          # Full audit with alerts
python3 scripts/budget_audit.py --json   # Machine-readable output
python3 scripts/budget_audit.py --reset-only  # Just reset daily counters

Governance Rules

1. Daily reset at midnight (configurable timezone)
2. Yellow at 80% — logged, no action
3. Red at 100% — logged, orchestrator alerted
4. Demotion at 200% OR 3 consecutive days over budget
5. Rehabilitation — demoted agent must go 7 clean days, then orchestrator manually restores privileges

Demotion Mechanics

Demotion removes an agent's subagents.allowAgents list in openclaw.json, preventing them from spawning other agents. They can still be spawned by the orchestrator.

Files

• scripts/budget_audit.py — Audit script (run from heartbeat or cron)
• references/GOVERNANCE.md — Full governance framework documentation