Skip to main content

Shield Commands

Interact with Shield using /shield commands in your bot's chat interface.

Available Commands​

/shield or /shield status​

Show current Shield status and statistics.

Output:

🛡️  SecureCheck Shield Status

Configuration:
- Enabled: ✅
- Inbound Mode: flag
- Outbound Mode: block

Statistics:
- Messages Scanned: 1,247
- Inbound: 834
- Outbound: 413
- Threats Blocked: 23

Top Channels:
- whatsapp:group123: 456 scanned, 12 blocked
- telegram:chat456: 378 scanned, 11 blocked

Top Accounts (by blocks):
- +15551234567: 234 scanned, 8 blocked
- telegram:@spammer: 45 scanned, 5 blocked

Use `/shield help` for commands.

/shield help​

List all available commands.

Output:

🛡️  SecureCheck Shield Commands

`/shield` or `/shield status` - Show status
`/shield help` - This help message
`/shield test <message>` - Test if message would be blocked
`/shield validate` - Validate configuration
`/shield health` - Check system health
`/shield pause <minutes>` - Temporarily disable (default: 5 min)
`/shield resume` - Re-enable Shield

Example:
`/shield test DROP TABLE users`
`/shield pause 10`

/shield test <message>​

Test if a message would be blocked without actually blocking it.

Examples:

/shield test DROP TABLE users

Output:

⚠️ Message would be BLOCKED

Threats detected:
- sql_injection

Test message: "DROP TABLE users"
/shield test Hello, how are you?

Output:

✅ Message is SAFE

No threats detected in: "Hello, how are you?"

Use Cases:

  • Test new rules before deploying
  • Debug why messages are being blocked
  • Verify allowlist is working
  • Test custom patterns

/shield validate​

Validate your Shield configuration for errors and warnings.

Output (Valid):

Configuration Validation

✅ Status: Valid

No issues found.

Output (With Issues):

Configuration Validation

❌ Status: Invalid

Errors:
- ❌ semanticThreshold must be between 0 and 1
- ❌ rateLimit.maxMessages must be >= 1

Warnings:
- ⚠️ semanticThreshold is very low (< 0.6) - may cause false positives
- ⚠️ Admin notifications enabled but no channel specified

Checks:

  • semanticThreshold in valid range (0-1)
  • API key length
  • Rate limit values
  • Notification configuration
  • Backend alert setup

/shield health​

Check system health and connectivity.

Output:

System Health Check

✅ Rules Engine: ok (42 rules)
✅ Semantic DB: ok (1,234 embeddings)
⚠️ Backend API: slow (2,300ms)
✅ Rate Limiter: active (5 users tracked)

Status Icons:

  • ✅ ok - Working normally
  • ⚠️ slow - Working but performance degraded
  • ❌ error - Not working, needs attention
  • ℹ️ not configured - Optional feature disabled

What's Checked:

  • Rules engine initialization
  • Semantic database connection
  • Backend API connectivity
  • Rate limiter status

/shield pause <minutes>​

Temporarily disable Shield for troubleshooting or maintenance.

Examples:

/shield pause       # Pause for 5 minutes (default)
/shield pause 10    # Pause for 10 minutes
/shield pause 60    # Pause for 1 hour

Output:

⏸️ Shield paused for 10 minute(s)

Use `/shield resume` to re-enable early.

Use Cases:

  • Troubleshooting false positives
  • Allowing emergency messages through
  • Testing bot behavior without Shield
  • Maintenance windows
warning

Shield will automatically resume after the time expires. All messages are allowed during pause.

Limits:

  • Minimum: 1 minute
  • Maximum: 1440 minutes (24 hours)

/shield resume​

Re-enable Shield immediately (cancel pause).

Output:

▶️ Shield resumed

If Shield is already active:

ℹ️ Shield is already active

Best Practices​

During Incidents​

  1. Check health first

    /shield health

  2. Validate config

    /shield validate

  3. Test specific message

    /shield test <problematic message>

  4. Pause if needed

    /shield pause 10

Regular Monitoring​

Run daily health checks:

# Morning check
/shield status

# Weekly health check
/shield health

# Monthly config review
/shield validate

Before Deploying Changes​

  1. Validate new config locally
  2. Test with /shield test
  3. Deploy to staging bot first
  4. Monitor /shield status after deploy
  5. Keep /shield pause ready for rollback

Troubleshooting​

Commands Not Responding​

Problem: /shield status returns nothing

Solutions:

  1. Check Shield is enabled in config
  2. Restart bot
  3. Check logs for errors: 
    grep "\[Shield\]" bot.log

Permission Denied​

Problem: "You don't have permission to use this command"

Solution: Check OpenClaw role configuration. Bot owner should have access by default.

Test Command Always Says Safe​

Problem: /shield test DROP TABLE returns "safe"

Solution: Rules engine may not be loaded. Check:

/shield health

If rules engine shows error, check API key and connectivity.

Next Steps​