Heartbeat 가이드

Heartbeat는 주기적으로 실행되는 작업으로, 특정 간격으로 코드를 실행하고 싶을 때 사용합니다.

개요

Heartbeat는 OpenClaw에서 제공하는 간단한 반복 실행 메커니즘입니다. Cron과 달리 복잡한 표현식 없이 단순한 간격으로 실행됩니다.

Heartbeat vs Cron

Heartbeat를 사용해야 하는 경우:

• 간단한 주기 실행: 매 N초/분/시간마다 실행
• 상태 확인: 서비스 상태를 주기적으로 확인
• 폴링: 이메일, API 등을 주기적으로 확인
• 실시간 처리: 데이터를 주기적으로 처리

설정 방법

기본 설정

triggers:
  - type: heartbeat
    interval: 300  # 5분마다 (초 단위)
    action: check_email

간격 단위

interval: 30        # 30초마다
interval: 300       # 5분마다
interval: 1800      # 30분마다
interval: 3600      # 1시간마다

조건부 실행

triggers:
  - type: heartbeat
    interval: 600
    condition: |
      import requests
      return requests.get("https://api.example.com/health").status_code == 200
    action: process_data

실전 예시

이메일 폴링

triggers:
  - type: heartbeat
    interval: 300
    action: check_new_emails

서비스 상태 확인

triggers:
  - type: heartbeat
    interval: 60
    action: check_service_health

주기적 데이터 처리

triggers:
  - type: heartbeat
    interval: 900
    action: process_queue

고급 설정

동적 간격

triggers:
  - type: heartbeat
    interval: |
      import datetime
      hour = datetime.datetime.now().hour
      if 9 <= hour <= 18:  # 업무시간
        return 300  # 5분
      else:  # 비업무시간
        return 1800  # 30분
    action: check_updates

타임아웃 설정

triggers:
  - type: heartbeat
    interval: 300
    timeout: 240
    action: sync_data

실패 시 재시도

triggers:
  - type: heartbeat
    interval: 300
    retry_on_failure: true
    max_retries: 3
    retry_delay: 60
    action: critical_task

모니터링

# 실행 중인 heartbeat 목록
openclaw heartbeat list

# 특정 heartbeat 상태
openclaw heartbeat status check_email

# heartbeat 로그
openclaw heartbeat logs check_email

트러블슈팅

실행이 예상보다 빈번함

# 수정 전
interval: 10   # 10초마다

# 수정 후
interval: 300  # 5분마다

작업이 완료되기 전에 다시 실행됨

triggers:
  - type: heartbeat
    interval: 300
    timeout: 240
    wait_for_completion: true
    action: long_running_task

특정 시간에만 실행하고 싶음

특정 시간 실행에는 Cron 사용을 권장합니다:

triggers:
  - type: cron
    expression: "0 9 * * *"
    action: morning_task

권장 간격

참고:

• 공식 문서: Automation