문제 설명
OpenClaw 사용 중 여러 사용자가 동시에 메시지를 보내거나 메시지 양이 많을 때, 로그에 다음과 같은 오류가 나타날 수 있습니다:
[openclaw:gateway] Error calling model API: 429 Too Many Requests
[openclaw:gateway] Rate limit exceeded. Retry after 20 seconds.
[openclaw:gateway] Headers: x-ratelimit-remaining-requests: 0, x-ratelimit-reset-requests: 20s
사용자 측에서는 봇 응답 지연이 크게 증가하거나, 오류 메시지를 받게 됩니다:
봇 응답: 서비스가 일시적으로 바쁩니다. 잠시 후 다시 시도해 주세요.
429 오류는 API 요청이 모델 제공업체의 속도 제한을 초과했음을 의미합니다. AI 모델 제공업체마다 분당 요청 수(RPM), 분당 토큰 수(TPM), 일일 총 호출량 등 서로 다른 제한 정책을 적용합니다.
각 제공업체의 제한 기준
일반적인 제한 (무료/저급 기준):
| 제공업체 | RPM | TPM | 일일 제한 |
|---|---|---|---|
| OpenAI (Tier 1) | 500 | 30,000 | 없음 |
| Anthropic (Build) | 50 | 40,000 | 없음 |
| Google Gemini (Free) | 15 | 32,000 | 1,500 |
실제 제한은 계정 등급과 사용하는 구체적인 모델에 따라 달라집니다.
진단 단계
OpenClaw의 속도 제한 통계를 확인합니다:
openclaw stats rate-limit
출력 예시:
Provider Model RPM Used RPM Limit Status
openai gpt-4o 45/60 60 ⚠️ Warning
anthropic claude-sonnet 12/50 50 ✓ OK
상세한 API 로그를 활성화하여 요청 빈도를 추적합니다:
DEBUG=openclaw:api* openclaw start
최근 1시간의 요청 로그를 확인합니다:
openclaw logs --filter "api" --since 1h
해결 방안
방안 1: 내장 속도 제한기 활성화
OpenClaw에는 속도 제한기가 내장되어 있어, 요청을 보내기 전에 빈도를 사전 제어하여 제공업체의 제한이 트리거되는 것을 방지합니다:
{
"api": {
"rateLimiter": {
"enabled": true,
"strategy": "sliding-window",
"limits": {
"openai": {
"requestsPerMinute": 50,
"tokensPerMinute": 25000
},
"anthropic": {
"requestsPerMinute": 40,
"tokensPerMinute": 35000
}
}
}
}
}
제공업체 실제 한도의 80%로 제한 값을 설정하여 여유를 두는 것을 권장합니다.
방안 2: 자동 재시도 및 백오프 설정
429 오류 발생 시 OpenClaw이 자동으로 대기 후 재시도하도록 합니다:
{
"api": {
"retry": {
"enabled": true,
"maxRetries": 3,
"backoff": {
"type": "exponential",
"initialDelay": 5000,
"maxDelay": 60000,
"factor": 2
},
"retryOn": [429, 500, 502, 503]
}
}
}
이렇게 하면 429 응답을 받았을 때 OpenClaw은 5초 후 첫 번째 재시도, 10초 후 두 번째 재시도, 20초 후 세 번째 재시도를 수행합니다.
방안 3: 사용자별 속도 제한 설정
각 사용자의 메시지 전송 빈도를 제한하여 API 호출을 원천적으로 줄입니다:
{
"users": {
"rateLimit": {
"messagesPerMinute": 10,
"cooldownMessage": "메시지 전송이 너무 빈번합니다. {remaining}초 후에 다시 시도해 주세요."
}
}
}
방안 4: 다중 API Key 순환
여러 API Key를 설정하여 순환 사용함으로써 가용 한도를 배로 늘립니다:
{
"providers": {
"openai": {
"apiKeys": [
"sk-key-1-xxxxx",
"sk-key-2-xxxxx",
"sk-key-3-xxxxx"
],
"keyRotation": "round-robin"
}
}
}
OpenClaw은 두 가지 순환 전략을 지원합니다:
round-robin: 각 Key를 순서대로 번갈아 사용least-used: 현재 사용량이 가장 적은 Key를 우선 사용
특정 Key에서 429 오류가 발생하면 OpenClaw이 자동으로 해당 Key를 건너뛰고 다음 사용 가능한 Key를 사용합니다.
방안 5: 모델 다운그레이드 설정
주 모델이 속도 제한에 걸렸을 때 자동으로 대체 모델로 전환합니다:
{
"models": {
"default": {
"provider": "openai",
"model": "gpt-4o",
"fallback": [
{
"provider": "anthropic",
"model": "claude-sonnet-4-20250514"
},
{
"provider": "openai",
"model": "gpt-4o-mini"
}
]
}
}
}
gpt-4o에서 429 오류가 반환되면 OpenClaw이 자동으로 fallback 목록의 다음 모델을 사용하여 요청을 처리합니다.
방안 6: 요청 큐 설정
동시 요청을 큐에 넣어 순서대로 처리하여 순간적인 요청 수 과다를 방지합니다:
{
"api": {
"queue": {
"enabled": true,
"concurrency": 3,
"maxQueueSize": 100,
"timeout": 120000
}
}
}
concurrency는 동시에 진행되는 API 요청 수를 제어하며, 초과하는 요청은 큐에서 대기합니다.
모니터링 권장사항
대시보드 또는 알림을 설정하여 API 사용 현황을 모니터링합니다:
# 실시간 API 사용 통계 확인
openclaw stats api --watch
# 사용 보고서 내보내기
openclaw stats api --export csv --period 7d > api-usage.csv
정기적으로 API 사용 보고서를 확인하면 한도를 합리적으로 계획하고 적시에 API 계정 등급을 업그레이드하는 데 도움이 됩니다.