Install & Quick Start

Requires Node.js 20+.

terminal
# Install globally
$ npm install -g clawwall
# Or via install script
$ curl -fsSL https://clawwall.dev/install.sh | bash
# Start the daemon
$ clawwall start
# Launch agent
$ CLAWWALL_ENABLED=true openclaw

The daemon starts on port 7654 by default and opens the dashboard automatically. Set CLAWWALL_ENABLED=true on your agent to activate the before-tool-call hook.

How It Works

OpenClaw → before-tool-call hook → POST /policy/check → ClawWall daemon
                                                                    ↓
                                        allow (instant) ← Rule Engine → deny (instant)
                                                                    ↓
                                                                  ask → Dashboard [Allow/Deny]
  1. 1. Agent calls a tool (exec, read, write, browser, etc.)
  2. 2. OpenClaw's before-tool-call hook fires, POSTing to /policy/check
  3. 3. ClawWall evaluates built-in and custom rules against tool name + args
  4. 4. ALLOW/DENY returns instantly. ASK suspends the call, pushes to dashboard
  5. 5. Dashboard shows [Allow] / [Deny] buttons; your click resolves the call

What It Protects

Credentials

Blocks reads of .env, .aws/credentials, ~/.ssh/id_rsa, .netrc, .npmrc, and other common credential files via regex matching on path arguments.

Destructive commands

Blocks rm -rf, mkfs, format, fdisk, shred, dd if=/dev/zero, shutdown, halt, reboot, and similar destructive shell patterns.

Data exfiltration

Blocks curl with --data/-d flags, wget --post-data/--post-file, nc -e/-c, and other patterns that send data to external endpoints.

Sensitive path writes

Blocks writes to .env, .ssh/, /etc/passwd, /etc/shadow, /etc/hosts, and other sensitive system/credential paths.

Workspace boundary

Blocks write operations to paths outside the agent's current working directory (cwd). The agent stays in its sandbox.

Internal network

Pauses browser/navigate/web_fetch calls to localhost, 127.x.x.x, 10.x.x.x, 172.16-31.x.x, 192.168.x.x for your approval.

Web Dashboard

The dashboard lives at http://localhost:7654 and auto-opens when you run clawwall start.

You can also use the hosted control panel at clawwall.dev/dashboard — it connects to your local daemon directly from the browser.

Live Feed Real-time stream of every policy decision: tool name, args, decision badge (ALLOW/DENY/ASK), timestamp.
Stats Cumulative allow/deny/ask counts, uptime since daemon start, connection status.
Pending Approvals ASK-decision calls waiting for your input. Each shows tool + args + reason. [Allow] / [Deny] buttons resolve instantly.
Rules View built-in rules (read-only) and manage custom command/path deny patterns.

CLI Reference

Command Description
clawwall start Start the daemon and open the dashboard
clawwall stop Stop the running daemon
clawwall status Show daemon status, port, uptime, and rule counts
clawwall tui Open terminal UI (ncurses-style live feed + pending approvals)
clawwall rules list Print all built-in and custom rules as JSON
clawwall rules add-command <pattern> Add a regex pattern to deny on command args
clawwall rules add-path <pattern> Add a regex pattern to deny on path args
clawwall rules remove-command <index> Remove custom command rule by index
clawwall rules remove-path <index> Remove custom path rule by index
clawwall logs Tail the audit log (JSON lines)
clawwall install-launchd Install macOS launchd plist for auto-start on login

Custom Rules

Custom rules are regex patterns matched against tool arguments. Command rules match against any string arg; path rules match against path-like args. Rules are stored in ~/.clawwall/rules.json by default (override with CLAWWALL_RULES_FILE).

terminal — adding custom rules
# Deny any git push --force
$ clawwall rules add-command "push.*--force"
# Deny writes to /tmp/
$ clawwall rules add-path "^/tmp/"
# Deny curl to specific domain
$ clawwall rules add-command "curl.*evil\.com"
# List all rules
$ clawwall rules list
# Remove custom command rule at index 0
$ clawwall rules remove-command 0

Patterns are standard JavaScript regex strings. They are tested with new RegExp(pattern). Rules file location: ~/.clawwall/rules.json

Built-in Rules

Rule ID Tools Decision Description
dangerous_command exec, bash, shell, process DENY Matches rm -rf, mkfs, format, fdisk, shred, dd, shutdown, halt, reboot
credential_read read, cat, view DENY Matches .env, .aws/credentials, id_rsa, id_ed25519, .netrc, .npmrc
exfiltration exec, bash, shell DENY Matches curl -d/--data, wget --post-*, nc -e, and data-send patterns
sensitive_write write, edit, apply_patch DENY Matches writes to .env, .ssh/, /etc/passwd, /etc/shadow, /etc/hosts
outside_workspace write, edit, apply_patch DENY Path not under process.cwd() at time of call
internal_network browser, navigate, web_fetch ASK URL matches localhost, 127.x, 10.x, 172.16-31.x, 192.168.x

Configuration

All configuration is via environment variables. No config file required.

Variable Default Description
CLAWWALL_ENABLED false Set to true in agent process to activate the hook
CLAWWALL_URL http://localhost:7654 Daemon base URL for policy checks
CLAWWALL_PORT 7654 Port for the daemon to listen on
CLAWWALL_TIMEOUT_MS 5000 Max ms to wait for a policy response before allowing
CLAWWALL_RULES_FILE ~/.clawwall/rules.json Path to custom rules JSON file
CLAWWALL_AUDIT_DIR ~/.clawwall/logs/ Directory for audit log JSONL files

HTTP API

Base URL: http://localhost:7654

Method Path Description
GET /health { status: "ok", hasCustomRules, stats }
GET /stats { allow, deny, ask, uptime, startedAt }
GET /rules { builtIn, custom: { denyCommands, denyPaths } }
POST /rules/add Body: { type, pattern } → { added, rules }
DELETE /rules/command/:index Remove custom command rule → { removed, rules }
DELETE /rules/path/:index Remove custom path rule → { removed, rules }
POST /rules/reload Reload rules from disk → { reloaded, hasCustomRules }
POST /policy/check Evaluate PolicyRequest → { decision, reason }
WS /ws WebSocket stream: policy events + pending approvals
curl example — policy check 
curl -X POST http://localhost:7654/policy/check \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent",
    "tool": { "name": "exec", "args": { "command": "rm -rf /tmp/test" } },
    "context": { "cwd": "/home/user/project" }
  }'

# Response:
# { "decision": "deny", "reason": "dangerous_command" }

Agent Integration

Set CLAWWALL_ENABLED=true before launching your OpenClaw agent. ClawWall auto-registers the hook via the OpenClaw config.

~/.openclaw/config.json — manual hook config 
{
  "hooks": {
    "before-tool-call": [
      {
        "name": "clawwall",
        "enabled": true,
        "url": "http://localhost:7654/policy/check",
        "timeout_ms": 5000
      }
    ]
  }
}

Audit Log

Every policy decision is written to ~/.clawwall/logs/YYYY-MM-DD.jsonl as newline-delimited JSON.

audit log entry 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ts": "2025-01-15T10:23:45.123Z",
  "agent_id": "my-agent",
  "tool": "exec",
  "args": { "command": "rm -rf /tmp" },
  "decision": "deny",
  "reason": "dangerous_command",
  "cwd": "/home/user/project"
}

Tail the live log with: clawwall logs  |  Override location: CLAWWALL_AUDIT_DIR

Auto-Start on Login

On macOS, ClawWall can install a launchd plist so the daemon starts automatically when you log in.

terminal
# Install launchd plist
$ clawwall install-launchd
# Verify it's loaded
$ launchctl list | grep clawwall
# Plist location
# ~/Library/LaunchAgents/dev.clawwall.daemon.plist

Scope & Limitations

⚠ ClawWall is not an OS-level firewall

ClawWall works by integrating with OpenClaw's tool execution pipeline. It intercepts tool calls made by OpenClaw-compatible agents before they execute.

Other AI tools — Cursor, Claude Desktop, Copilot, Windsurf — are not covered unless they implement the ClawWall HTTP API (POST /policy/check).

ClawWall does not install kernel modules, eBPF probes, or OS-level syscall hooks. It cannot catch operations performed directly by the OS or by tools outside the hook pipeline.