OpenClaw Guardian

A security layer plugin for OpenClaw that intercepts dangerous tool calls (exec, write, edit) through two-tier regex blacklist rules and LLM-based intent verification. Critical operations require 3/3 unanimous LLM votes, warning-level operations require 1 LLM confirmation. 99% of normal operations pass instantly with zero overhead. Includes bypass/pipe-attack detection, path canonicalization, SHA-256 hash-chain audit logging, and auto-discovers a cheap model from your existing provider config.

The missing safety layer for AI agents.

Why?

OpenClaw gives agents direct access to shell, files, email, browser, and more. 99% of that is harmless. Guardian catches the 1% that isn't — without slowing down the rest.

How It Works

text

Tool Call → Blacklist Matcher (regex rules, 0ms)
              ↓
   No match     → Pass instantly (99% of calls)
   Warning hit  → 1 LLM vote ("did the user ask for this?")
   Critical hit → 3 LLM votes (all must confirm user intent)

Two Blacklist Levels

Level	LLM Votes	Latency	Examples
No match	0	~0ms	Reading files, git, normal ops
Warning	1	~1-2s	rm -rf /tmp/cache, chmod 777, sudo apt
Critical	3 (unanimous)	~2-4s	rm -rf ~/, mkfs, dd of=/dev/, shutdown

What Gets Checked

Only three tool types are inspected:

• exec → command string matched against exec blacklist
• write / edit → file path canonicalized and matched against path blacklist
• Everything else passes through instantly

LLM Intent Verification

When a blacklist rule matches, Guardian asks a lightweight LLM: "Did the user explicitly request this?" It reads recent conversation context to prevent false positives.

• Warning: 1 LLM call. Confirmed → proceed.
• Critical: 3 parallel LLM calls. All 3 must confirm. Any "no" → block.

Auto-discovers a cheap/fast model from your existing OpenClaw provider config (prefers Haiku). No separate API key needed.

LLM Fallback

• Critical + LLM down → blocked (fail-safe)
• Warning + LLM down → asks user for manual confirmation

Blacklist Rules

Critical (exec)

• rm -rf on system paths (excludes /tmp/ and workspace)
• mkfs, dd to block devices, redirects to /dev/sd*
• Writes to /etc/passwd, /etc/shadow, /etc/sudoers
• shutdown, reboot, disable SSH
• Bypass: eval, absolute-path rm, interpreter-based (python -c, node -e)
• Pipe attacks: curl | sh, wget | bash, base64 -d | sh
• Chain attacks: download + chmod +x + execute

Warning (exec)

• rm -rf on safe paths, sudo, chmod 777, chown root
• Package install/remove, service management
• Crontab mods, SSH/SCP, Docker ops, kill/killall

Path Rules (write/edit)

• Critical: system auth files, SSH keys, systemd units
• Warning: dotfiles, /etc/ configs, .env files, authorized_keys

Audit Log

Every blacklist hit logged to ~/.openclaw/guardian-audit.jsonl with SHA-256 hash chain — tamper-evident, each entry covers full content + previous hash.

Installation

bash

openclaw plugins install openclaw-guardian

Or manually:

bash

cd ~/.openclaw/workspace
git clone https://github.com/fatcatMaoFei/openclaw-guardian.git

Token Cost

Scenario	% of Ops	Extra Cost
No match	~99%	0
Warning	~0.5-1%	~500 tokens
Critical	<0.5%	~1500 tokens

Prefers cheap models (Haiku, GPT-4o-mini, Gemini Flash).

File Structure

text

extensions/guardian/
├── index.ts                # Entry — registers before_tool_call hook
├── src/
│   ├── blacklist.ts        # Two-tier regex rules (critical/warning)
│   ├── llm-voter.ts        # LLM intent verification
│   └── audit-log.ts        # SHA-256 hash-chain audit logger
├── test/
│   └── blacklist.test.ts   # Blacklist rule tests
├── openclaw.plugin.json    # Plugin manifest
└── default-policies.json   # Enable/disable toggle

License

MIT