OpenClaw 서비스 모니터링 및 알림 설정 튜토리얼

서문

OpenClaw는 장기간 실행되는 AI 어시스턴트 서비스로서 안정성이 매우 중요합니다. 서비스가 중단되면 연결된 모든 채팅 채널이 응답을 잃게 됩니다. 본 글에서는 처음부터 완벽한 모니터링 및 알림 체계를 구축하여 문제가 발생했을 때 즉시 발견하고 처리할 수 있도록 도와드리겠습니다.

1. 헬스 체크 엔드포인트

OpenClaw Gateway는 기본적으로 18789 포트에서 실행되며, 내장된 헬스 체크 엔드포인트를 제공합니다.

1.1 기본 헬스 체크

# 서비스 생존 여부 확인
curl -s http://localhost:18789/health

# 예상 응답
# {"status":"ok","uptime":3600,"version":"1.2.0"}

1.2 상세 상태 확인

# 각 채널 연결 상태를 포함한 상세 상태 정보 조회
curl -s http://localhost:18789/health/detail | jq .

응답 예시:

{
  "status": "ok",
  "uptime": 86400,
  "version": "1.2.0",
  "channels": {
    "whatsapp": "connected",
    "telegram": "connected",
    "discord": "connected"
  },
  "model": {
    "provider": "claude",
    "status": "available"
  },
  "memory": {
    "heapUsed": "128MB",
    "heapTotal": "256MB"
  }
}

2. 업타임 모니터링 방안

2.1 Cron 정기 점검 사용

가장 간단한 모니터링 방법은 crontab을 통해 서비스 상태를 정기적으로 확인하는 것입니다:

# crontab 편집
crontab -e

# 5분마다 확인하고, 실패 시 이메일 알림 발송
*/5 * * * * curl -sf http://localhost:18789/health > /dev/null || echo "OpenClaw 서비스 이상! 시간: $(date)" | mail -s "OpenClaw Alert" [email protected]

장애 감지 시 자동으로 서비스를 재시작하려면:

#!/bin/bash
# /usr/local/bin/openclaw-watchdog.sh 로 저장

HEALTH_URL="http://localhost:18789/health"
LOG_FILE="/var/log/openclaw-watchdog.log"

if ! curl -sf --max-time 10 "$HEALTH_URL" > /dev/null 2>&1; then
    echo "[$(date)] 헬스 체크 실패, OpenClaw를 재시작합니다..." >> "$LOG_FILE"
    openclaw restart
    sleep 15
    if curl -sf --max-time 10 "$HEALTH_URL" > /dev/null 2>&1; then
        echo "[$(date)] 재시작 성공, 서비스가 복구되었습니다" >> "$LOG_FILE"
    else
        echo "[$(date)] 재시작 후에도 서비스를 사용할 수 없습니다. 수동 개입이 필요합니다!" >> "$LOG_FILE"
        # 긴급 알림 발송
        curl -s -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
            -d chat_id="<CHAT_ID>" \
            -d text="🚨 OpenClaw 서비스 재시작 실패, 수동 개입이 필요합니다!"
    fi
fi

# crontab에 추가, 3분마다 실행
*/3 * * * * /usr/local/bin/openclaw-watchdog.sh

2.2 Uptime Kuma를 이용한 모니터링

Uptime Kuma는 아름다운 웹 인터페이스를 제공하는 오픈소스 모니터링 도구입니다.

# Docker로 Uptime Kuma 배포
docker run -d \
  --name uptime-kuma \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  louislam/uptime-kuma:latest

Uptime Kuma에서 모니터링 항목 추가:

설정 항목	값
모니터링 유형	HTTP(s)
이름	OpenClaw Gateway
URL	`http://서버IP:18789/health`
하트비트 간격	60초
재시도 횟수	3
타임아웃	10초
예상 상태 코드	200

3. Prometheus 메트릭 수집

3.1 Prometheus 엔드포인트 활성화

OpenClaw 설정 파일에서 Prometheus 메트릭 내보내기를 활성화합니다:

// ~/.config/openclaw/openclaw.json5
{
  "monitoring": {
    "prometheus": {
      "enabled": true,
      "port": 9191,
      "path": "/metrics"
    }
  }
}

서비스를 재시작하여 설정을 적용합니다:

openclaw restart

3.2 사용 가능한 메트릭 확인

curl -s http://localhost:9191/metrics

OpenClaw가 내보내는 주요 메트릭:

메트릭명	유형	설명
`openclaw_messages_total`	Counter	처리된 총 메시지 수
`openclaw_response_duration_seconds`	Histogram	응답 시간 분포
`openclaw_active_channels`	Gauge	활성 채널 수
`openclaw_model_requests_total`	Counter	모델 API 호출 횟수
`openclaw_model_errors_total`	Counter	모델 API 오류 횟수
`openclaw_memory_heap_bytes`	Gauge	Node.js 힙 메모리 사용량
`openclaw_skills_loaded`	Gauge	로드된 스킬 수

3.3 Prometheus 수집 설정

# prometheus.yml
scrape_configs:
  - job_name: 'openclaw'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9191']
    metrics_path: '/metrics'

4. Grafana 시각화 대시보드

4.1 Grafana 설치

# Docker 방식으로 설치
docker run -d \
  --name grafana \
  --restart=always \
  -p 3000:3000 \
  -v grafana-storage:/var/lib/grafana \
  grafana/grafana-oss:latest

4.2 OpenClaw 대시보드 생성

Grafana에 Prometheus 데이터 소스를 추가한 후 다음 주요 패널을 생성합니다:

메시지 처리 속도 패널 (PromQL):

rate(openclaw_messages_total[5m])

평균 응답 지연 패널:

histogram_quantile(0.95, rate(openclaw_response_duration_seconds_bucket[5m]))

모델 호출 오류율 패널:

rate(openclaw_model_errors_total[5m]) / rate(openclaw_model_requests_total[5m]) * 100

메모리 사용 패널:

openclaw_memory_heap_bytes / 1024 / 1024

4.3 권장 대시보드 레이아웃

대시보드를 네 개 영역으로 나누는 것을 권장합니다:

개요 행: 서비스 상태, 업타임, 활성 채널 수, 로드된 스킬 수
메시지 통계 행: 메시지 속도, 채널별 메시지 수, 응답 지연 분포
모델 호출 행: API 호출 속도, 오류율, 제공업체별 호출 비율
리소스 모니터링 행: 메모리 사용량, CPU 사용량(Node Exporter 연동 필요), 디스크 공간

5. 알림 통지 설정

5.1 Grafana 알림 규칙

Grafana에서 알림 규칙을 설정합니다:

# 서비스 불가용 알림
- alert: OpenClawDown
  expr: up{job="openclaw"} == 0
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "OpenClaw 서비스 불가용"
    description: "OpenClaw 서비스가 2분 이상 응답을 중단했습니다"

# 높은 오류율 알림
- alert: OpenClawHighErrorRate
  expr: rate(openclaw_model_errors_total[5m]) > 0.1
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "OpenClaw 모델 호출 오류율 과다"

# 메모리 알림
- alert: OpenClawHighMemory
  expr: openclaw_memory_heap_bytes > 512 * 1024 * 1024
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "OpenClaw 메모리 사용량 512MB 초과"

5.2 Telegram 알림 통지

# Grafana에서 Telegram 연락 포인트 설정
# 설정 -> 연락 포인트 -> 새로 만들기
# 유형: Telegram
# Bot Token: 본인의 Bot Token
# Chat ID: 본인의 Chat ID

5.3 Webhook 알림 통지

기업용 메신저 등을 사용하는 경우 Webhook 알림을 설정할 수 있습니다:

# 기업용 Webhook 예시
curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msgtype": "markdown",
    "markdown": {
      "content": "## OpenClaw 알림\n> 서비스 상태 이상\n> 시간: '"$(date)"'\n> 즉시 확인해 주세요"
    }
  }'

5.4 이메일 알림 통지

Grafana 설정 파일에서 이메일을 활성화합니다:

# /etc/grafana/grafana.ini
[smtp]
enabled = true
host = smtp.example.com:587
user = [email protected]
password = your_password
from_address = [email protected]
from_name = OpenClaw Monitor

6. 리소스 사용 모니터링

6.1 Node Exporter를 이용한 시스템 리소스 모니터링

# Node Exporter 설치
docker run -d \
  --name node-exporter \
  --restart=always \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  quay.io/prometheus/node-exporter:latest \
  --path.rootfs=/host

6.2 주요 시스템 지표

관심 지표	정상 범위	알림 임계값
CPU 사용률	< 50%	> 80% 5분 지속
메모리 사용률	< 70%	> 90% 5분 지속
디스크 사용률	< 80%	> 90%
네트워크 연결 수	< 1000	> 5000

6.3 OpenClaw 로그 모니터링

openclaw logs 명령어와 결합하여 이상 로그를 모니터링합니다:

# 실시간 오류 로그 모니터링
openclaw logs | grep -i "error\|warn\|fail" --line-buffered

# Loki + Promtail을 이용한 로그 수집 (선택 사항)
# OpenClaw 로그를 Loki로 전달하여 중앙 관리 및 조회

7. 모니터링 체계 요약

완벽한 OpenClaw 모니터링 체계에는 다음 계층이 포함되어야 합니다:

┌─────────────────────────────────────────────┐
│              알림 통지 계층                    │
│    Telegram / Email / Webhook / 메신저        │
├─────────────────────────────────────────────┤
│              시각화 계층                       │
│           Grafana Dashboard                  │
├─────────────────────────────────────────────┤
│              데이터 수집 계층                   │
│     Prometheus + Node Exporter + Loki        │
├─────────────────────────────────────────────┤
│              서비스 계층                       │
│     OpenClaw Gateway (:18789)                │
│     Prometheus Metrics (:9191)               │
└─────────────────────────────────────────────┘

위의 설정을 통해 OpenClaw 서비스에 대한 전방위적인 모니터링을 구현하여 어떠한 이상 상황도 즉시 발견하고 처리할 수 있습니다. 가장 간단한 cron 헬스 체크부터 시작하여 점차 완벽한 Prometheus + Grafana 솔루션으로 업그레이드하는 것을 권장합니다.