Heartbeat 가이드
Heartbeat는 주기적으로 실행되는 작업으로, 특정 간격으로 코드를 실행하고 싶을 때 사용합니다.
개요
Heartbeat는 OpenClaw에서 제공하는 간단한 반복 실행 메커니즘입니다. Cron과 달리 복잡한 표현식 없이 단순한 간격으로 실행됩니다.
Heartbeat vs Cron
| 특징 | Heartbeat | Cron |
|---|---|---|
| 복잡도 | 단순 (간격만 지정) | 복잡 (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
권장 간격
| 작업 유형 | 권장 간격 |
|---|---|
| 이메일 폴링 | 300-600초 (5-10분) |
| API 상태 확인 | 60-300초 (1-5분) |
| 데이터베이스 정리 | 86400초 (하루) |
| 대기열 처리 | 60-300초 (1-5분) |
참고: