크론 vs 하트비트: 각각 언제 사용해야 하는가

하트비트와 크론 작업 모두 스케줄에 따라 작업을 실행할 수 있습니다. 이 가이드는 사용 사례에 맞는 올바른 메커니즘을 선택하는 데 도움을 줍니다.

빠른 의사결정 가이드

하트비트: 주기적 인식

하트비트는 일정 간격(기본값: 30분)으로 메인 세션에서 실행됩니다. 에이전트가 상황을 확인하고 중요한 사항을 표면화하도록 설계되었습니다.

하트비트를 사용해야 할 때

• 다수의 주기적 확인: 받은편지함, 캘린더, 날씨, 알림, 프로젝트 상태를 확인하는 5개의 별도 크론 작업 대신, 하나의 하트비트로 모두 묶어서 처리할 수 있습니다.
• 컨텍스트 인식 판단: 에이전트가 메인 세션의 전체 컨텍스트를 가지고 있어, 긴급한 것과 기다릴 수 있는 것을 스마트하게 판단할 수 있습니다.
• 대화 연속성: 하트비트 실행은 같은 세션을 공유하므로, 에이전트가 최근 대화를 기억하고 자연스럽게 후속 조치를 취할 수 있습니다.
• 저부하 모니터링: 하나의 하트비트가 여러 작은 폴링 작업을 대체합니다.

하트비트의 장점

• 다수의 확인을 묶어서 처리: 하나의 에이전트 턴으로 받은편지함, 캘린더, 알림을 함께 검토할 수 있습니다.
• API 호출 감소: 하나의 하트비트가 5개의 격리 크론 작업보다 저렴합니다.
• 컨텍스트 인식: 에이전트가 현재 작업 중인 내용을 알고 그에 따라 우선순위를 정할 수 있습니다.
• 스마트 억제: 주의가 필요한 것이 없으면, 에이전트가 HEARTBEAT_OK로 응답하고 메시지가 전달되지 않습니다.
• 자연스러운 타이밍: 대기열 부하에 따라 약간 변동되지만, 대부분의 모니터링에는 충분합니다.

하트비트 예시: HEARTBEAT.md 체크리스트

# Heartbeat checklist

- Check email for urgent messages
- Review calendar for events in next 2 hours
- If a background task finished, summarize results
- If idle for 8+ hours, send a brief check-in

에이전트가 각 하트비트마다 이를 읽고 하나의 턴에서 모든 항목을 처리합니다.

하트비트 설정

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 간격
        target: "last", // 명시적 알림 전달 대상 (기본값은 "none")
        activeHours: { start: "08:00", end: "22:00" }, // 선택 사항
      },
    },
  },
}

전체 설정은 하트비트를 참고하세요.

크론: 정밀한 스케줄링

크론 작업은 정확한 시간에 실행되며, 메인 컨텍스트에 영향을 주지 않고 격리 세션에서 실행할 수 있습니다. 정시 반복 스케줄은 0-5분 범위 내에서 작업별 결정론적 오프셋으로 자동 분산됩니다.

크론을 사용해야 할 때

• 정확한 타이밍 필요: “매주 월요일 오전 9시에 이것을 보내줘” (“9시쯤”이 아닌).
• 독립적 작업: 대화 컨텍스트가 필요 없는 작업.
• 다른 모델/사고 레벨: 더 강력한 모델이 필요한 심층 분석.
• 일회성 리마인더: --at으로 “20분 후 알려줘”.
• 시끄러운/빈번한 작업: 메인 세션 기록을 어지럽히는 작업.
• 외부 트리거: 에이전트가 다른 작업 중인지와 무관하게 독립적으로 실행되어야 하는 작업.

크론의 장점

• 정밀한 타이밍: 시간대 지원이 있는 5필드 또는 6필드(초) 크론 표현식.
• 내장 부하 분산: 정시 반복 스케줄은 기본적으로 최대 5분까지 분산됩니다.
• 작업별 제어: --stagger <duration>으로 분산을 오버라이드하거나 --exact로 정확한 타이밍을 강제합니다.
• 세션 격리: 메인 기록을 오염시키지 않고 cron:<jobId>에서 실행됩니다.
• 모델 오버라이드: 작업별로 더 저렴하거나 더 강력한 모델을 사용할 수 있습니다.
• 전달 제어: 격리 작업은 기본적으로 announce (요약)이며, 필요에 따라 none을 선택할 수 있습니다.
• 즉시 전달: Announce 모드는 하트비트를 기다리지 않고 직접 게시합니다.
• 에이전트 컨텍스트 불필요: 메인 세션이 유휴 상태이거나 압축되어도 실행됩니다.
• 일회성 지원: --at으로 정확한 미래 타임스탬프 지정.

크론 예시: 일일 아침 브리핑

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 \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

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

크론 예시: 일회성 리마인더

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 참조는 크론 작업을 참고하세요.

의사결정 플로차트

작업이 정확한 시간에 실행되어야 하는가?
  예 -> 크론 사용
  아니오 -> 계속...

작업이 메인 세션으로부터 격리되어야 하는가?
  예 -> 크론 (격리) 사용
  아니오 -> 계속...

이 작업을 다른 주기적 확인과 묶어서 처리할 수 있는가?
  예 -> 하트비트 사용 (HEARTBEAT.md에 추가)
  아니오 -> 크론 사용

일회성 리마인더인가?
  예 -> --at이 있는 크론 사용
  아니오 -> 계속...

다른 모델이나 사고 레벨이 필요한가?
  예 -> --model/--thinking이 있는 크론 (격리) 사용
  아니오 -> 하트비트 사용

둘 다 함께 사용하기

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

1. 하트비트가 30분마다 일괄 턴으로 일상적인 모니터링(받은편지함, 캘린더, 알림)을 처리합니다.
2. 크론이 정밀한 스케줄(일일 보고서, 주간 리뷰)과 일회성 리마인더를 처리합니다.

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

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

# Heartbeat checklist

- Scan inbox for urgent emails
- Check calendar for events in next 2h
- Review any pending tasks
- Light check-in if quiet for 8+ hours

크론 작업 (정밀한 타이밍):

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

# 매주 월요일 오전 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는 결정론적 실행과 명시적 승인이 필요한 다단계 도구 파이프라인을 위한 워크플로 런타임입니다. 작업이 단일 에이전트 턴 이상이고, 사람의 체크포인트가 있는 재개 가능한 워크플로가 필요할 때 사용하세요.

Lobster가 적합한 경우

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

하트비트 및 크론과의 결합

• 하트비트/크론은 실행이 언제 일어나는지 결정합니다.
• Lobster는 실행이 시작된 후 _어떤 단계_가 일어나는지 정의합니다.

예약된 워크플로의 경우, 크론이나 하트비트를 사용하여 Lobster를 호출하는 에이전트 턴을 트리거하세요. 임시 워크플로의 경우, Lobster를 직접 호출하세요.

운영 참고사항 (코드 기반)

• Lobster는 도구 모드로 로컬 서브프로세스 (lobster CLI)로 실행되며 JSON 엔벨로프를 반환합니다.
• 도구가 needs_approval을 반환하면, resumeToken과 approve 플래그로 재개합니다.
• 이 도구는 선택적 플러그인이며, tools.alsoAllow: ["lobster"] (권장)로 추가적으로 활성화합니다.
• Lobster는 lobster CLI가 PATH에 있어야 합니다.

자세한 사용법과 예시는 Lobster를 참고하세요.

메인 세션 vs 격리 세션

하트비트와 크론 모두 메인 세션과 상호작용할 수 있지만, 방식이 다릅니다:

메인 세션 크론을 사용해야 할 때

다음이 필요한 경우 --session main과 --system-event를 사용하세요:

• 리마인더/이벤트가 메인 세션 컨텍스트에 나타나기를 원할 때
• 에이전트가 전체 컨텍스트로 다음 하트비트에서 처리하기를 원할 때
• 별도의 격리 실행이 필요 없을 때

openclaw cron add \
  --name "Check project" \
  --every "4h" \
  --session main \
  --system-event "Time for a project health check" \
  --wake now

격리 크론을 사용해야 할 때

다음이 필요한 경우 --session isolated를 사용하세요:

• 이전 컨텍스트 없이 클린 슬레이트
• 다른 모델이나 사고 레벨 설정
• 채널로 직접 요약 전달
• 메인 세션을 어지럽히지 않는 기록

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 0" \
  --session isolated \
  --message "Weekly codebase analysis..." \
  --model opus \
  --thinking high \
  --announce

비용 고려사항

팁:

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

관련 문서

• 하트비트 - 전체 하트비트 설정
• 크론 작업 - 전체 크론 CLI 및 API 참조
• 시스템 - 시스템 이벤트 + 하트비트 제어