Can OpenClaw’s Broad Permissions Be Tamed? Introducing ClawReins – an Audited AI Agent Guard

OpenClaw agents can execute shell commands, modify files, and call APIs. When granted root privileges they can delete databases or mass‑delete emails, posing a serious security risk.

ClawReins – a watchdog layer for OpenClaw

ClawReins is a plugin that hooks the before_tool_call event, pauses any risky action, waits for a human decision, and records a full audit log. It acts like a sudo for the agent.

Real‑world incidents

TechCrunch (Feb 23 2026): a Meta AI researcher reported an OpenClaw agent that ran away in her mailbox.

Case: an OpenClaw agent attempted to delete 4,382 Gmail messages; ClawReins intercepted and blocked the operation.

Two‑stage protection

Pre‑execution : a security scanner runs 13 high‑risk configuration checks.

Runtime : tool calls are intercepted; the policy decides to ALLOW, ASK (human approval), or DENY.

Core features

Browser state awareness – detects CAPTCHA, 2FA, challenge walls.

Irreversible risk scoring – distinguishes high‑risk from catastrophic actions.

Runtime intervention via terminal or messaging channels.

ToolShield alignment – synchronises new tool hardening guidelines.

Complete audit log – every decision is traceable.

Trajectory forecasting – predicts high‑risk N+1 steps from session memory.

Runtime interception flow

AI agent calls tool → before_tool_call hook fires
                ↓
        ClawReins checks policy
                ↓
      ┌───────────┴───────────┐
      ↓                       ↓
   ALLOW                ASK/DENY
      ↓                       ↓
   Execute immediately   Pause and await approval
                              ↓
                     ┌───────┴───────┐
                     ↓               ↓
               User approves   User rejects
                     ↓               ↓
               Execute ✓        Cancel ✓
                     ↓
           Decision written to audit log

Approval decision types

ALLOW : execute immediately (e.g., file read).

ASK : prompt for approval (e.g., file write, shell command).

DENY : auto‑block (e.g., file delete).

Confirm token for catastrophic actions

ClawReins returns a token request, e.g. CONFIRM-AB12CD.

The agent calls

clawreins_respond({ decision: "confirm", confirmation: "CONFIRM-AB12CD" })

.

The action proceeds only if the token matches.

Default "Balanced" security policy

FileSystem : read – ALLOW; write – ASK; delete – DENY.

Shell : bash – ASK; exec – ASK.

Browser : screenshot – ALLOW; navigate/click/type/evaluate – ASK.

Gateway : sendMessage – ASK.

Network : fetch/request – ASK.

Other : all actions – ASK (fail‑safe default).

Security scanning

ClawReins runs a pre‑execution scanner that checks the local OpenClaw environment for 13 high‑risk configuration issues.

13 security checks

GATEWAY_BINDING (Critical) : Gateway listening on 0.0.0.0 or missing localhost binding – auto‑fixed.

API_KEYS_EXPOSURE (Critical) : Plaintext API keys/tokens/passwords in config – not auto‑fixed.

FILE_PERMISSIONS (Critical) : Config file permissions not 600 – auto‑fixed.

HTTPS_TLS (Warning) : Missing HTTPS/TLS or certificate config – not auto‑fixed.

SHELL_COMMAND_ALLOWLIST (Critical) : Missing safeBins or equivalent allowlist – auto‑fixed.

SENSITIVE_DIRECTORIES (Warning) : Agent can still access ~/.ssh, ~/.gnupg, ~/.aws, /etc/shadow – not auto‑fixed.

WEBHOOK_AUTH (Warning) : Webhook endpoint lacks auth token – not auto‑fixed.

SANDBOX_ISOLATION (Warning) : No Docker or sandbox isolation detected – not auto‑fixed.

DEFAULT_WEAK_CREDENTIALS (Critical) : Default/weak/undefined Gateway credentials – not auto‑fixed.

RATE_LIMITING (Warning) : Missing Gateway throttling or rate‑limit config – not auto‑fixed.

NODEJS_VERSION (Critical) : Node.js version vulnerable to CVE‑2026‑21636 – not auto‑fixed.

CONTROL_UI_AUTH (Critical) : Control UI auth bypass flag enabled – auto‑fixed.

BROWSER_UNSANDBOXED (Critical) : Browser skill missing headless: true or sandbox: true – not auto‑fixed.

Exit codes

0

– SECURE. 1 – NEEDS ATTENTION. 2 – EXPOSED.

Installation & configuration

Method 1 – npm (recommended)

# Install plugin
openclaw plugins install clawreins@beta

# Run setup
node ~/.openclaw/extensions/clawreins/dist/cli/index.js init

# Restart Gateway
openclaw gateway restart

Method 2 – local clone (development)

# Clone and build
git clone https://github.com/pegasi-ai/clawreins
cd clawreins
npm install
npm run build

# Register as linked plugin
openclaw plugins install --link .

# Run setup
node dist/cli/index.js init

# Restart Gateway
openclaw gateway restart

CLI commands

clawreins init

– interactive setup wizard. clawreins configure – alias for init (OpenClaw entry). clawreins policy – manage security policies. clawreins stats – show statistics. clawreins audit – view decision history. clawreins reset – reset statistics. clawreins disable – temporarily disable. clawreins enable – re‑enable. clawreins toolshield-sync – sync ToolShield protections to AGENTS.md. clawreins upgrade / clawreins update – reinstall latest beta and restart Gateway. clawreins scan – run 13 checks and save HTML report. clawreins scan --fix – backup config and apply supported fixes. clawreins scan --monitor – compare with baseline and alert on drift. clawreins scan --monitor --alert-command "…" – run notification script on drift.

Security‑scan usage examples

Basic scan

# Run 13 checks and save HTML report
clawreins scan

# Save report and open automatically
clawreins scan --html

# Machine‑readable output (CI)
clawreins scan --json

Automatic fix

# Apply supported auto‑fixes (requires confirmation)
clawreins scan --fix

# Apply without prompting
clawreins scan --fix --yes

Drift monitoring

# Compare with baseline and alert on drift
clawreins scan --monitor

# Run notification script on drift
clawreins scan --monitor --alert-command "/path/to/send-openclaw-alert.sh"

Daily cron example

# Record only drift daily
0 9 * * * /usr/bin/env \
  HOME=$HOME \
  OPENCLAW_HOME=$HOME/.openclaw \
  /usr/local/bin/clawreins scan --monitor \
  >> $HOME/.openclaw/clawreins/scan-monitor.log 2>&1

# Daily with alert notification
0 9 * * * /usr/bin/env \
  HOME=$HOME \
  OPENCLAW_HOME=$HOME/.openclaw \
  /usr/local/bin/clawreins scan --monitor \
  --alert-command "$HOME/bin/send-openclaw-alert.sh" \
  >> $HOME/.openclaw/clawreins/scan-monitor.log 2>&1

ToolShield integration

ClawReins enables ToolShield by default and can sync its protections to OpenClaw’s AGENTS.md:

# Sync ToolShield protections
clawreins toolshield-sync

# Use a different bundled model
clawreins toolshield-sync --model claude-sonnet-4.5

# Custom OpenClaw path
OPENCLAW_HOME=~/.openclaw-profile clawreins toolshield-sync

# Append without removing existing ToolShield section
clawreins toolshield-sync --append

ToolShield project: https://github.com/CHATS-lab/ToolShield

Memory trajectory forecasting

ClawReins evaluates accumulated session memory before execution and predicts high‑risk N+1 trajectories using three signals:

Drift score – semantic drift from initial intent to current trajectory.

Salami index – seemingly low‑risk steps that form a harmful chain.

Commitment creep – increasing irreversibility and decreasing rollback options.

If the combined risk exceeds a threshold, ClawReins upgrades to human‑in‑the‑loop (HITL) and includes the predicted dangerous path in the approval summary.

Data storage

All data is stored under ~/.openclaw/clawreins/:

~/.openclaw/clawreins/
├── policy.json          # security policy rules
├── decisions.jsonl      # append‑only audit log
├── stats.json           # statistics
├── scan-state.json      # last drift‑monitor baseline
├── browser-sessions.json# encrypted browser auth/session state
└── clawreins.log        # application log

Usage examples

Audit log view

$ clawreins audit --lines 5

16:05:00 | FileSystem.read | ALLOWED | 0.0s
16:06:00 | FileSystem.write | APPROVED | 3.5s (human)
16:07:00 | Shell.bash | REJECTED | 1.2s (human)
16:08:00 | FileSystem.delete | BLOCKED | 0.0s - Policy: DENY

Statistics

$ clawreins stats

📊 ClawReins statistics

Total calls: 142

Decisions:
 ✅ ALLOWED: 35 (24.6%)
 ✅ APPROVED: 89 (62.7%) – user
 ❌ REJECTED: 12 (8.5%) – user
 🚫 BLOCKED: 6 (4.2%) – policy

Average decision time: 2.8s

Developer API

import { Interceptor, createToolCallHook } from 'clawreins';

// Create interceptor with default policy
const interceptor = new Interceptor();

// Create hook for OpenClaw's before_tool_call event
const hook = createToolCallHook(interceptor);

// Register hook with OpenClaw plugin API
api.on('before_tool_call', hook);

ClawReins intercepts each tool mapped in TOOL_TO_MODULE:

FileSystem : read, write, edit, glob

Shell : bash, exec

Browser : navigate, screenshot, click, type, evaluate

Network : fetch, request, webhook, download

Gateway : listSessions, listNodes, sendMessage

Unmapped tools default to defaultAction (ASK, fail‑safe).

Project structure

src/
├── core/
│   ├── Interceptor.ts          # policy evaluation engine
│   ├── Arbitrator.ts           # human approval (TTY prompt / channel queue)
│   ├── ApprovalQueue.ts        # in‑memory approval state for channel mode
│   ├── MemoryRiskForecaster.ts # drift/Salami/commitment prediction
│   ├── toolshield/             # bundled ToolShield core
│   └── Logger.ts               # Winston logging
├── plugin/
│   ├── index.ts               # plugin entry (hook + tool registration)
│   ├── tool-interceptor.ts     # before_tool_call handling + clawreins_respond
│   └── config-manager.ts      # OpenClaw config management
├── storage/                    # persistence (PolicyStore, DecisionLog, StatsTracker)
├── cli/                        # command‑line interface
├── toolshield/                 # ToolShield sync helper
├── types.ts                    # TypeScript definitions
└── config.ts                   # default policy

Security principles

✅ Zero trust – every action is evaluated.

✅ Synchronous blocking – agent waits for approval.

✅ No bypass – plugin hook intercepts all tool calls.

✅ Immutable audit – JSON Lines log is append‑only.

✅ Human authority – critical decisions require human sign‑off.

✅ Fail‑safe – unknown actions default to ASK/DENY.

Environment variable configuration

# Enable gating for destructive actions (default on)
CLAWREINS_DESTRUCTIVE_GATING=on

# Bulk‑operation threshold (default 20)
CLAWREINS_BULK_THRESHOLD=20

# Irreversible‑action confirm threshold (optional)
CLAWREINS_CONFIRM_THRESHOLD=80

Key takeaways

Production‑grade AI safety layer built specifically for OpenClaw agents.

Two‑stage protection: pre‑execution scan and runtime interception.

13 automated security checks detect high‑risk configurations.

Human‑in‑the‑loop approval workflow with YES/NO/ALLOW/CONFIRM tokens.

Full audit log makes every decision traceable.

Browser awareness detects CAPTCHA, 2FA, and other risk states.

Memory‑based trajectory forecasting predicts risky next steps.

ToolShield integration provides command‑level hardening.

Drift monitoring compares scans over time and alerts on configuration changes.

Fail‑safe defaults block unknown actions.