OpenClaw 상태 점검 및 자동 재시작 메커니즘

서문

24시간 운영되는 OpenClaw 서비스의 경우, 수동 모니터링만으로는 현실적이지 않습니다. 서비스 상태를 지속적으로 감지하고, 장애 발생 시 자동으로 복구하며, 복구가 불가능한 경우 즉시 알림을 보내는 자동화된 상태 점검 및 복구 체계가 필요합니다. 이 글에서는 OpenClaw의 상태 점검 도구와 자동 재시작 메커니즘을 종합적으로 소개합니다.

1. openclaw doctor 진단 명령어

1.1 기본 사용법

openclaw doctor는 OpenClaw 내장 원스톱 진단 도구로, 서비스의 각 핵심 지표를 자동으로 검사합니다:

openclaw doctor

출력 예시:

OpenClaw Doctor - 상태 진단 보고서
================================

[서비스 상태]
  ✓ OpenClaw 데몬 프로세스 실행 중 (PID: 12345)
  ✓ 실행 시간: 7d 3h 22m
  ✓ 버전: 1.2.0 (최신 버전)

[게이트웨이 검사]
  ✓ Gateway 포트 18789 접근 가능
  ✓ 상태 점검 엔드포인트 응답 정상 (12ms)
  ✓ Web Dashboard 접근 가능

[채널 연결]
  ✓ WhatsApp: 연결됨
  ✓ Telegram: 연결됨
  ⚠ Discord: 재연결 중 (마지막 연결 끊김: 2분 전)

[모델 서비스]
  ✓ Claude API: 사용 가능 (지연: 320ms)
  ✓ API Key: 유효
  ⚠ 이번 달 Token 사용량: 85% (할당량 근접)

[리소스 사용량]
  ✓ 메모리: 198MB / 512MB (38%)
  ✓ CPU: 평균 3.2%
  ✓ 디스크: 로그 디렉터리 256MB
  ✓ 파일 디스크립터: 128 / 65536

[최근 오류]
  ⚠ 지난 1시간 동안 2건의 API 타임아웃
  ✓ 지난 24시간 심각한 오류 없음

진단 결과: 기본적으로 정상 (경고 2건)

1.2 상세 검사 모드

# 모든 검사를 실행하고 상세 정보 출력
openclaw doctor --verbose

# 특정 모듈만 검사
openclaw doctor --check gateway
openclaw doctor --check channels
openclaw doctor --check model
openclaw doctor --check resources
openclaw doctor --check skills

# JSON 형식으로 출력(스크립트 처리에 편리)
openclaw doctor --format json

1.3 스크립트에서 사용

openclaw doctor의 종료 코드를 스크립트에서 활용할 수 있습니다:

종료 코드	의미
0	모두 정상
1	경고가 있지만 서비스 사용 가능
2	심각한 문제가 있으며 서비스에 영향 가능
3	서비스 사용 불가

#!/bin/bash
openclaw doctor --quiet
EXIT_CODE=$?

case $EXIT_CODE in
    0) echo "서비스 정상" ;;
    1) echo "경고 존재, 주의 필요" ;;
    2) echo "심각한 문제, 처리 필요" ;;
    3) echo "서비스 사용 불가, 긴급 복구 필요!" ;;
esac

2. 상태 점검 엔드포인트

2.1 HTTP 상태 점검

OpenClaw Gateway는 여러 상태 점검 엔드포인트를 제공합니다:

# 기본 생존 검사(liveness)
curl -s http://localhost:18789/health
# {"status":"ok","uptime":604800}

# 준비 검사(readiness)
curl -s http://localhost:18789/health/ready
# {"status":"ready","channels":{"whatsapp":"connected","telegram":"connected"}}

# 상세 상태
curl -s http://localhost:18789/health/detail

2.2 커스텀 상태 점검 기준

설정에서 어떤 조건이 "정상"인지를 정의할 수 있습니다:

// ~/.config/openclaw/openclaw.json5
{
  "health": {
    // 최소 하나의 채널이 연결되어야 준비 완료로 간주
    "minConnectedChannels": 1,
    // 메모리 사용량이 이 비율을 초과하면 비정상으로 표시
    "maxMemoryPercent": 90,
    // 모델 API 연속 실패 횟수가 이 값을 초과하면 비정상으로 표시
    "maxConsecutiveModelErrors": 5,
    // 상태 점검 타임아웃
    "timeout": 5000
  }
}

3. Watchdog 감시 메커니즘

3.1 OpenClaw 내장 Watchdog

OpenClaw은 자체 상태를 모니터링하고 이상 시 자동으로 복구하는 워치독 기능을 내장하고 있습니다:

{
  "watchdog": {
    "enabled": true,
    // 검사 간격
    "interval": "60s",
    // 자동 재시작 조건
    "restartOn": {
      // 메모리 초과 시 자동 재시작
      "memoryExceeded": true,
      "memoryThreshold": "450MB",
      // 모든 채널 연결 끊김 시 자동 재시작
      "allChannelsDisconnected": true,
      // 모델 연속 실패 시 자동 재시작
      "consecutiveModelErrors": 10,
      // 응답 타임아웃 비율이 너무 높을 때 자동 재시작
      "timeoutRateThreshold": 0.5
    },
    // 재시작 쿨다운 시간(빈번한 재시작 방지)
    "restartCooldown": "5m",
    // 최대 연속 재시작 횟수
    "maxRestarts": 3,
    // 최대 재시작 횟수 초과 시 동작
    "onMaxRestartsExceeded": "alert"  // "alert" 또는 "stop"
  }
}

3.2 외부 Watchdog 스크립트

더 안정적인 모니터링을 위해 OpenClaw 프로세스와 독립적인 워치독을 사용하는 것을 권장합니다:

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

HEALTH_URL="http://localhost:18789/health"
LOG="/var/log/openclaw-watchdog.log"
MAX_FAILURES=3
FAILURE_COUNT=0

check_health() {
    RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null)
    if [ $? -ne 0 ]; then
        return 1
    fi
    STATUS=$(echo "$RESPONSE" | jq -r '.status' 2>/dev/null)
    if [ "$STATUS" != "ok" ]; then
        return 1
    fi
    return 0
}

log_msg() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG"
}

if ! check_health; then
    FAILURE_COUNT=$((FAILURE_COUNT + 1))
    log_msg "상태 점검 실패 (연속 $FAILURE_COUNT 회)"

    if [ $FAILURE_COUNT -ge $MAX_FAILURES ]; then
        log_msg "연속 $MAX_FAILURES 회 실패, 서비스 재시작 중..."
        openclaw restart
        sleep 20

        if check_health; then
            log_msg "재시작 성공, 서비스 복구됨"
            FAILURE_COUNT=0
        else
            log_msg "재시작 후에도 사용 불가, 알림 전송"
            # 알림 전송(Telegram/이메일/Webhook)
            curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
                -d chat_id="${CHAT_ID}" \
                -d text="OpenClaw 서비스 재시작 실패, 수동 개입 필요! 서버: $(hostname)"
        fi
    fi
else
    FAILURE_COUNT=0
fi

정기 실행 설정:

chmod +x /usr/local/bin/openclaw-watchdog.sh

# 2분마다 실행
crontab -e
# */2 * * * * /usr/local/bin/openclaw-watchdog.sh

3.3 Systemd Watchdog 통합

Systemd로 OpenClaw을 관리하는 경우, Systemd의 워치독 기능을 활용할 수 있습니다:

# /etc/systemd/system/openclaw.service
[Service]
WatchdogSec=120        # 워치독 타임아웃: 120초
Restart=on-failure
RestartSec=10
StartLimitBurst=5
StartLimitIntervalSec=300

# 워치독 타임아웃 또는 서비스 크래시 시 실행
ExecStartPost=/usr/local/bin/openclaw-health-notify.sh start
ExecStopPost=/usr/local/bin/openclaw-health-notify.sh stop

OpenClaw이 정기적으로 Systemd에 하트비트 신호를 보내야 합니다. 설정에서 활성화합니다:

{
  "watchdog": {
    "systemdNotify": true  // 자동으로 systemd에 워치독 하트비트 전송
  }
}

4. 채널 자동 재연결

4.1 내장 재연결 메커니즘

OpenClaw은 각 채널 연결에 대해 내장 자동 재연결 로직을 제공합니다:

{
  "channels": {
    "reconnect": {
      "enabled": true,
      // 초기 재연결 지연
      "initialDelay": "5s",
      // 최대 재연결 지연(지수 백오프 상한)
      "maxDelay": "5m",
      // 최대 재연결 시도 횟수(0=무제한)
      "maxAttempts": 0,
      // 백오프 계수
      "backoffFactor": 2
    }
  }
}

재연결 로그 예시:

[INFO] [channel:discord] 연결 끊김, 5s 후 재연결 시도 (1/∞)
[INFO] [channel:discord] 재연결 중...
[WARN] [channel:discord] 재연결 실패, 10s 후 재시도 (2/∞)
[INFO] [channel:discord] 재연결 중...
[INFO] [channel:discord] 재연결 성공, 중단 시간: 18s

4.2 채널 연결 상태 모니터링

# 모든 채널 연결 상태 확인
openclaw status

# 출력
# 채널 상태:
#   WhatsApp  ✓ 연결됨 (uptime: 7d)
#   Telegram  ✓ 연결됨 (uptime: 7d)
#   Discord   ⚠ 재연결 중 (끊김: 2m)

# 특정 채널 수동 재연결
openclaw channel reconnect discord

5. 알림 설정

5.1 내장 알림 채널

{
  "alerts": {
    "enabled": true,
    // 알림 방식
    "channels": [
      {
        "type": "telegram",
        "botToken": "YOUR_BOT_TOKEN",
        "chatId": "YOUR_CHAT_ID"
      },
      {
        "type": "email",
        "smtp": {
          "host": "smtp.example.com",
          "port": 587,
          "user": "[email protected]",
          "pass": "password"
        },
        "to": "[email protected]"
      },
      {
        "type": "webhook",
        "url": "https://hooks.slack.com/services/xxx"
      }
    ],
    // 알림 트리거 조건
    "rules": {
      "serviceDown": true,
      "channelDisconnected": true,
      "highMemory": true,
      "highErrorRate": true,
      "certificateExpiring": true
    }
  }
}

5.2 알림 억제

단시간에 대량의 중복 알림을 방지합니다:

{
  "alerts": {
    // 동일 유형 알림의 최소 간격
    "throttle": "15m",
    // 복구 알림
    "notifyOnRecover": true
  }
}

6. 상태 점검 모범 사례

다층 점검: 내장 watchdog + 외부 cron 스크립트 + Uptime Kuma, 다중 보장
적절한 간격: 상태 점검을 너무 빈번하게 하지 않고, 1-2분에 한 번이면 충분
점진적 복구: 먼저 채널 재연결을 시도하고, 다음으로 서비스 재시작, 마지막에 수동 알림 전송
쿨다운 기간: 재시작 쿨다운 시간을 설정하여 "장애 감지-재시작-다시 장애-다시 재시작" 무한 루프 방지
정기 훈련: 능동적으로 장애를 시뮬레이션(예: kill -9)하여 자동 복구 메커니즘이 유효한지 검증
로그 보존: watchdog 스크립트의 작업 로그를 별도로 보관하여 사후 분석에 활용

안정적인 상태 점검 및 자동 복구 메커니즘을 구축하면 OpenClaw 서비스의 가용성을 99.9%에 가깝게 달성할 수 있으며, 수동 운영 부담을 크게 줄일 수 있습니다.