OpenClaw 요청 빈도 제한 및 남용 방지 설정

서문

OpenClaw 인스턴스가 여러 채널에 연결되어 다수의 사용자를 서비스할 때, 한 활발한 사용자가 단시간에 대량의 메시지를 보내면 API 할당량이 소진되거나 응답 지연이 증가하여 다른 사용자의 경험에 영향을 줄 수 있습니다. 본 문서에서는 OpenClaw의 빈도 제한과 남용 방지 메커니즘을 설정하여 리소스를 공정하게 분배하는 방법을 상세히 설명합니다.

1. 빈도 제한이 필요한 이유

1.1 일반적인 문제 시나리오

단일 사용자 도배: 한 사용자가 연속으로 빠르게 수십 개의 메시지를 보내 요청 큐를 가득 채움
그룹 메시지 폭주: 활발한 그룹에서 모든 메시지가 AI 답변을 트리거하여 단시간에 대량의 API 호출 발생
악의적 남용: 공개 Bot이 악의적으로 빈번하게 호출됨
API 할당량 보호: AI 공급자의 RPM(분당 요청 수) 제한 초과 방지

1.2 제한하지 않을 때의 결과

영향	설명
API 비용 폭주	하루에 수백 달러의 비용이 발생할 수 있음
다른 사용자 사용 불가	요청 큐가 가득 차서 일반 사용자가 답변을 받지 못함
상위 속도 제한 트리거	Claude/OpenAI의 API 속도 제한에 걸려 모든 요청이 느려짐
서비스 크래시	메모리와 CPU 리소스가 고갈됨

2. 전역 빈도 제한

2.1 기본 설정

// ~/.config/openclaw/openclaw.json5
{
  "rateLimit": {
    "enabled": true,
    // 전역 제한: 분당 최대 처리 메시지 수
    "global": {
      "maxRequests": 60,
      "window": "1m"
    }
  }
}

2.2 모델 API 호출 제한

API 요금제에 맞게 상위 제한을 설정합니다:

{
  "rateLimit": {
    "model": {
      // 분당 최대 API 요청 수
      "rpm": 50,
      // 분당 최대 토큰 수
      "tpm": 100000,
      // 일일 최대 요청 수 (0=제한 없음)
      "dailyLimit": 2000,
      // 일일 최대 비용 (달러)
      "dailyCostLimit": 10.00,
      // 제한 도달 시 동작
      "onLimitReached": "queue"  // "queue"=대기열 대기, "reject"=즉시 거부
    }
  }
}

제한에 도달하면 OpenClaw이 사용자에게 안내 메시지를 보냅니다:

{
  "rateLimit": {
    "messages": {
      "rateLimited": "요청이 너무 빈번합니다. 잠시 후 다시 시도해 주세요.",
      "dailyLimitReached": "오늘의 사용 한도가 소진되었습니다. 내일 다시 이용해 주세요.",
      "queueing": "현재 대기 중입니다. 예상 대기 시간은 {waitTime}초입니다."
    }
  }
}

3. 사용자별 제한

3.1 사용자 수준 제한 설정

{
  "rateLimit": {
    "perUser": {
      // 각 사용자의 분당 최대 메시지 수
      "maxRequests": 10,
      "window": "1m",
      // 각 사용자의 시간당 최대 요청 수
      "maxRequestsPerHour": 100,
      // 각 사용자의 일일 최대 토큰 소비
      "dailyTokenLimit": 50000,
      // 쿨다운 시간: 속도 제한 트리거 후 대기해야 하는 시간
      "cooldown": "30s"
    }
  }
}

3.2 VIP 사용자 면제

일부 중요한 사용자나 관리자에게는 더 높은 한도를 설정하거나 면제할 수 있습니다:

{
  "rateLimit": {
    "perUser": {
      "maxRequests": 10,
      "window": "1m"
    },
    // 사용자 화이트리스트: 속도 제한 적용 안 함
    "whitelist": [
      "+8213800138000",       // 전화번호
      "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. 채널별 제한

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 그룹 채팅 특수 처리

그룹 채팅의 메시지 양은 일반적으로 DM보다 훨씬 많으므로 특수 전략이 필요합니다:

{
  "rateLimit": {
    "groupChat": {
      // 그룹에서 분당 최대 응답 메시지 수
      "maxResponses": 5,
      "window": "1m",
      // @멘션된 메시지에만 응답
      "mentionOnly": true,
      // 또는 확률적으로 응답 (가끔 대화에 참여해야 하는 시나리오에 적합)
      "responseRate": 0.3,  // 30% 확률로 응답
      // 연속 메시지 병합: 단시간 내 여러 메시지를 하나의 요청으로 병합
      "batchWindow": "5s"
    }
  }
}

5. 남용 방지 메커니즘

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. 속도 제한 상태 모니터링

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

7. 모범 사례

느슨하게 시작해서 엄격하게: 초기에는 비교적 느슨한 제한을 설정하고, 실제 사용 데이터에 따라 점진적으로 조임
친절한 안내: 속도 제한 시 사용자에게 명확한 안내 메시지를 제공하여 언제 다시 사용할 수 있는지 알려줌
우선순위 큐: VIP 사용자나 관리자의 요청을 우선 처리
계층적 전략: 그룹 채팅은 DM보다 더 엄격한 속도 제한이 필요
비용 안전장치: 일일 비용 상한을 항상 설정하여 예기치 않은 고액 청구서 방지
정기적 조정: 매월 속도 제한 통계를 검토하고 사용자 증가에 따라 한도 조정

합리적인 빈도 제한은 사용자 경험을 제한하는 것이 아니라 모든 사용자가 공정하고 안정적인 서비스를 받을 수 있도록 보장하는 것입니다. 잘 설정된 속도 제한 전략은 OpenClaw 대규모 운영의 기반입니다.