OpenClaw请求频率限制与防滥用配置

前言

当你的 OpenClaw 实例接入多个频道并服务多个用户时，一个活跃用户可能在短时间内发送大量消息，导致 API 配额耗尽或响应延迟增加，影响其他用户的体验。本文将详细讲解如何配置 OpenClaw 的频率限制和防滥用机制，确保资源公平分配。

一、为什么需要频率限制

1.1 常见问题场景

单用户刷屏：某个用户连续快速发送几十条消息，占满请求队列
群组消息洪流：活跃群组中每条消息都触发 AI 回复，短时间产生大量 API 调用
恶意滥用：公开的 Bot 被人恶意频繁调用
API 配额保护：防止超出 AI 提供商的 RPM（每分钟请求数）限制

1.2 不限制的后果

影响	说明
API 费用失控	一天可能产生数百美元的费用
其他用户无法使用	请求队列被占满，正常用户得不到回复
触发上游限流	被 Claude/OpenAI 的 API 限速后全部请求变慢
服务崩溃	内存和 CPU 资源被耗尽

二、全局频率限制

2.1 基本配置

// ~/.config/openclaw/openclaw.json5
{
  "rateLimit": {
    "enabled": true,
    // 全局限制：每分钟最多处理的消息数
    "global": {
      "maxRequests": 60,
      "window": "1m"
    }
  }
}

2.2 模型 API 调用限制

根据你的 API 计划配置上游限制：

{
  "rateLimit": {
    "model": {
      // 每分钟最大 API 请求数
      "rpm": 50,
      // 每分钟最大 Token 数
      "tpm": 100000,
      // 每日最大请求数（0=不限制）
      "dailyLimit": 2000,
      // 每日最大费用（美元）
      "dailyCostLimit": 10.00,
      // 达到限制时的行为
      "onLimitReached": "queue"  // "queue"=排队等待, "reject"=直接拒绝
    }
  }
}

当达到限制时，OpenClaw 会向用户发送提示消息：

{
  "rateLimit": {
    "messages": {
      "rateLimited": "请求过于频繁，请稍后再试。",
      "dailyLimitReached": "今日使用额度已用完，请明天再来。",
      "queueing": "当前排队中，预计等待 {waitTime} 秒。"
    }
  }
}

三、按用户限流

3.1 配置用户级别限制

{
  "rateLimit": {
    "perUser": {
      // 每个用户每分钟最多发送的消息数
      "maxRequests": 10,
      "window": "1m",
      // 每个用户每小时最大请求数
      "maxRequestsPerHour": 100,
      // 每个用户每日最大 Token 消耗
      "dailyTokenLimit": 50000,
      // 冷却时间：触发限流后需要等待的时间
      "cooldown": "30s"
    }
  }
}

3.2 VIP 用户豁免

对于某些重要用户或管理员，可以设置更高的限额或豁免：

{
  "rateLimit": {
    "perUser": {
      "maxRequests": 10,
      "window": "1m"
    },
    // 用户白名单：不受限流约束
    "whitelist": [
      "+8613800138000",       // 手机号
      "telegram:123456789",   // Telegram 用户 ID
      "discord:987654321"     // Discord 用户 ID
    ],
    // 自定义用户配额
    "customLimits": {
      "telegram:123456789": {
        "maxRequests": 30,
        "window": "1m",
        "dailyTokenLimit": 200000
      }
    }
  }
}

3.3 用户分组管理

对于大量用户，可以按组设置配额：

{
  "rateLimit": {
    "groups": {
      "free": {
        "maxRequests": 5,
        "window": "1m",
        "dailyTokenLimit": 10000,
        "dailyRequestLimit": 50
      },
      "premium": {
        "maxRequests": 20,
        "window": "1m",
        "dailyTokenLimit": 100000,
        "dailyRequestLimit": 500
      },
      "admin": {
        "maxRequests": 60,
        "window": "1m",
        "dailyTokenLimit": 0  // 0 = 不限制
      }
    },
    // 用户到组的映射
    "userGroups": {
      "telegram:111": "premium",
      "telegram:222": "admin"
    },
    // 未指定组的用户使用的默认组
    "defaultGroup": "free"
  }
}

四、按频道限流

4.1 频道级别限制

不同频道可能有不同的使用模式和优先级：

{
  "rateLimit": {
    "perChannel": {
      "telegram": {
        "maxRequests": 30,
        "window": "1m"
      },
      "discord": {
        "maxRequests": 20,
        "window": "1m",
        // Discord 群组中特殊限制
        "groupChat": {
          "maxRequests": 10,
          "window": "1m",
          // 群聊中仅响应 @Bot 的消息
          "mentionOnly": true
        }
      },
      "whatsapp": {
        "maxRequests": 25,
        "window": "1m"
      }
    }
  }
}

4.2 群组聊天特殊处理

群组聊天的消息量通常远大于私聊，需要特殊策略：

{
  "rateLimit": {
    "groupChat": {
      // 群组中每分钟最多响应的消息数
      "maxResponses": 5,
      "window": "1m",
      // 仅回复被 @ 提及的消息
      "mentionOnly": true,
      // 或者按概率回复（适用于需要偶尔参与对话的场景）
      "responseRate": 0.3,  // 30% 概率回复
      // 连续消息合并：短时间内多条消息合并为一次请求
      "batchWindow": "5s"
    }
  }
}

五、防滥用机制

5.1 消息内容过滤

{
  "antiAbuse": {
    "enabled": true,
    // 最大消息长度（字符数）
    "maxMessageLength": 2000,
    // 拒绝纯重复消息
    "rejectDuplicates": true,
    "duplicateWindow": "1m",
    // 关键词黑名单
    "blockedPatterns": [
      "ignore previous instructions",
      "system prompt"
    ],
    // 检测到滥用时的处理
    "onAbuse": "warn"  // "warn"=发送警告, "block"=静默忽略, "ban"=临时封禁
  }
}

5.2 临时封禁机制

当用户持续触发限流规则时，自动进行临时封禁：

{
  "antiAbuse": {
    "autoBan": {
      "enabled": true,
      // 在指定时间窗口内触发限流超过阈值次数则封禁
      "triggerCount": 5,
      "triggerWindow": "10m",
      // 封禁时长
      "banDuration": "1h",
      // 累计封禁次数达到阈值则永久封禁
      "permanentBanThreshold": 3,
      // 封禁通知消息
      "banMessage": "由于频繁请求，您的账号已被临时限制使用，请 {duration} 后再试。"
    }
  }
}

5.3 封禁管理

# 查看当前封禁列表
openclaw ban list

# 手动封禁用户
openclaw ban add "telegram:123456" --duration 24h --reason "滥用"

# 解除封禁
openclaw ban remove "telegram:123456"

# 查看封禁历史
openclaw ban history --user "telegram:123456"

六、监控限流状态

6.1 查看限流统计

# 查看当前限流状态
openclaw stats --rate-limit

# 输出
# 频率限制统计 (最近1小时)
# ─────────────────────────────
# 全局请求:     580 / 3600
# 被限流次数:   12
# 被限流用户:   3
# 当前排队:     2
# 今日 Token:   89,500 / 无限制
# 今日费用:     $1.85 / $10.00

6.2 Prometheus 指标

# 被限流的请求数
rate(openclaw_rate_limited_total[5m])

# 按用户统计被限流次数
topk(10, increase(openclaw_rate_limited_total[24h]))

# 当前排队长度
openclaw_queue_length

# 每日费用进度
openclaw_daily_cost / openclaw_daily_cost_limit * 100

七、最佳实践

从宽到严：初始设置较宽松的限制，根据实际使用数据逐步收紧
友好提示：限流时给用户清晰的提示信息，告知何时可以继续使用
优先级队列：VIP 用户或管理员的请求优先处理
分级策略：群聊比私聊更需要严格限流
费用兜底：始终设置每日费用上限，防止意外的高额账单
定期调整：每月回顾限流统计，根据用户增长调整限额

合理的频率限制不是限制用户体验，而是确保所有用户都能获得公平、稳定的服务。一个配置得当的限流策略是 OpenClaw 大规模运营的基石。