OpenClaw 작업 스케줄링: Heartbeat vs Cron 선택 가이드

개발을 하다 보면 특정 시간에 맞춰 작업을 실행해야 할 때가 정말 많죠. 하지만 모든 작업에 똑같은 방식을 쓸 수는 없어요. 어떤 작업은 초 단위의 정확한 타이밍이 중요하고, 어떤 작업은 그저 주기적으로 상황을 슬쩍 확인만 하면 충분하니까요.

이 가이드는 여러분의 유스케이스에 딱 맞는 메커니즘을 선택할 수 있도록 도와드릴게요. Heartbeat와 Cron의 차이점을 알아보고, 언제 무엇을 사용하면 좋을지 함께 살펴봐요.

빠른 의사결정 가이드

유스케이스	추천 방식	이유
30분마다 받은 편지함 확인	Heartbeat	다른 확인 작업과 일괄 처리 가능, 컨텍스트 인지
매일 오전 9시 정각에 보고서 발송	Cron (isolated)	정확한 타이밍이 필요함
캘린더에서 다가오는 이벤트 모니터링	Heartbeat	주기적인 상황 인지에 자연스럽게 적합함
매주 심층 분석 실행	Cron (isolated)	독립적인 작업이며, 다른 모델 사용 가능
20분 뒤에 알림 받기	Cron (main, `--at`)	정확한 타이밍이 필요한 일회성 작업
백그라운드 프로젝트 상태 확인	Heartbeat	기존 사이클에 편승하여 실행 가능

Heartbeat: 주기적인 상황 인지

Heartbeat는 main session에서 정해진 간격(기본값: 30분)으로 실행돼요. 에이전트가 주변 상황을 점검하고 중요한 내용을 수면 위로 끌어올리도록 설계되었죠.

Heartbeat를 사용하는 경우

여러 주기적 확인 작업: 받은 편지함, 캘린더, 날씨, 알림, 프로젝트 상태를 확인하기 위해 5개의 별도 Cron 작업을 만드는 대신, 하나의 Heartbeat로 이 모든 것을 일괄 처리할 수 있어요.
컨텍스트 기반 의사결정: 에이전트가 메인 세션의 전체 컨텍스트를 가지고 있어서, 무엇이 급하고 무엇이 나중에 처리해도 될지 똑똑하게 판단할 수 있어요.
대화의 연속성: Heartbeat 실행은 동일한 세션을 공유해요. 그래서 에이전트가 최근 대화 내용을 기억하고 자연스럽게 후속 조치를 취할 수 있죠.
낮은 오버헤드 모니터링: 하나의 Heartbeat가 수많은 작은 폴링 작업을 대체해요.

Heartbeat의 장점

여러 확인 작업 일괄 처리: 에이전트가 한 번의 턴으로 받은 편지함, 캘린더, 알림을 함께 검토할 수 있어요.
API 호출 감소: 5개의 독립적인 Cron 작업을 돌리는 것보다 하나의 Heartbeat를 쓰는 게 비용이 더 저렴해요.
컨텍스트 인지: 에이전트가 여러분이 무엇을 작업하고 있었는지 알고 그에 따라 우선순위를 정해요.
스마트한 억제: 주의가 필요한 사항이 없으면 에이전트가 HEARTBEAT_OK라고 응답하고 메시지를 보내지 않아요.
자연스러운 타이밍: 큐 부하에 따라 시간이 약간씩 밀릴 수 있는데, 대부분의 모니터링 작업에는 큰 문제가 없어요.

Heartbeat 예시: 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

에이전트는 매 Heartbeat마다 이 파일을 읽고 모든 항목을 한 번에 처리해요.

Heartbeat 설정하기

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // interval
        target: "last", // explicit alert delivery target (default is "none")
        activeHours: { start: "08:00", end: "22:00" }, // optional
      },
    },
  },
}

전체 설정 방법은 Heartbeat 문서를 참고해 주세요.

Cron: 정밀한 스케줄링

Cron 작업은 정확한 시간에 실행되며, 메인 컨텍스트에 영향을 주지 않고 독립된 세션(isolated session)에서 실행될 수 있어요. 매시 정각에 반복되는 스케줄은 작업별로 결정론적인 오프셋을 가져서 0~5분 사이에 자동으로 분산되어 실행돼요.

Cron을 사용하는 경우

정확한 타이밍이 필수일 때: “매주 월요일 오전 9시 정각에 발송” (9시쯤이 아니라 정확히 9시여야 할 때).
독립적인 작업: 대화 컨텍스트가 필요 없는 작업들.
다른 모델이나 추론 능력이 필요할 때: 더 고성능 모델이 필요한 무거운 분석 작업.
일회성 알림: --at을 사용한 “20분 뒤에 알려줘” 같은 작업.
빈도가 높거나 노이즈가 많은 작업: 메인 세션 히스토리를 복잡하게 만들 수 있는 작업들.
외부 트리거: 에이전트의 활동 여부와 상관없이 독립적으로 실행되어야 하는 작업.

Cron의 장점

정밀한 타이밍: 타임존을 지원하며 5개 또는 6개(초 단위 포함) 필드의 Cron 표현식을 사용할 수 있어요.
내장된 부하 분산: 매시 정각 반복 스케줄은 기본적으로 최대 5분까지 엇갈리게 실행돼요.
작업별 제어: --stagger <duration>으로 분산 시간을 조정하거나 --exact로 정확한 타이밍을 강제할 수 있어요.
세션 격리: cron:<jobId>에서 실행되어 메인 히스토리를 더럽히지 않아요.
모델 오버라이드: 작업마다 더 저렴하거나 더 강력한 모델을 골라 쓸 수 있어요.
전달 제어: 격리된 작업은 기본적으로 announce(요약) 모드로 작동하며, 필요에 따라 none을 선택할 수 있어요.
즉시 전달: Announce 모드는 Heartbeat를 기다리지 않고 메시지를 바로 게시해요.
에이전트 컨텍스트 불필요: 메인 세션이 유휴 상태이거나 압축된 상태여도 실행돼요.
일회성 지원: 미래의 특정 시점을 지정하는 --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 \
  --announce \
  --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 jobs에서 확인할 수 있어요.

의사결정 플로우차트

Does the task need to run at an EXACT time?
  YES -> Use cron
  NO  -> Continue...

Does the task need isolation from main session?
  YES -> Use cron (isolated)
  NO  -> Continue...

Can this task be batched with other periodic checks?
  YES -> Use heartbeat (add to HEARTBEAT.md)
  NO  -> Use cron

Is this a one-shot reminder?
  YES -> Use cron with --at
  NO  -> Continue...

Does it need a different model or thinking level?
  YES -> Use cron (isolated) with --model/--thinking
  NO  -> Use heartbeat

두 방식 조합하기

가장 효율적인 방법은 두 가지를 모두 사용하는 거예요.

Heartbeat는 30분마다 한 번의 턴으로 일상적인 모니터링(받은 편지함, 캘린더, 알림)을 일괄 처리해요.
Cron은 정확한 스케줄이 필요한 작업(일일 보고서, 주간 검토)과 일회성 알림을 담당하죠.

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

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

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

# Daily morning briefing at 7am
openclaw cron add --name "Morning brief" --cron "0 7 * * *" --session isolated --message "..." --announce

# Weekly project review on Mondays at 9am
openclaw cron add --name "Weekly review" --cron "0 9 * * 1" --session isolated --message "..." --model opus

# One-shot reminder
openclaw cron add --name "Call back" --at "2h" --session main --system-event "Call back the client" --wake now

Lobster: 승인 단계가 포함된 결정론적 워크플로우

Lobster는 결정론적인 실행과 명시적인 승인이 필요한 다단계 도구 파이프라인을 위한 워크플로우 런타임이에요. 작업이 단순히 에이전트의 한 번의 답변으로 끝나지 않고, 사람이 중간에 개입하여 확인해야 하는 재개 가능한 워크플로우일 때 사용하세요.

Lobster가 적합한 경우

다단계 자동화: 단순한 프롬프트가 아니라 고정된 도구 호출 파이프라인이 필요할 때.
승인 게이트: 외부 영향을 주는 작업 전에 일시 중지하고, 승인을 받은 뒤 다시 시작해야 할 때.
재개 가능한 실행: 중단된 워크플로우를 이전 단계를 다시 실행하지 않고 이어서 진행하고 싶을 때.

Heartbeat 및 Cron과의 관계

Heartbeat/Cron은 실행되는 ‘시점’을 결정해요.
Lobster는 실행이 시작된 후 ‘어떤 단계’가 진행될지를 정의해요.

스케줄링된 워크플로우를 만들려면, Cron이나 Heartbeat를 사용해 Lobster를 호출하는 에이전트 턴을 트리거하면 돼요. 임시 워크플로우라면 Lobster를 직접 호출하면 됩니다.

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

Lobster는 도구 모드에서 로컬 서브프로세스(lobster CLI)로 실행되며 JSON envelope를 반환해요.
도구가 needs_approval을 반환하면, resumeToken과 approve 플래그를 사용해 재개할 수 있어요.
이 도구는 선택적 플러그인이에요. tools.alsoAllow: ["lobster"]를 통해 추가로 활성화하는 것을 권장해요.
Lobster를 쓰려면 PATH에 lobster CLI가 설치되어 있어야 해요.

자세한 사용법과 예시는 Lobster 문서를 확인해 보세요.

Main Session vs Isolated Session 비교

Heartbeat와 Cron 모두 메인 세션과 상호작용할 수 있지만 방식이 달라요.

	Heartbeat	Cron (main)	Cron (isolated)
세션	Main	Main (시스템 이벤트 경유)	`cron:<jobId>`
히스토리	공유됨	공유됨	매 실행 시 새로 시작
컨텍스트	전체 유지	전체 유지	없음 (깨끗하게 시작)
모델	메인 세션 모델	메인 세션 모델	오버라이드 가능
출력	`HEARTBEAT_OK`가 아니면 전달	Heartbeat 프롬프트 + 이벤트	Announce 요약 (기본값)

Main Session Cron을 사용하는 경우

다음과 같은 상황에서는 --session main과 --system-event를 함께 사용하세요.

알림이나 이벤트가 메인 세션 컨텍스트에 나타나길 원할 때
에이전트가 다음 Heartbeat 때 전체 컨텍스트를 가지고 이를 처리하길 원할 때
별도의 격리된 실행이 필요 없을 때

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

Isolated Cron을 사용하는 경우

다음과 같은 상황에서는 --session isolated를 사용하세요.

이전 컨텍스트 없이 깨끗한 상태에서 시작하고 싶을 때
다른 모델이나 추론 설정을 쓰고 싶을 때
요약본을 채널로 직접 알리고 싶을 때
히스토리가 메인 세션을 복잡하게 만들지 않길 원할 때

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

비용 고려 사항

메커니즘	비용 프로필
Heartbeat	N분마다 한 번의 턴 실행; HEARTBEAT.md 크기에 비례
Cron (main)	다음 Heartbeat에 이벤트를 추가 (격리된 턴 없음)
Cron (isolated)	작업당 한 번의 전체 에이전트 턴 실행; 저렴한 모델 사용 가능

팁:

토큰 오버헤드를 줄이려면 HEARTBEAT.md를 작게 유지하세요.
비슷한 확인 작업들은 여러 개의 Cron 작업 대신 Heartbeat로 묶어서 처리하세요.
내부적인 처리만 원한다면 Heartbeat의 target을 "none"으로 설정하세요.
반복적인 일상 작업에는 저렴한 모델과 함께 Isolated Cron을 사용하세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.