Skip to main content

Rate Limiting

Rate limiting restricts how many messages a user can send within a time window. This prevents spam floods, brute force attacks, and accidental infinite loops.

Quick Start​

Enable rate limiting in your config:

{
  "plugins": {
    "openclaw-shield": {
      "rateLimit": {
        "enabled": true,
        "maxMessages": 20,
        "window": 60,
        "action": "block"
      }
    }
  }
}

This allows 20 messages per 60 seconds per user. The 21st message within 60 seconds will be blocked.

Configuration​

OptionTypeDefaultDescription
enabledbooleanfalseEnable rate limiting
maxMessagesnumber20Max messages per window
windownumber60Time window in seconds
actionstring"block"block or flag
messagestring"⚠️ Too many messages..."Custom rate limit message

How It Works​

Shield tracks message timestamps per user using a sliding window:

User +15551234567:
10:00:00 → Message 1 ✅
10:00:05 → Message 2 ✅
10:00:10 → Message 3 ✅
...
10:00:55 → Message 20 ✅
10:00:58 → Message 21 ❌ RATE LIMITED

After 60 seconds (the window), the first message expires:

10:01:00 → Message 1 expires
10:01:05 → Message 22 ✅ (now 20/20 in current window)

This is a sliding window, not a fixed reset time.

Common Configurations​

Aggressive (Anti-Spam)​

Strict limits for public bots:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 5,
    "window": 60,
    "action": "block"
  }
}

5 messages per minute - Good for preventing spam floods.

Default settings for most use cases:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 20,
    "window": 60,
    "action": "block"
  }
}

20 messages per minute - Allows normal conversation, blocks spam.

Lenient (Enterprise)​

Relaxed limits for trusted environments:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 100,
    "window": 60,
    "action": "flag"
  }
}

100 messages per minute - Very generous, just flags excessive use.

Per-Hour Limiting​

For very relaxed rate limiting:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 500,
    "window": 3600,
    "action": "block"
  }
}

500 messages per hour - Good for bots with long conversations.

Actions​

Block Mode​

User sees immediate rejection:

⚠️ Too many messages. Please slow down and try again later. (Reset in 2m)

Message is rejected completely.

Flag Mode​

Message is allowed but prepended with warning:

⚠️ [Rate Limit Warning: 21/20]

User's original message here...

Bot can see the warning and respond appropriately.

Exempting Users​

Combine with allowlist to exempt trusted users:

{
  "allowlist": {
    "enabled": true,
    "senders": ["+15551234567"]  // VIP user
  },
  "rateLimit": {
    "enabled": true,
    "maxMessages": 10,
    "window": 60
  }
}

The VIP user bypasses rate limiting entirely.

Use Cases​

Preventing Spam Floods​

Scenario: Public bot getting spammed

Config:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 5,
    "window": 60,
    "action": "block",
    "message": "🛑 Spam detected. Wait 1 minute."
  }
}

Preventing Infinite Loops​

Scenario: Bot and user stuck in conversation loop

Config:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 30,
    "window": 60,
    "action": "block"
  }
}

Preventing DoS Attacks​

Scenario: Attacker trying to overwhelm bot

Config:

{
  "rateLimit": {
    "enabled": true,
    "maxMessages": 10,
    "window": 60,
    "action": "block"
  }
}

Performance​

Rate limiting is extremely fast:

  • Check time: < 1ms
  • Memory: ~50 bytes per tracked user
  • Cleanup: Automatic (old timestamps removed)

No impact on message processing speed.

Troubleshooting​

Legitimate Users Getting Limited​

Problem: Normal users hitting limit

Solution: Increase maxMessages or window:

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

Rate Limit Not Working​

Problem: Users still spamming

Solution:

  1. Check enabled: true
  2. Verify bot restarted
  3. Check logs:
[Shield] Rate Limit: enabled=true, max=20/60s

Need Different Limits Per Channel​

Problem: Want stricter limits for public channels

Solution: Not currently supported. Use multiple bot instances or contact support.

Best Practices​

  1. Start Lenient: Begin with high limits (50/min) and lower if needed
  2. Monitor: Check for false positives
  3. Communicate: Set clear message explaining the limit
  4. Exempt VIPs: Use allowlist for team members
  5. Log: Keep action: "flag" initially to see impact before blocking

Testing​

Test rate limiting:

# Send 21 messages rapidly
# Message 21 should be rate limited

# Check Shield logs
[Shield] Rate limit triggered: +15551234567 (21/20)

Next Steps​