Basic Configuration

This page covers the essential configuration options to get Shield working for your use case.

Minimal Configuration

The absolute minimum to enable Shield:

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

This uses all defaults:

• ✅ Inbound filtering enabled (flag mode)
• ✅ Outbound filtering enabled (flag mode)
• ✅ Built-in rules loaded
• ✅ Semantic detection enabled
• ❌ Rate limiting disabled
• ❌ Allowlist disabled
• ❌ Backend integration disabled

---

Enable/Disable Shield

Completely Disable

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

Shield won't load at all. No protection.

Temporary Disable via Command

/shield pause 10

Disables for 10 minutes, then automatically resumes.

---

Filtering Direction

Control which direction to filter:

Both Directions (Default)

{
  "inboundEnabled": true,
  "outboundEnabled": true
}

Scans both incoming user messages AND outgoing bot responses.

Inbound Only

{
  "inboundEnabled": true,
  "outboundEnabled": false
}

Only scans incoming messages. Bot responses go through unchecked.

Use when:

• You trust your LLM completely
• Want lower latency
• Only concerned about malicious users

Outbound Only

{
  "inboundEnabled": false,
  "outboundEnabled": true
}

Only scans outgoing bot responses. User messages go through unchecked.

Use when:

• Worried about bot leaking secrets
• Need to comply with PII regulations
• Already have another inbound filter

---

Action Modes

Each direction can have a different mode:

Available Modes

Mode	Behavior	User Sees	Bot Sees
block	Reject message	Error message	Nothing
flag	Allow with warning	Original message	Warning prepended
monitor	Allow silently	Original message	Original message

Examples

Conservative (Recommended)

Block dangerous outbound, flag inbound:

{
  "inboundMode": "flag",
  "outboundMode": "block"
}

Why?

• Users see warnings about their suspicious messages
• Bot never leaks secrets (blocked)
• False positives in user messages don't break conversation

Aggressive

Block everything suspicious:

{
  "inboundMode": "block",
  "outboundMode": "block"
}

Why?

• Maximum security
• Good for high-risk environments
• May frustrate legitimate users with false positives

Monitoring Only

Log threats but don't block:

{
  "inboundMode": "monitor",
  "outboundMode": "monitor"
}

Why?

• Testing Shield before enabling
• Collecting data on false positives
• Analyzing threat patterns

---

Backend Integration

Connect to SecureCheck backend for centralized monitoring.

Standalone (No Backend)

{
  "enabled": true
}

Shield works completely offline with local rules.

With Backend

{
  "enabled": true,
  "botToken": "sct_abc123...xyz",
  "apiEndpoint": "https://api.securecheck.io"
}

Get your botToken from dashboard.securecheck.io.

Backend features:

• Centralized alert dashboard
• Community threat intelligence
• Auto-updating rules
• Analytics and reporting
• Multi-bot management

Optional

Backend is completely optional. Shield works great standalone!

---

Semantic Detection

Adjust AI-powered threat detection sensitivity.

Default (Balanced)

{
  "semanticThreshold": 0.75
}

Catches most threats with few false positives.

Sensitive (Catch More)

{
  "semanticThreshold": 0.65
}

Pros: Catches more novel/obfuscated attacks
Cons: More false positives

Conservative (Less Noise)

{
  "semanticThreshold": 0.85
}

Pros: Fewer false positives
Cons: May miss sophisticated attacks

Disabled

{
  "semanticThreshold": 1.0
}

Turns off semantic detection completely. Only regex/keyword matching.

Use when:

• Limited RAM/CPU
• Prioritize speed over detection
• Testing specific rules

---

Rule Management

Auto-Update Rules

{
  "autoUpdateRules": true
}

Fetches latest rules from backend on startup.

Requires: Backend integration (botToken)

Use Only Local Rules

{
  "autoUpdateRules": false
}

Only uses built-in rules. No external fetching.

---

Complete Configuration Example

Putting it all together:

{
  "plugins": {
    "openclaw-shield": {
      "enabled": true,
      
      "// Filtering": "",
      "inboundEnabled": true,
      "inboundMode": "flag",
      "outboundEnabled": true,
      "outboundMode": "block",
      
      "// Backend Integration": "",
      "botToken": "sct_your_token_here",
      "apiEndpoint": "https://api.securecheck.io",
      "autoUpdateRules": true,
      
      "// Detection": "",
      "semanticThreshold": 0.75,
      
      "// Rate Limiting": "(see rate-limiting page)",
      "rateLimit": {
        "enabled": true,
        "maxMessages": 20,
        "window": 60,
        "action": "block"
      },
      
      "// Allowlist": "(see allowlist page)",
      "allowlist": {
        "enabled": true,
        "senders": ["+15551234567"]
      },
      
      "// Redaction": "(see redaction page)",
      "redaction": {
        "enabled": true,
        "mode": "secrets"
      },
      
      "// Notifications": "(see notifications page)",
      "notifications": {
        "user": true,
        "admin": true
      }
    }
  }
}

JSON Comments

JSON doesn't support comments. The "// Comment": "" lines above are for documentation only. Remove them from your actual config.

---

Configuration Validation

Validate your config before restarting:

/shield validate

Output:

Configuration Validation

✅ Status: Valid

No issues found.

Or if there are errors:

Configuration Validation

❌ Status: Invalid

Errors:
- ❌ semanticThreshold must be between 0 and 1
- ❌ botToken is required when autoUpdateRules is true

---

Common Configurations

For Public Bots

{
  "enabled": true,
  "inboundMode": "block",
  "outboundMode": "block",
  "semanticThreshold": 0.75,
  "rateLimit": {
    "enabled": true,
    "maxMessages": 10,
    "window": 60
  }
}

Strict security for untrusted users.

For Internal/Enterprise Bots

{
  "enabled": true,
  "inboundMode": "flag",
  "outboundMode": "block",
  "semanticThreshold": 0.80,
  "allowlist": {
    "enabled": true,
    "domains": ["@company.com"]
  }
}

Trust employees, still prevent data leaks.

For Testing/Development

{
  "enabled": true,
  "inboundMode": "monitor",
  "outboundMode": "monitor",
  "semanticThreshold": 0.70
}

Log everything, block nothing.

---

Configuration Options Reference

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	"flag"	Action: block, flag, monitor
semanticThreshold	number	0.75	Similarity threshold (0-1)
botToken	string	-	Bot token from dashboard
apiEndpoint	string	"https://api.securecheck.io"	Backend API URL
autoUpdateRules	boolean	false	Fetch rules on startup

---

Next Steps

• Rate Limiting - Prevent spam and DoS
• Redaction - Protect sensitive data
• Allowlist - Trust specific users
• Notifications - Get alerted about threats
• Custom Rules - Create your own patterns
• Advanced Settings - Fine-tune performance