Skip to main content

Advanced Settings

Information about advanced features, performance characteristics, and future configuration options.

Current Status

Most advanced settings are currently optimized with sensible defaults and not user-configurable. Future versions will add more tuning options based on user feedback.

Currently Configurable​

Semantic Detection Threshold​

Control AI-powered threat detection sensitivity:

{
  "semanticThreshold": 0.75
}

Values:

  • 0.65 - More sensitive (catches more, more false positives)
  • 0.75 - Balanced (default, recommended)
  • 0.85 - Less sensitive (fewer false positives, may miss variants)
  • 1.0 - Disabled (no semantic detection, regex/keywords only)

See Basic Configuration for details.

Performance Characteristics​

Processing Speed​

Without Semantic Detection (semanticThreshold: 1.0):

  • Average: 5-10 ms/message
  • P95: < 20 ms
  • P99: < 30 ms

With Semantic Detection (default):

  • Average: 15-30 ms/message
  • P95: < 50 ms
  • P99: < 100 ms

Resource Usage​

CPU:

  • Idle: < 1%
  • Processing: 5-10% per core
  • Semantic: 20-30% per core during detection

Memory:

  • Base: ~100 MB
  • Per 1,000 rules: +50 MB
  • Semantic models: +500 MB (first load)

Storage:

  • Plugin code: ~5 MB
  • Built-in rules: < 1 MB
  • Semantic DB: ~100-500 MB (if enabled)
  • Logs: ~1-10 MB/day

Throughput​

  • Single core: ~500 messages/second
  • Dual core: ~1,000 messages/second
  • Quad core: ~2,000 messages/second

Built-In Optimizations​

Shield uses these optimizations automatically:

Caching​

Rule cache:

  • Compiled regex patterns cached
  • ~5ms vs ~15ms without cache

Semantic cache:

  • Embedding calculations cached
  • 70-80% hit rate typical
  • ~2ms cache hit vs ~30ms miss

Allowlist Fast Path​

  • Allowlist check happens first
  • < 0.1 ms lookup (hash table)
  • Bypasses all other checks

Rate Limit Tracking​

  • Sliding window algorithm
  • In-memory timestamp tracking
  • Automatic cleanup of old entries
  • < 1 ms check time

Monitoring​

Via Shield Commands​

Check status and health:

/shield status    # Statistics and activity
/shield health    # System component status

Example status output:

Messages Scanned: 1,247
Threats Blocked: 23
Top Threats: sql_injection (12), xss (8), prompt_injection (3)

Example health output:

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

Log Locations​

Shield logs to:

  • OpenClaw console logs
  • File: ~/.securecheck/shield/logs/security-YYYY-MM-DD.log

Log levels (controlled by OpenClaw):

  • INFO - Normal operations
  • WARN - Threats detected
  • ERROR - System errors

Future Configuration Options​

These settings are planned for future releases:

Performance Tuning (Planned)​

  • Processing timeouts
  • Concurrent processing limits
  • Thread pool configuration

Advanced Caching (Planned)​

  • Cache size limits
  • TTL configuration
  • Cache eviction policies

Logging Options (Planned)​

  • Log rotation settings
  • Structured JSON logging
  • Custom log destinations

Health/Metrics (Planned)​

  • Prometheus metrics endpoint
  • OpenTelemetry integration
  • Health check endpoint

Network Options (Planned)​

  • HTTP proxy support
  • Custom TLS certificates
  • Connection pooling
Want These Features?

If you need specific advanced configuration options, please:

Optimization Tips​

For Best Performance​

  1. Enable semantic detection for comprehensive protection
  2. Use allowlist for trusted users (fastest path)
  3. Start with flag mode before switching to block
  4. Monitor via /shield status to identify issues
  5. Keep rules updated via autoUpdateRules: true

For Lower Memory​

  1. Disable semantic detection (semanticThreshold: 1.0)
  2. Use fewer custom rules
  3. Rely on built-in rules (well-optimized)

For Lower CPU​

  1. Increase semantic threshold (0.85+) for fewer checks
  2. Use specific rules instead of broad patterns
  3. Optimize custom regex patterns

Troubleshooting Performance​

High Latency​

Problem: Messages taking too long to process

Check:

  1. Run /shield health - look for slow components
  2. Check semantic threshold - try increasing to 0.85 or 1.0
  3. Review custom rules - complex regex can be slow
  4. Check system resources - CPU/RAM usage

High Memory Usage​

Problem: Shield consuming too much RAM

Solutions:

  1. Disable semantic detection (semanticThreshold: 1.0)
  2. Reduce number of custom rules
  3. Check for memory leaks in logs
  4. Restart OpenClaw to clear caches

Slow Semantic Detection​

Problem: First message takes long time

Explanation:

  • First semantic check downloads transformer models (~200MB)
  • Models cached after first download
  • Subsequent checks are fast (~30ms)

Normal behavior - not a problem!

Next Steps​