Cron vs Heartbeat: 언제 무엇을 사용할지

Heartbeat와 cron 작업 모두 일정에 따라 작업을 실행할 수 있습니다. 이 가이드는 사용 사례에 적합한 메커니즘을 선택하는 데 도움이 됩니다.

빠른 결정 가이드

사용 사례권장 사항이유
30분마다 받은편지함 확인Heartbeat다른 확인과 배치, 컨텍스트 인식
정확히 오전 9시에 일일 보고서 전송Cron (isolated)정확한 타이밍 필요
다가오는 이벤트에 대한 일정 모니터링Heartbeat주기적 인식에 자연스럽게 맞음
주간 심층 분석 실행Cron (isolated)독립 작업, 다른 모델 사용 가능
20분 후에 알림Cron (main, --at)정확한 타이밍의 일회성
백그라운드 프로젝트 상태 확인Heartbeat기존 사이클에 편승

Heartbeat: 주기적 인식

Heartbeat는 정기적인 간격 (기본값: 30분)으로 main session에서 실행됩니다. Agent가 항목을 확인하고 중요한 것을 표면화하도록 설계되었습니다.

Heartbeat를 사용해야 할 때

  • 여러 주기적 확인: 받은편지함, 일정, 날씨, 알림, 프로젝트 상태를 확인하는 5개의 별도 cron 작업 대신 단일 heartbeat가 모두 배치할 수 있습니다.
  • 컨텍스트 인식 결정: Agent는 전체 main session 컨텍스트를 가지므로 긴급한 것과 기다릴 수 있는 것에 대해 현명한 결정을 내릴 수 있습니다.
  • 대화 연속성: Heartbeat 실행은 동일한 세션을 공유하므로 agent가 최근 대화를 기억하고 자연스럽게 후속 조치를 취할 수 있습니다.
  • 낮은 오버헤드 모니터링: 하나의 heartbeat가 많은 작은 폴링 작업을 대체합니다.

Heartbeat 장점

  • 여러 확인 배치: 하나의 agent 턴에서 받은편지함, 일정, 알림을 함께 검토할 수 있습니다.
  • API 호출 감소: 단일 heartbeat가 5개의 isolated cron 작업보다 저렴합니다.
  • 컨텍스트 인식: Agent는 작업 중인 내용을 알고 그에 따라 우선순위를 지정할 수 있습니다.
  • 스마트 억제: 주의가 필요한 것이 없으면 agent는 HEARTBEAT_OK로 응답하고 메시지가 전달되지 않습니다.
  • 자연스러운 타이밍: 큐 로드에 따라 약간 표류하지만 대부분의 모니터링에는 괜찮습니다.

Heartbeat 예제: HEARTBEAT.md 체크리스트

# Heartbeat 체크리스트

- 긴급 메시지에 대한 이메일 확인
- 다음 2시간 이내 이벤트에 대한 일정 검토
- 백그라운드 작업이 완료되면 결과 요약
- 8시간 이상 유휴 상태이면 간단한 확인 전송

Agent는 각 heartbeat에서 이것을 읽고 한 번의 턴으로 모든 항목을 처리합니다.

Heartbeat 구성

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 간격
        target: "last",      // 알림을 전달할 위치
        activeHours: { start: "08:00", end: "22:00" }  // 선택 사항
      }
    }
  }
}

전체 구성은 Heartbeat를 참조하세요.

Cron: 정확한 일정

Cron 작업은 정확한 시간에 실행되며 main 컨텍스트에 영향을 주지 않고 isolated 세션에서 실행될 수 있습니다.

Cron을 사용해야 할 때

  • 정확한 타이밍 필요: "매주 월요일 오전 9시에 전송" ("9시경"이 아닌 정확히).
  • 독립 작업: 대화 컨텍스트가 필요하지 않은 작업.
  • 다른 모델/thinking: 더 강력한 모델이 필요한 무거운 분석.
  • 일회성 알림: --at로 "20분 후에 알림".
  • 시끄럽거나 빈번한 작업: Main session 기록을 어지럽힐 수 있는 작업.
  • 외부 트리거: Agent가 활성 상태인지 여부와 독립적으로 실행되어야 하는 작업.

Cron 장점

  • 정확한 타이밍: 시간대 지원이 있는 5필드 cron 표현식.
  • 세션 격리: Main 기록을 오염시키지 않고 cron:<jobId>에서 실행.
  • 모델 오버라이드: 작업당 더 저렴하거나 더 강력한 모델 사용.
  • 전달 제어: 채널로 직접 전달 가능; 기본적으로 여전히 main에 요약을 게시 (구성 가능).
  • Agent 컨텍스트 불필요: Main session이 유휴 상태이거나 압축되어도 실행.
  • 일회성 지원: 정확한 미래 타임스탬프를 위한 --at.

Cron 예제: 일일 아침 브리핑

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "America/New_York" \
  --session isolated \
  --message "Generate today's briefing: weather, calendar, top emails, news summary." \
  --model opus \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

이것은 뉴욕 시간 정확히 오전 7시에 실행되며, 품질을 위해 Opus를 사용하고, WhatsApp으로 직접 전달합니다.

Cron 예제: 일회성 알림

openclaw cron add \
  --name "Meeting reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: standup meeting starts in 10 minutes." \
  --wake now \
  --delete-after-run

전체 CLI 참조는 Cron 작업을 참조하세요.

결정 순서도

작업이 정확한 시간에 실행되어야 합니까?
  예 -> Cron 사용
  아니오  -> 계속...

작업이 main session에서 격리되어야 합니까?
  예 -> Cron (isolated) 사용
  아니오  -> 계속...

이 작업을 다른 주기적 확인과 배치할 수 있습니까?
  예 -> Heartbeat 사용 (HEARTBEAT.md에 추가)
  아니오  -> Cron 사용

일회성 알림입니까?
  예 -> --at를 사용한 Cron 사용
  아니오  -> 계속...

다른 모델 또는 thinking 레벨이 필요합니까?
  예 -> --model/--thinking을 사용한 Cron (isolated) 사용
  아니오  -> Heartbeat 사용

둘 다 결합

가장 효율적인 설정은 둘 다 사용합니다:

  1. Heartbeat는 30분마다 한 번의 배치된 턴으로 일상적인 모니터링 (받은편지함, 일정, 알림)을 처리합니다.
  2. Cron은 정확한 일정 (일일 보고서, 주간 검토)과 일회성 알림을 처리합니다.

예제: 효율적인 자동화 설정

HEARTBEAT.md (30분마다 확인):

# Heartbeat 체크리스트
- 긴급 이메일에 대한 받은편지함 스캔
- 다음 2시간 이내 이벤트에 대한 일정 확인
- 보류 중인 작업 검토
- 8시간 이상 조용하면 가벼운 확인

Cron 작업 (정확한 타이밍):

# 오전 7시 일일 아침 브리핑
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --deliver

# 월요일 오전 9시 주간 프로젝트 검토
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# 일회성 알림
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster: 승인이 있는 결정론적 워크플로우

Lobster는 결정론적 실행과 명시적 승인이 필요한 다단계 도구 파이프라인을 위한 워크플로우 런타임입니다. 작업이 단일 agent 턴 이상이고 인간 체크포인트가 있는 재개 가능한 워크플로우를 원할 때 사용하세요.

Lobster가 적합한 경우

  • 다단계 자동화: 일회성 프롬프트가 아닌 고정된 도구 호출 파이프라인이 필요합니다.
  • 승인 게이트: 부작용은 승인할 때까지 일시 중지되었다가 재개되어야 합니다.
  • 재개 가능한 실행: 이전 단계를 다시 실행하지 않고 일시 중지된 워크플로우를 계속합니다.

Heartbeat 및 cron과의 연계 방법

  • Heartbeat/cron은 실행이 언제 발생하는지 결정합니다.
  • Lobster는 실행이 시작되면 어떤 단계가 발생하는지 정의합니다.

예약된 워크플로우의 경우 cron 또는 heartbeat를 사용하여 Lobster를 호출하는 agent 턴을 트리거하세요. 임시 워크플로우의 경우 Lobster를 직접 호출하세요.

운영 참고사항 (코드에서)

  • Lobster는 도구 모드에서 로컬 하위 프로세스 (lobster CLI)로 실행되며 JSON 엔벨로프를 반환합니다.
  • 도구가 needs_approval을 반환하면 resumeToken 및 approve 플래그로 재개합니다.
  • 도구는 선택적 plugin입니다; tools.alsoAllow: ["lobster"]를 통해 추가적으로 활성화하세요 (권장).
  • lobsterPath를 전달하는 경우 절대 경로여야 합니다.

전체 사용법 및 예제는 Lobster를 참조하세요.

Main Session vs Isolated Session

Heartbeat와 cron 모두 main session과 상호 작용할 수 있지만 방식이 다릅니다:

HeartbeatCron (main)Cron (isolated)
SessionMainMain (시스템 이벤트를 통해)cron:<jobId>
기록공유공유각 실행마다 새로 시작
컨텍스트전체전체없음 (깨끗하게 시작)
모델Main session 모델Main session 모델오버라이드 가능
출력HEARTBEAT_OK가 아니면 전달Heartbeat 프롬프트 + 이벤트Main에 요약 게시

Main session cron을 사용해야 할 때

다음을 원할 때 --session main과 --system-event를 사용하세요:

  • 알림/이벤트가 main session 컨텍스트에 나타나도록
  • Agent가 전체 컨텍스트로 다음 heartbeat 중에 처리하도록
  • 별도의 isolated 실행 없음
openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

Isolated cron을 사용해야 할 때

다음을 원할 때 --session isolated를 사용하세요:

  • 이전 컨텍스트 없이 깨끗한 시작
  • 다른 모델 또는 thinking 설정
  • 출력이 채널로 직접 전달 (요약은 여전히 기본적으로 main에 게시)
  • Main session을 어지럽히지 않는 기록
openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --deliver

비용 고려사항

메커니즘비용 프로필
HeartbeatN분마다 한 번의 턴; HEARTBEAT.md 크기에 따라 확장
Cron (main)다음 heartbeat에 이벤트 추가 (isolated 턴 없음)
Cron (isolated)작업당 전체 agent 턴; 더 저렴한 모델 사용 가능

팁:

  • 토큰 오버헤드를 최소화하려면 HEARTBEAT.md를 작게 유지하세요.
  • 여러 cron 작업 대신 유사한 확인을 heartbeat로 배치하세요.
  • 내부 처리만 원하는 경우 heartbeat에서 target: "none"을 사용하세요.
  • 일상적인 작업에는 더 저렴한 모델로 isolated cron을 사용하세요.

관련 항목

  • Heartbeat - 전체 heartbeat 구성
  • Cron 작업 - 전체 cron CLI 및 API 참조
  • System - 시스템 이벤트 + heartbeat 제어
← 문서로 돌아가기