Most agents have no built-in spend controls, so token usage can quietly spike or run away in the background. Revenium for OpenClaw adds real-time budget guardrails so you can ship agents with hard limits and get alerted before costs exceed what you intended.
By John D'Emic · Revenium Engineering
Revenium for OpenClaw
Starting today, you can install real-time budget guardrails into any OpenClaw agent:
clawhub install --force --dir ~/.openclaw/skills reveniumbash ~/.openclaw/skills/revenium/scripts/post-install.shRestart the OpenClaw gateway, then start an agent session.
On first run, it walks you through an interactive setup to configure your credentials and budget, asking for:
- Revenium API key, Team ID, Tenant ID, and User ID
- An optional organization name (for attribution in Revenium reporting)
- Budget amount and period (daily / weekly / monthly / quarterly)
- Whether the agent runs autonomously, and if so, which notification channel (Slack, Discord, Telegram, WhatsApp, Signal, Google Chat, MS Teams, Mattermost, or iMessage) should receive budget alerts
After that, every agent run becomes budget-aware. It runs silently in the background, getting out of your way until it needs to protect you.
It meters your actual token consumption in real time, compares it against your configured thresholds, and stops execution before a spend limit is crossed rather than after. For autonomous agents running without a human present, budget exceedance triggers a hard halt on all operations and sends a notification to your configured channel, operations don't resume until you explicitly clear the halt.
The skill is available right now on ClawHub's marketplace, alongside 3,200+ other skills.
How It Works (the technical bits)
This integration matches how OpenClaw ships software. It uses lightweight, composable units that you can attach to an agent and distribute.
1) Skill-as-a-single-file (SKILL.md) injection
The guardrail lives as a single SKILL.md file that OpenClaw injects into the agent's system prompt.
Why that matters:
- No SDK integration
- No application refactors
- No changes to your agent runtime
The skill is self-contained. It carries its own instructions, its own operational logic, and its own setup flow inside one Markdown file that OpenClaw loads at startup. If you want to understand exactly what it's doing, you can read the whole thing in less than a few minutes.
After ClawHub installs the skill, a post-install script handles the heavier lifting.
It installs prerequisites (the revenium CLI and jq via Homebrew), configures Docker sandbox bind mounts so the agent can invoke the CLI and read credentials inside the sandbox, seeds an initial budget status file, injects a mandatory budget check into the agent's AGENTS.md, and deploys a lightweight BUDGET-GUARD.md into the workspace via OpenClaw's bootstrap-extra-files hook.
This ensures budget enforcement is active in every session, including isolated cron jobs and subagents that don't load AGENTS.md. All of this runs once, and the skill itself remains a single Markdown file that carries no runtime dependencies of its own.
This architecture reflects Revenium's water-meter philosophy: the meter on the side of your house measures what flows through the pipes, but it never shuts off your faucets. If the meter goes offline, you can still flush your toilets, wash your hands, and water your lawn.
Budget enforcement should work the same way. It observes and reports, and it can warn you when spend is running high, but it should never become a dependency that takes your agent down with it.
2) The operation-guard pattern (budget checks at the boundary)
At a high level, the skill implements an operation guard with rules:
- Before each agent turn, check the current budget state
- If under budget, proceed silently
- If over budget in interactive mode, stop execution and ask the user for explicit approval to continue
- If over budget in autonomous mode, hard-halt all operations and send a notification to the configured channel (Slack, Discord, Telegram, etc.) - the agent will not resume until the halt is explicitly cleared
This keeps a human meaningfully in the loop at the moment it matters (when money is on the line) without making the agent feel broken or opaque.
For autonomous agents where no human is present, the halt-and-notify pattern ensures nothing runs away in the background. Once a halt is triggered, it sticks. Only an explicit clear-halt.sh can resume operations, even if spend later drops below the threshold.
This is deliberate: a budget breach in autonomous mode should require a human decision, not quietly self-resolve. When the user does approve resumption, the agent can run clear-halt.sh itself within the conversation. Any tokens consumed during that exchange are tagged as GUARDRAIL operations in Revenium, so budget enforcement overhead is tracked separately from the actual work your agent is doing.
The check is fast, local, and adds no measurable latency to the normal (under-budget) execution path. The agent reads a local JSON file written by the background cron rather than making a network call to Revenium on every turn.
3) Metering in the background (cron + JSONL parsing)
Budget enforcement needs metering that is accurate, timely, and has low overhead. To avoid adding agent-side latency, metering runs out-of-band.
A lightweight cron job runs every minute, executing two independent scripts back-to-back: a metering reporter and a budget checker. Separating these means a failure in one doesn't block the other. The metering reporter parses OpenClaw's session JSONL files, extracting:
- Input/output token counts, cache reads/writes
- Model identifiers and providers (derived from the model string, e.g.
claude-sonnet-4-6→ Anthropic) - Model source (e.g.
bedrock) and whether the API call was streamed - Stop reasons (END, TOKEN_LIMIT, TIMEOUT, etc.)
- The user's input message and the assistant's response (only if you've explicitly enabled "AI Prompt Capture" in the Revenium app; otherwise, no prompt data leaves your machine)
- The session's system prompt
- Request/response timestamps and computed duration in milliseconds
- A trace ID that walks the parentId chain to correlate all completions within a single conversation turn
- Operation type:
CHATfor regular responses,TOOL_CALLfor tool invocations, orGUARDRAILfor budget enforcement checks themselves
Each event is shipped to the Revenium metering API via revenium meter completion. A ledger file tracks reported transactions to avoid duplicates, and sessions inactive for over an hour are marked as done so they are not re-scanned.
After metering completes, a separate budget check script fetches the current alert from Revenium, computes whether spend exceeds the threshold, and writes the result to a local budget-status.json. If the agent is in autonomous mode and spend has crossed the threshold, the script transitions the agent into a halted state and fires a notification to the configured channel.
By decoupling metering from execution, we eliminate any risk of the accounting layer adding latency or introducing failure modes into your agent's core loop. The agent runs fast. The accounting catches up asynchronously. One minute of lag is an entirely acceptable trade-off for zero impact on agent performance.
4) Fail-open behavior (guardrails without brittleness)
We made a deliberate call on failure behavior. If the cron hasn't run yet, or if the budget status file is missing, the agent proceeds with a warning rather than a hard block. This is fail-open, not fail-closed.
The post-install script seeds an initial budget-status.json with zeroed values so the agent always has a file to read, even before the cron has run for the first time. If that file is ever missing or unreadable, the skill tells the user and proceeds rather than blocking.
A guardrail system shouldn't become a new single point of failure for your agent workflows.
We'd rather surface a clear warning ("Budget status unavailable. Proceeding with caution.") and let you make an informed decision than silently brick your agent over infrastructure noise.
Safety shouldn't come at the cost of brittleness.
The Revenium CLI
The skill is powered by the revenium CLI, which you can install via Homebrew:
brew install revenium/tap/reveniumRepo: github.com/revenium/revenium-cli.
The CLI wraps the Revenium API for:
- Budget configuration and alert management
- Metering ingestion (the
meter completioncommand used by the cron) - Local agent state synchronization
- Configuration management (API key, Team/Tenant/User IDs)
You can query your current spend, adjust thresholds, review alert history, and configure new budget periods all from the command line.
The skill orchestrates the CLI under the hood, so users who interact with the agent through conversation never need to think about the CLI directly.
The agent understands budget-related questions and actions, and handles the plumbing transparently. Run /revenium at any time to view your budget status, reset your spend counter, or reconfigure your thresholds and period. For developers who want direct control, the CLI is there. For everyone else, it stays invisible.
What's Next
This launch also connects directly to Revenium's Tool Registry, our recently released platform for metering external APIs, MCP servers, and SaaS tool calls made by AI agents.
The same infrastructure that tracks what your agent spends on a web search API or a database query now tracks what it spends on tokens. The metering cron tags every completion with an operation type (CHAT, TOOL_CALL, or GUARDRAIL) so you can see exactly how your token budget breaks down by what the agent was doing.
For teams trying to build a coherent picture of total AI operating costs, that unification is significant. OpenClaw token spend and external tool spend now live in the same ledger.
We've kept the Revenium skill fully open source, and the developer tier is free to get started. We are genuinely interested in how different teams want to structure budgets. This can be by project, by user, by environment, or by model.
We would love your feedback as you put this into practice.
The repo is open, the ClawHub listing is live, and we're in Discord if you want to talk through your setup or share what you're building.
Come find us: discord.gg/J2DbmjZ2nA
Your agents are powerful. Now they're also accountable.
Resources:
- Revenium docs and free tier signup: get your API key and configure your first budget
- ClawHub Marketplace listing: skill page with install instructions
- OpenClaw Skill on GitHub: source code and full documentation
- Revenium CLI on GitHub: source code and full documentation
- Discord community: talk to the team and the community (feedback welcome)
.png)
