Clawnitor 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

Terminal
openclaw plugins install @clawnitor/plugin

2. Add your API key

Sign up at app.clawnitor.io to get your API key, then add it to your openclaw.json:

openclaw.json
{
  "plugins": {
    "entries": {
      "clawnitor": {
        "config": {
          "apiKey": "clw_live_your_key_here"
        }
      }
    }
  }
}

3. Run your agent

Start your OpenClaw agent normally. Events will appear on your dashboard in real-time.

Configuration

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

apiKeystringrequired
Your Clawnitor API key. Starts with clw_live_.
backendUrlstringdefault: https://api.clawnitor.io
Backend API endpoint. Override for self-hosted or development.
spendLimitnumberdefault: 100
Max spend per session in USD. Agent auto-pauses when this limit is reached.
rateLimitnumberdefault: 120
Max tool calls per minute. Agent auto-pauses when this rate is exceeded.
toolBlockliststring[]default: []
Tool names to always block. Case-insensitive. Example: ["execute_bash", "rm"]
redactionPatternsstring[]default: []
Additional regex patterns for redacting sensitive data from event logs.
Full example — openclaw.json
{
  "plugins": {
    "entries": {
      "clawnitor": {
        "config": {
          "apiKey": "clw_live_abc123",
          "spendLimit": 50,
          "rateLimit": 60,
          "toolBlocklist": ["execute_bash", "delete_file"],
          "redactionPatterns": ["sk-[a-zA-Z0-9]{32}"]
        }
      }
    }
  }
}

Event Monitoring

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

Event types

tool_useEvery tool invocation with name, params, result, duration
llm_callLLM requests with token count, cost, model name
message_sentOutbound messages from the agent
message_receivedInbound messages to the agent
agent_lifecycleSession and agent lifecycle events
subagentSub-agent creation and completion

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

Keyword

Block actions containing specific strings. Case-insensitive by default.

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

Alert or block when event frequency exceeds a threshold in a time window.

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

Alert or block when a numeric field crosses a limit in a time window.

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

Describe what to block in plain English. Evaluated by Claude Haiku.

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

Alert channels

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

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.

1
Server Kill State

Click "Kill" in your dashboard. A WebSocket signal reaches the plugin instantly. All subsequent actions are blocked until you resume.

2
Local Failsafe

Spend circuit breaker, rate limiter, and tool blocklist. Always active, even when offline. Configured via your openclaw.json.

3
Cached Rule Evaluation

Your server-side rules are fetched every 60 seconds and evaluated locally. Keyword, rate, and threshold rules run pre-action without a network round-trip.

Anomaly DetectionPro

Clawnitor 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.

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 Clawnitor backend is unreachable, the plugin keeps working:

  • Events are cached locally in SQLite (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.

POST/api/eventsIngest batch of events (up to 100)
GET/api/eventsList events with pagination
GET/api/agentsList all agents
POST/api/agentsCreate agent
GET/api/rulesList rules
POST/api/rulesCreate rule
PUT/api/rules/:idUpdate rule
DELETE/api/rules/:idDelete rule
GET/api/alertsList alerts
POST/api/agents/:id/killKill (pause) agent
POST/api/agents/:id/resumeResume agent
GET/api/statsDashboard stats
GET/api/savesList saves (blocked actions)
GET/api/saves/countTotal save count
GET/api/statusHealth check (public)

Pricing

Free$01 agents, 3 pattern rules, 7 days history. Email alerts, 1 manual kill/mo, local failsafe, 1 team (2 members).
Pro$5/mo1 (+$3/ea) agents, Unlimited pattern + 5 NL rules, 90 days history. Unlimited kill + auto-kill, AI detection (15-min eval), all alerts, 14-day trial.
Team$19/mo5 (+$2/ea) agents, Unlimited + 20 NL + shared rules, 1 year history. 10 members, 5-min eval, auto-kill, full role management.
EnterpriseCustomUnlimited agents, Unlimited rules, Unlimited history. SSO, audit logs, custom webhooks, custom roles.

Troubleshooting

Events not showing up on the dashboard

Check that your API key is correct and starts with clw_live_. Verify the backend URL is reachable. Events are batched every 5 seconds — wait a moment after starting your agent.

Kill switch didn't trigger

Free tier gets 1 kill per month. Pro and above get unlimited kills. If you've used your monthly kill, upgrade to Pro. Check that the WebSocket connection is active (look for reconnection logs). The local failsafe (spend limits, rate limits, tool blocklist) always works regardless of tier.

Rule not firing

Check that the rule is enabled. Verify the event type matches (e.g., a rate rule on 'tool_use' won't trigger on 'llm_call'). Keyword rules are case-insensitive by default. NL rules require backend connectivity.

Agent paused unexpectedly

Check your spend limit (default $100/session) and rate limit (default 120 calls/min). These fire automatically via the local failsafe. Adjust in your openclaw.json config.

Can't connect to WebSocket

The plugin reconnects automatically with exponential backoff (1s to 60s). If behind a firewall, ensure outbound WebSocket connections to api.clawnitor.io are allowed. HTTPS fallback is always active.

Need help? Email support@clawnitor.io

Home / Demo / Pricing