Skip to main content

Troubleshooting

Common problems and how to solve them.

Installation Issues​

Cannot Find Module 'openclaw-shield'​

Error:

Error: Cannot find module 'openclaw-shield'

Solutions:

  1. Install the package:

    npm install openclaw-shield

  2. Verify installation:

    npm list openclaw-shield

  3. Restart OpenClaw:

    openclaw gateway --verbose

Plugin Not Loading​

Problem: No Shield logs during startup

Check:

  1. Config file location:

    # Linux/Mac
    ls -la ~/.openclaw/openclaw.json

    # Windows
    dir %USERPROFILE%\.openclaw\openclaw.json

  2. JSON syntax:

    • Use jsonlint.com to validate
    • Check for missing commas, quotes
    • Ensure proper nesting

  3. Enable setting:

    {
      "plugins": {
        "openclaw-shield": {
          "enabled": true  // Must be true!
        }
      }
    }

  4. OpenClaw version:

    openclaw --version
    # Must be v2026.1.0 or newer

Configuration Issues​

Config Changes Not Applied​

Problem: Updated config but Shield behaves the same

Solutions:

  1. Restart OpenClaw:

    # Kill existing process
    pkill openclaw

    # Start fresh
    openclaw gateway --verbose

  2. Validate config:

    /shield validate

  3. Check logs for errors:

    grep "Shield" ~/.openclaw/logs/*.log

Invalid Configuration​

Error:

Configuration Validation

❌ Status: Invalid
- semanticThreshold must be between 0 and 1

Solutions:

Check these common mistakes:

SettingValid RangeCommon Mistake
semanticThreshold0.0 - 1.0Using 75 instead of 0.75
rateLimit.maxMessages>= 1Negative numbers
rateLimit.window>= 1Zero or negative
botTokenNon-emptyEmpty string

Detection Issues​

Legitimate Messages Being Blocked​

Problem: False positives blocking real users

Solutions:

  1. Use flag mode instead of block:

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

  2. Increase semantic threshold:

    {
      "semanticThreshold": 0.85  // Higher = less sensitive
    }

  3. Add to allowlist:

    {
      "allowlist": {
        "enabled": true,
        "senders": ["+15551234567"]
      }
    }

  4. Review specific rule:

    /shield test <the message that was blocked>

  5. Temporarily disable:

    /shield pause 10

Threats Not Being Detected​

Problem: Malicious messages passing through

Solutions:

  1. Verify Shield is running:

    /shield status

  2. Check filtering is enabled:

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

  3. Check action mode:

    {
      "inboundMode": "block",  // Not "monitor"
      "outboundMode": "block"
    }

  4. Lower semantic threshold:

    {
      "semanticThreshold": 0.70  // Lower = more sensitive
    }

  5. Check if user is allowlisted:

    /shield allowlist

  6. Add custom rule: See Custom Rules to detect specific patterns.

Performance Issues​

High Latency​

Problem: Messages taking too long to process

Symptoms:

  • Users see delays
  • Bot feels slow
  • Timeouts

Solutions:

  1. Enable caching:

    {
      "advanced": {
        "ruleCache": { "enabled": true },
        "semanticCache": { "enabled": true }
      }
    }

  2. Disable debug mode:

    {
      "advanced": {
        "debug": { "enabled": false }
      }
    }

  3. Increase timeout:

    {
      "advanced": {
        "processingTimeout": 1000
      }
    }

  4. Disable semantic detection:

    {
      "semanticThreshold": 1.0
    }

  5. Check system resources:

    top  # Check CPU/RAM usage

High Memory Usage​

Problem: Shield consuming excessive RAM

Solutions:

  1. Reduce cache sizes:

    {
      "advanced": {
        "ruleCache": { "maxSize": 500 },
        "semanticCache": { "maxSize": 5000 }
      }
    }

  2. Disable semantic detection:

    {
      "semanticThreshold": 1.0
    }

  3. Lower thread pool:

    {
      "advanced": {
        "threadPoolSize": 2
      }
    }

  4. Enable aggressive GC:

    {
      "advanced": {
        "memory": {
          "gcAggressiveness": "high"
        }
      }
    }

Rate Limiting Issues​

Users Not Being Rate Limited​

Problem: Spammers still flooding bot

Solutions:

  1. Verify rate limiting enabled:

    {
      "rateLimit": {
        "enabled": true  // Must be explicitly true
      }
    }

  2. Check action mode:

    {
      "rateLimit": {
        "action": "block"  // Not "monitor"
      }
    }

  3. Lower limits:

    {
      "rateLimit": {
        "maxMessages": 5,
        "window": 60
      }
    }

  4. Check if user allowlisted: Allowlisted users bypass rate limits.

Legitimate Users Getting Limited​

Problem: Normal users hitting rate limit

Solutions:

  1. Increase limits:

    {
      "rateLimit": {
        "maxMessages": 30,
        "window": 60
      }
    }

  2. Use flag mode:

    {
      "rateLimit": {
        "action": "flag"
      }
    }

  3. Add to allowlist:

    {
      "allowlist": {
        "senders": ["+15551234567"]
      }
    }

Backend Integration Issues​

Cannot Connect to Backend​

Error:

⚠️ Backend API: connection failed

Solutions:

  1. Check internet connection:

    ping api.securecheck.io

  2. Verify bot token:

    {
      "botToken": "sct_your_actual_token"  // Not empty or placeholder
    }

  3. Check firewall:

    # Allow HTTPS outbound
    curl https://api.securecheck.io/health

  4. Check proxy settings:

    {
      "advanced": {
        "proxy": {
          "https": "http://proxy.company.com:8080"
        }
      }
    }

  5. Increase timeout:

    {
      "advanced": {
        "api": {
          "timeout": 10000
        }
      }
    }

Backend Integration Not Required​

Good News: Shield works perfectly without backend!

{
  "enabled": true
  // No botToken needed
}

Backend features you'll miss:

  • Centralized dashboard
  • Community rules
  • Multi-bot management
  • Analytics

But you get:

  • ✅ Full threat detection
  • ✅ All local rules
  • ✅ Complete privacy
  • ✅ No external dependencies

Command Issues​

Shield Commands Not Responding​

Problem: /shield status returns nothing

Solutions:

  1. Check Shield loaded:

    openclaw gateway --verbose | grep Shield

  2. Verify command permissions:

    • Must be bot owner or admin
    • Check OpenClaw role configuration

  3. Try alternate command:

    /shield help

  4. Check logs:

    tail -f ~/.securecheck/shield/logs/*.log

Dashboard Issues​

Cannot Access Dashboard​

Problem: dashboard.securecheck.io won't load

Solutions:

  1. Check internet connection

  2. Try different browser

  3. Clear cache/cookies

  4. Disable browser extensions

  5. Check status: Visit status.securecheck.io

Dashboard Not Showing Alerts​

Problem: No alerts in dashboard

Solutions:

  1. Verify backend integration:

    {
      "botToken": "sct_your_token",
      "notifications": {
        "backendAlerts": true
      }
    }

  2. Check bot token is correct

  3. Send test threat:

    /shield test DROP TABLE users

  4. Wait a few minutes: Alerts may be batched/delayed

  5. Check alert filters: Dashboard may be filtering by date/type

Log Issues​

No Logs Being Created​

Problem: Log directory empty

Solutions:

  1. Check log path:

    ls -la ~/.securecheck/shield/logs/

  2. Verify logging enabled:

    {
      "advanced": {
        "logging": {
          "file": true
        }
      }
    }

  3. Check permissions:

    chmod 755 ~/.securecheck/shield/logs/

  4. Look in console:

    openclaw gateway --verbose

Logs Too Large​

Problem: Log files consuming too much disk

Solutions:

  1. Enable log rotation:

    {
      "advanced": {
        "logging": {
          "maxFileSize": "10M",
          "maxFiles": 5,
          "compress": true
        }
      }
    }

  2. Reduce log level:

    {
      "advanced": {
        "logLevel": "warn"  // Instead of "debug"
      }
    }

  3. Manual cleanup:

    # Delete old logs
    find ~/.securecheck/shield/logs/ -name "*.log" -mtime +30 -delete

Debugging Tips​

Enable Debug Mode​

{
  "advanced": {
    "debug": {
      "enabled": true,
      "traceRules": true,
      "traceSemantic": true,
      "tracePerformance": true
    },
    "logLevel": "debug"
  }
}

Restart and check logs:

tail -f ~/.securecheck/shield/logs/security-*.log

Use Shield Commands​

# Check status
/shield status

# Validate config
/shield validate

# Test a message
/shield test your message here

# Check health
/shield health

Check System Health​

# Node.js version
node --version

# OpenClaw version
openclaw --version

# Disk space
df -h

# Memory
free -h

# CPU
top

Getting Help​

Self-Service​

  1. Search docs: docs.securecheck.io
  2. Check logs: ~/.securecheck/shield/logs/
  3. Test commands: /shield help
  4. Validate config: /shield validate

Community Support​

  1. Discord: discord.gg/YEtqKvC6
  2. GitHub Issues: github.com/securecheckio/openclaw-shield/issues
  3. Community Forum: forum.securecheck.io

Professional Support​

  1. Email: support@securecheck.io
  2. Priority support: For paid plans
  3. Enterprise support: Custom SLAs available

Reporting Bugs​

When reporting issues, include:

  1. OpenClaw version: openclaw --version
  2. Shield version: npm list openclaw-shield
  3. Operating system: Linux/Mac/Windows + version
  4. Configuration: (redact sensitive values)
  5. Error messages: Full error text
  6. Logs: Last 50 lines from Shield logs
  7. Steps to reproduce: Exact steps to trigger issue

GitHub Issue Template:

## Environment
- OpenClaw: v2026.1.0
- Shield: v0.1.0
- OS: Ubuntu 22.04
- Node: v18.17.0

## Configuration
```json
{
  "enabled": true,
  "inboundMode": "block"
}

Expected Behavior​

Shield should block SQL injection

Actual Behavior​

Message passes through undetected

Steps to Reproduce​

  1. Configure Shield with default rules
  2. Send message: "'; DROP TABLE users; --"
  3. Message not blocked

Logs​

[ERROR] Rule engine failed to load...

---

## Next Steps

- **[Commands](commands)** - Control Shield via bot
- **[Advanced Settings](../configuration/advanced)** - Performance tuning
- **[Dashboard](../dashboard/overview)** - Monitor via web