Installation

Prerequisites

Before installing, ensure you meet the system requirements:

• ✅ OpenClaw v2026.1.0+
• ✅ Node.js 18+
• ✅ npm 8+

New to OpenClaw?

See the Quick Start guide for a beginner-friendly walkthrough.

---

Production Installation (Recommended)

Step 1: Install via npm

npm install openclaw-shield

This installs the latest stable version from the npm registry.

Step 2: Configure OpenClaw

Create or edit ~/.openclaw/openclaw.json:

Minimal configuration:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true
    }
  }
}

With backend integration:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true,
      "botToken": "sct_your_token_here"
    }
  }
}

Get your botToken from dashboard.securecheck.io.

Config File Location

• Linux/Mac: ~/.openclaw/openclaw.json
• Windows: C:\Users\YourName\.openclaw\openclaw.json

Create the directory and file if they don't exist.

Step 3: Restart OpenClaw

openclaw gateway --verbose

Expected logs:

🛡️  OpenClaw Shield initializing...
   ✓ Loaded 42 built-in rules
   ✓ Inbound filtering: enabled
   ✓ Outbound filtering: enabled
   ✓ Semantic detection: ready
✅ OpenClaw Shield initialized successfully

Step 4: Verify Protection

Send a test malicious message to your bot:

'; DROP TABLE users; --

Expected response:

🛑 Message blocked by security filter
Reason: SQL injection detected

---

Development Installation

For contributing or customizing Shield:

Step 1: Clone Repository

git clone https://github.com/securecheckio/openclaw-shield.git
cd openclaw-shield

Step 2: Install Dependencies

npm install

Step 3: Build Plugin

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Step 4: Link Locally

# From openclaw-shield directory
npm link

# From your OpenClaw installation
cd ~/.openclaw
npm link openclaw-shield

Step 5: Configure and Test

Follow steps 2-4 from the Production Installation above.

---

Docker Installation

Using docker-compose

Create docker-compose.yml:

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    volumes:
      - ./openclaw.json:/root/.openclaw/openclaw.json
    environment:
      - NODE_ENV=production
    command: openclaw gateway

Create openclaw.json:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true,
      "botToken": "${SHIELD_BOT_TOKEN}"
    }
  }
}

Start the container:

export SHIELD_BOT_TOKEN=sct_your_token
docker-compose up -d

---

Configuration File Location

Shield loads configuration from OpenClaw's main config file.

File Paths by OS

OS	Path
Linux	~/.openclaw/openclaw.json
macOS	~/.openclaw/openclaw.json
Windows	C:\Users\YourName\.openclaw\openclaw.json
Docker	/root/.openclaw/openclaw.json

Creating the Config

If the file doesn't exist:

# Linux/Mac
mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw"
notepad "$env:USERPROFILE\.openclaw\openclaw.json"

Paste this minimal config:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true
    }
  }
}

---

Verification Steps

1. Check Plugin Loaded

openclaw gateway --verbose | grep Shield

Should show:

🛡️  OpenClaw Shield initializing...
✅ OpenClaw Shield initialized successfully

2. Test via Bot Command

Message your bot:

/shield status

Should return Shield statistics.

3. Test Threat Detection

Message your bot:

/shield test <script>alert('xss')</script>

Should show:

⚠️ Message would be BLOCKED
Threats detected:
- xss

---

Updating Shield

Update to Latest Version

npm update openclaw-shield
openclaw gateway --verbose

Check Current Version

npm list openclaw-shield

Upgrade from Beta

If you installed from git, switch to npm:

# Unlink old installation
npm unlink openclaw-shield

# Install from npm
npm install openclaw-shield

# Restart
openclaw gateway

Configuration Options

Basic Options

Option	Type	Default	Description
enabled	boolean	true	Enable/disable Shield
inboundEnabled	boolean	true	Filter incoming messages
inboundMode	string	"flag"	Action: block, flag, monitor
outboundEnabled	boolean	true	Filter outgoing messages
outboundMode	string	"block"	Action: block, flag, monitor

Modes:

• block - Reject message completely
• flag - Allow but add warning
• monitor - Log only, no action

Advanced Options

Option	Type	Default	Description
semanticThreshold	number	0.75	Similarity threshold (0-1)
apiEndpoint	string	"https://securecheck.io"	Backend API endpoint
botToken	string	-	Bot token for backend alerts
autoUpdateRules	boolean	false	Fetch rules from API on startup

Rate Limiting

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 20,
    "window": 60,
    "action": "block",
    "message": "⚠️ Too many messages. Please slow down."
  }
}

Allowlist

{
  "allowlist": {
    "enabled": true,
    "senders": ["+15551234567", "telegram:@admin"],
    "channels": ["whatsapp:company_group"],
    "domains": ["@company.com"]
  }
}

Redaction

{
  "redaction": {
    "enabled": true,
    "mode": "secrets",
    "includeTypes": ["openai_keys", "github_keys", "emails"],
    "keepStart": 6,
    "keepEnd": 4
  }
}

Redaction modes:

• off - No redaction
• secrets - API keys and tokens
• pii - Personal information
• all - Both secrets and PII
• custom - Use includeTypes

Notifications

{
  "notifications": {
    "user": true,
    "admin": true,
    "channel": "telegram:@admin_user",
    "backendAlerts": true,
    "backendAlertThreshold": 3,
    "backendAlertWindow": 3600
  }
}

Minimal Configuration

For basic protection:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true
    }
  }
}

All options use sensible defaults.

Backend Integration

Connect to the SecureCheck backend for centralized monitoring:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true,
      "apiEndpoint": "https://securecheck.io",
      "botToken": "your-bot-token",
      "notifications": {
        "backendAlerts": true
      }
    }
  }
}

Get your bot token from securecheck.io/dashboard.

Note: Backend is optional. Shield works standalone without it.

Troubleshooting

Plugin Not Loading

Error: Cannot find module 'openclaw-shield'

Solution:

# From openclaw-shield directory
npm run build
npm link

# From your bot directory
npm link openclaw-shield

Build Errors

Error: TypeScript compilation errors

Solution:

# Ensure Node.js 18+
node --version

# Clean install
rm -rf node_modules package-lock.json
npm install
npm run build

Shield Not Filtering

Problem: Messages not being checked

Solution:

1. Verify enabled: true in config
2. Check bot was restarted after config changes
3. Look for Shield initialization logs
4. Check for error messages in logs

Rate Limit Not Working

Problem: Users still spamming

Solution:

{
  "rateLimit": {
    "enabled": true,  // Must be explicitly enabled
    "maxMessages": 10,
    "window": 60,
    "action": "block"
  }
}

Next Steps

• Configure rate limiting - Prevent spam
• Use Shield commands - Test and monitor
• Set up backend (optional) - Centralized monitoring