OpenClaw 로그 분석 및 장애 진단 기법

서문

OpenClaw에 비정상적인 동작이 발생했을 때(메시지 미응답, 응답 지연, 채널 연결 끊김 등) 로그는 가장 중요한 문제 해결 도구입니다. 이 글에서는 OpenClaw의 로그 형식을 이해하고, 핵심 필드를 식별하며, 일반적인 오류 패턴을 빠르게 진단하는 기법을 체계적으로 설명합니다.

1. 로그 형식 상세

1.1 표준 텍스트 형식

OpenClaw은 기본적으로 구조화된 텍스트 형식으로 로그를 출력하며, 각 줄에는 다음 필드가 포함됩니다:

[2026-03-14 09:15:32.456] [INFO] [gateway] 메시지 수신 (WhatsApp) msgId=msg_a1b2c3

각 필드의 의미:

1.2 JSON 형식

log.format: "json"을 설정하면 로그가 JSON 형식으로 출력되어, 프로그래밍 방식의 분석에 더 편리합니다:

{
  "timestamp": "2026-03-14T09:15:32.456Z",
  "level": "info",
  "component": "gateway",
  "message": "메시지 수신",
  "meta": {
    "channel": "whatsapp",
    "msgId": "msg_a1b2c3",
    "from": "+8613800138000"
  }
}

1.3 핵심 컴포넌트 식별자

OpenClaw 로그에서 자주 볼 수 있는 컴포넌트(component):

2. 핵심 로그 필드 해석

2.1 메시지 생명주기 추적

각 메시지에는 OpenClaw 내부에서 고유한 traceId가 할당되어 전체 처리 체인을 관통합니다. traceId를 통해 하나의 메시지가 수신부터 응답까지의 완전한 과정을 연결할 수 있습니다:

# traceId로 전체 체인 필터링
openclaw logs --since 1h | grep "traceId=trace_x7y8z9"

출력 예시:

[09:15:32.456] [INFO] [gateway] 메시지 수신 traceId=trace_x7y8z9 channel=whatsapp
[09:15:32.480] [INFO] [memory] 대화 기록 로딩 traceId=trace_x7y8z9 historyCount=12
[09:15:32.510] [INFO] [model] API 요청 전송 traceId=trace_x7y8z9 model=claude-3.5-sonnet
[09:15:34.230] [INFO] [model] API 응답 수신 traceId=trace_x7y8z9 latency=1720ms tokens=285
[09:15:34.250] [INFO] [gateway] 응답 전송 traceId=trace_x7y8z9 channel=whatsapp

2.2 성능 관련 필드

모델 호출 로그에서 다음 필드는 성능 분석에 매우 중요합니다:

• latency: 요청 전송부터 완전한 응답 수신까지의 소요 시간(밀리초)
• inputTokens: 입력 Token 수, 컨텍스트 길이를 반영
• outputTokens: 출력 Token 수
• cost: 이번 호출의 추정 비용(달러)
• retryCount: 재시도 횟수, 0이 아닌 값은 최초 요청 실패를 의미

3. 일반적인 오류 패턴 및 진단 방법

3.1 모델 API 인증 실패

[ERROR] [model] API 호출 실패: 401 Unauthorized provider=claude error="Invalid API key"

진단 방법:

# API Key 설정 확인
openclaw config get model.apiKey
# 키가 올바른 접두사로 시작하는지 확인(예: sk-ant-)

# API Key 유효성 테스트
curl -H "x-api-key: YOUR_KEY" https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

3.2 속도 제한(Rate Limit)

[WARN] [model] API 속도 제한 provider=openai statusCode=429 retryAfter=30s
[WARN] [model] 대기 중 queueLength=5 estimatedWait=45s

진단 방법:

# 최근 1시간의 429 오류 횟수 확인
openclaw logs --since 1h --level warn | grep "429" | wc -l

# 요청 빈도 확인
openclaw logs --since 1h --component model | grep "API 요청 전송" | wc -l

해결 방안: 동시 요청 수 감소, 요청 큐 활성화, 더 높은 할당량의 API 플랜으로 전환.

3.3 채널 연결 끊김

[ERROR] [channel:whatsapp] WebSocket 연결 끊김 code=1006 reason="Connection lost"
[INFO] [channel:whatsapp] 재연결 시도 attempt=1/5
[INFO] [channel:whatsapp] 재연결 성공 downtime=8s

진단 방법:

# 특정 채널의 연결 끊김 기록 확인
openclaw logs --since 24h --component channel:whatsapp --level error

# 연결 끊김 빈도 확인
openclaw logs --since 7d | grep "연결 끊김" | awk '{print $1}' | sort | uniq -c

연결 끊김이 빈번하다면, 네트워크 안정성과 서버 방화벽 설정을 확인하세요.

3.4 메모리 오버플로 경고

[WARN] [gateway] 메모리 사용량 과다 heapUsed=480MB heapTotal=512MB percentage=94%
[ERROR] [gateway] OOM: 메모리 한도 근접, 캐시 정리 중

진단 방법:

# 메모리 추이 확인
openclaw logs --since 6h | grep "heapUsed"

# 메모리 누수 여부 확인(메모리가 지속적으로 증가하고 해제되지 않는 경우)
openclaw logs --since 24h | grep "heapUsed" | awk -F'heapUsed=' '{print $2}' | head -20

3.5 스킬 실행 실패

[ERROR] [skill] 스킬 실행 타임아웃 skillName=weather timeout=10000ms
[ERROR] [skill] 스킬 런타임 오류 skillName=rss error="ECONNREFUSED 127.0.0.1:3000"

진단 방법:

# 특정 스킬의 오류 기록 확인
openclaw logs --since 24h --component skill | grep "weather"

# openclaw doctor로 스킬 상태 확인
openclaw doctor --check skills

4. 효율적인 로그 분석 기법

4.1 빠른 오류 진단

# 최근 오류 요약 확인
openclaw logs --since 1h --level error

# 컴포넌트별 오류 수 통계
openclaw logs --since 24h --level error --format json | jq '.component' | sort | uniq -c | sort -rn

4.2 응답 지연 분석

# 응답 시간이 5초를 초과하는 요청 찾기
openclaw logs --since 1h --component model | grep "latency=" | awk -F'latency=' '{
  split($2, a, "ms"); if(a[1] > 5000) print $0
}'

4.3 openclaw doctor로 자동 진단

openclaw doctor 명령어는 최근 로그를 자동으로 스캔하여 일반적인 문제를 식별합니다:

openclaw doctor

# 출력 예시
# ✓ 서비스 상태: 실행 중 (uptime: 3d 12h)
# ✓ 게이트웨이 포트: 18789 접근 가능
# ⚠ 최근 1시간 동안 3건의 API 429 오류
# ✓ 모든 채널 연결 정상
# ⚠ 메모리 사용량 78%, 주의 필요
# ✓ 디스크 공간 충분

4.4 외부 분석용 로그 내보내기

# 최근 24시간의 JSON 형식 로그 내보내기
openclaw logs --since 24h --format json > /tmp/openclaw-logs-export.json

# jq와 결합하여 복잡한 쿼리 수행
cat /tmp/openclaw-logs-export.json | jq 'select(.level == "error") | {time: .timestamp, msg: .message, component: .component}'

5. 로그 분석 모범 사례

1. 기준선 설정: 시스템이 정상 작동할 때 핵심 지표(평균 지연, 오류율, 메모리 사용량)를 기록하여, 문제 발생 시 비교 기준으로 활용
2. 계층적 조사: 먼저 ERROR 수준으로 범위를 좁히고, 다음에 DEBUG 수준으로 전환하여 세부 사항 확인
3. traceId 활용: 단일 요청의 전체 체인을 추적하여, 대량의 로그에 압도되지 않기
4. 정기 점검: 매주 몇 분간 WARN 수준 로그를 검토하여, 문제가 악화되기 전에 징후 발견
5. 자동화 알림: 모니터링 시스템과 결합하여 핵심 오류 패턴에 대한 자동 알림 설정, 수동 순찰 부담 감소

이러한 로그 분석 기법을 숙지하면, 대부분의 OpenClaw 운영 문제를 몇 분 내에 진단할 수 있어, 장애 복구 시간을 크게 단축할 수 있습니다.