Halt Documentation

Agent monitoring, smart rules, and a kill switch for OpenClaw. One plugin. Total control.

Quick Start

Get from zero to monitored in under 2 minutes.

1. Install the plugin

openclaw plugins install @halt/plugin

2. Set up (one command)

npx halt init

This handles authentication, API key generation, and config in one command. Or manually: sign up at app.halt.dev, copy your API key, and add it to your openclaw.json:

{
  "plugins": {
    "entries": {
      "halt": {
        "config": {
          "apiKey": "clw_live_your_key_here"
        }
      }
    }
  }
}

3. Agents are auto-discovered

When the plugin starts, it reads your openclaw.json and registers all agents with Halt. They appear on your agents page as “discovered” — activate the ones you want to monitor.

To register agents before running them:

npx halt discover

Configuration

All configuration goes inside the config object in your openclaw.json.

{
  "plugins": {
    "entries": {
      "halt": {
        "config": {
          "apiKey": "clw_live_abc123",
          "spendLimit": 50,
          "rateLimit": 60,
          "toolBlocklist": ["execute_bash", "delete_file"],
          "redactionPatterns": ["sk-[a-zA-Z0-9]{32}"]
        }
      }
    }
  }
}

Event Monitoring

Halt captures every action your agent takes through OpenClaw's hooks system.

Event types

Privacy

Sensitive data (API keys, passwords, tokens) is automatically redacted before transmission. Data sharing for aggregate pattern improvement is opt-in and off by default.

Rules & Alerts

Rules evaluate against incoming events and trigger alerts or block actions. Free tier gets 3 pattern rules. Paid tiers get unlimited rules including natural language.

Rule types

{ "type": "keyword", "keywords": ["rm -rf", "DROP TABLE"], "matchMode": "any" }

{ "type": "rate", "eventType": "tool_use", "maxCount": 20, "windowMinutes": 5 }

{ "type": "threshold", "field": "cost_usd", "operator": "gt", "value": 10, "windowMinutes": 60 }

{ "type": "nl", "promptText": "Block any action that sends emails to more than 10 recipients" }

Per-agent scoping

Rules can apply to all agents (default) or be scoped to specific agents. Set the scope when creating a rule — select “All agents” or pick specific agents. The plugin only fetches rules relevant to its agent, so scoped rules never fire on the wrong agent.

Agent-visible rules

Rules can be visible or silent. Visible rules are injected into the agent's system prompt so it knows what's being enforced and can comply proactively. Silent rules enforce without the agent's knowledge. Set per-rule when creating, or override system-wide from Settings (All visible / Per rule / All silent).

Alert channels

Free tier: email only. Paid tiers: email, Telegram, Discord, and SMS. Enterprise adds custom webhooks with HMAC-SHA256 signing.

Shield Pro

Built-in injection detection engine that scans both tool inputs (before execution) and tool outputs (after execution). 140 detection patterns across 6 categories, 3 severity tiers. Zero latency — pure pattern matching, no API calls.

Detection Categories

• Critical (always blocked): Destructive commands (rm -rf, DROP TABLE, curl|bash), credential exfiltration (AWS keys, GitHub tokens, Stripe keys, JWTs, private keys, 30+ service-specific patterns)
• High (block by default): Prompt injection (instruction overrides, system prompt manipulation, jailbreaks, stealth patterns like "do not tell the user", multi-turn manipulation)
• Medium (alert by default): Encoding tricks (zero-width chars, homoglyphs, RTL overrides), data exfiltration (PII in outputs, crypto addresses, healthcare IDs)

How It Works

Shield runs as a standalone scanner in the plugin hook chain, before cached rules. It scans tool parameters on every call, and tool results after execution (catching indirect injection from RAG, APIs, and databases).

Pro+ users get three Shield rules auto-enabled on signup. Critical threats cannot be downgraded. High and medium tiers are configurable — set to block or alert per your preference. Per-tool allowlists prevent false positives on known-safe tools.

Output Scanning

Shield is the only agent monitoring tool that scans tool outputs at the plugin level. This catches indirect prompt injection — malicious instructions hiding in API responses, database results, or RAG documents. Output detections trigger alerts and feed into auto-kill escalation.

Kill Switch

Three layers of pre-action defense. Every tool call and message is checked before execution. If any layer triggers, the action is blocked in-process with zero network latency.

Anomaly DetectionPro

Halt builds a 72-hour behavioral baseline for each agent — typical event rates, tool usage patterns, cost per session. After the learning period, it flags deviations automatically.

No configuration needed. Baselines are built from your agent's actual behavior, not generic thresholds.

Cost Tracking

Every LLM call and tool use captures cost data from OpenClaw's native tracking. Halt aggregates this into actionable spend analytics on your dashboard:

• Per-agent cost cards — see which agents cost the most, with token counts and event volume
• 7-day spend chart — daily trend visualization with week-over-week comparison
• Top costly events — your 10 most expensive individual calls ranked, with model and timestamp
• Spend today + trend — stats row shows today's spend with a percentage change arrow

Cost data comes from OpenClaw's native cost_usd and tokens_used fields in event metadata. Halt does not calculate costs — it uses what OpenClaw reports.

Decision Traces

On each agent's detail page, you can see a visual timeline of recent sessions. Click any session to expand its full decision trace — every tool call, LLM request, and message in order.

• Session cards — date, duration, event count, total cost per session
• Expandable timeline — color-coded dots per event type (tool=sky, LLM=purple, message=green, subagent=yellow)
• Per-call detail — action name, target, model, cost, severity highlighting
• Subagent attribution — subagent lifecycle events show their ID with indented positioning

Navigate to Agents → click an agent → Sessions tab. Sessions are tracked with full lifecycle (active, completed, killed) including duration, event count, and cost. Subagent events are nested within their parent session. Blocked events show a BLOCKED badge with the reason and source rule.

TeamsTeam

Free tier includes 1 team with 2 members. Team tier scales to 10 members with full role management (owner, admin, editor, viewer) and unlimited shared rules.

Shared rules apply across all team members' agents. Invite members via email — invitations expire after 7 days.

Offline Resilience

If the Halt backend is unreachable, the plugin keeps working:

• Events are cached locally (up to 50MB / 7 days)
• Local failsafe (spend limits, rate limits, tool blocklist) stays active
• Cached rules continue evaluating pre-action
• On reconnect, queued events flush automatically

Your agents stay protected even when the internet isn't.

API Reference

All API endpoints require a Bearer token (Authorization: Bearer clw_live_...) unless marked as public.

Pricing

Troubleshooting