OpenClaw 튜토리얼 2편: Heartbeat vs Cron, 언제 무엇을 써야 하나

개요

OpenClaw 공식 문서를 보면 Heartbeat와 Cron은 둘 다 “주기적으로 뭔가를 실행한다”는 점에서 비슷해 보이지만, 실제 역할은 꽤 다릅니다.

이 문서는 공식 문서의 내용을 바탕으로,

를 실전 관점에서 정리합니다.

---

1. 한 줄 차이

Heartbeat

assistant의 정기 check-in입니다.

Cron

정해진 시간/주기로 작업을 실행하는 스케줄러입니다.

이 차이를 먼저 잡고 가면 거의 안 헷갈립니다.

---

2. Heartbeat란 무엇인가

공식 문서 기준 Heartbeat는,

결국 heartbeat는 에이전트의 주기적 상황 인식 루프에 가깝습니다.

Heartbeat가 잘 맞는 일

예를 들어,

이런 것들은 heartbeat가 아주 잘 맞습니다.

---

3. Cron이란 무엇인가

공식 문서 기준 Cron은 Gateway의 built-in scheduler입니다.

특징,

결국 cron은 정밀한 스케줄러 + 작업 실행기입니다.

Cron이 잘 맞는 일

---

4. 공식 문서 기준 핵심 차이

| 구분 | Heartbeat | Cron |

|---|---|---|

| 기본 성격 | periodic awareness | precise scheduling |

| 실행 위치 | main session | main 또는 isolated |

| 타이밍 | 대체로 정기적 | 더 정확한 시간 제어 |

| 컨텍스트 | main session 공유 | isolated 가능 |

| 주 용도 | 점검 / 체크인 / 상황 인식 | 리포트 / 리마인더 / 예약 작업 |

| 비용 최적화 | 여러 체크를 한 번에 묶기 좋음 | 개별 작업 단위 제어에 좋음 |

---

5. Heartbeat의 장점

1) 여러 점검을 한 번에 묶을 수 있다

관련 공식 문서도 heartbeat를 “batching”에 유리한 구조로 설명합니다.

예:

이걸 각각 cron으로 따로 돌리면 API 호출과 세션 노이즈가 많아질 수 있어요.

heartbeat는 이걸 한 턴으로 묶기 좋습니다.

2) main session 컨텍스트를 유지한다

heartbeat는 대화 맥락과 최근 상황을 이어받기 때문에,

더 자연스러운 판단이 가능합니다.

예:

3) 아무 일 없으면 조용히 끝난다

HEARTBEAT_OK 응답은 OpenClaw가 억제(suppress)합니다.

결국 “늘 돌지만, 늘 떠들진 않는” 구조를 만들 수 있어요.

---

6. Cron의 장점

1) 정확한 시간 제어

“매일 오전 7시”, “월요일 9시”, “20분 뒤” 같은 작업은 cron이 더 적합합니다.

2) isolated session 가능

관련 공식 문서 기준 cron은 cron:<jobId> 형태의 dedicated session에서 돌 수 있습니다.

이 포인트가 꽤 중요합니다.

결국:

할 수 있습니다.

3) 모델/세팅 override 가능

cron isolated job은,

을 쓸 수 있습니다.

결국 “비싼 작업은 필요할 때만 독립 실행”이 가능해집니다.

4) one-shot reminder에 아주 적합

“20분 후 알려줘” 같은 건 heartbeat보다 cron이 정확합니다.

---

7. 실전적으로 언제 heartbeat를 써야 하나

이런 경우 heartbeat가 맞습니다.

패턴 A. 여러 가벼운 상태 체크

패턴 B. assistant가 상황을 알아서 판단해야 할 때

“지금 굳이 말해야 하나?” 같은 판단이 필요하면 heartbeat가 자연스럽습니다.

패턴 C. 하나의 주기 루프로 관리하고 싶을 때

체크 항목이 계속 늘어날수록 heartbeat가 더 효율적일 수 있습니다.

---

8. 실전적으로 언제 cron을 써야 하나

패턴 A. 정확한 wall-clock 시각이 중요할 때

패턴 B. isolated run이 필요할 때

패턴 C. one-shot 리마인더

패턴 D. 다른 전달 방식이 필요할 때

공식 문서 기준 cron은,

같은 delivery mode를 갖습니다.

결국 외부 전달/분리된 알림 흐름 설계에 유리합니다.

---

9. 공식 문서 기준 가장 좋은 운영 방식: 둘 다 같이 쓰기

공식 문서도 가장 효율적인 패턴은 heartbeat + cron 조합이라고 설명합니다.

추천 구조

#### Heartbeat

30분마다,

#### Cron

정확한 시각,

결국:

으로 나누면 됩니다.

---

10. 예시 구성

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 설정 예시

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: { start: "08:00", end: "22:00" }
      }
    }
  }
}

cron 예를 들어, 아침 브리프

openclaw cron add \
  --name "Morning briefing" \
  --cron "0 7 * * *" \
  --tz "Asia/Seoul" \
  --session isolated \
  --message "Generate today's briefing." \
  --announce

cron 예를 들어, one-shot reminder

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

---

11. heartbeat를 남용하면 생기는 문제

1) 너무 자주 돌리면 토큰이 많이 든다

관련 공식 문서도 shorter intervals는 비용을 더 태운다고 분명히 말합니다.

2) 할 일을 다 heartbeat에 몰아넣으면 모호해진다

정확한 시간 예약이 필요한 작업까지 heartbeat에 넣으면,

“언제 실행돼야 하는지”가 애매해집니다.

3) main session이 과도하게 busy하면 지연될 수 있다

heartbeat는 main 흐름과 관계가 깊어서, 바쁜 상황에선 defer될 수 있습니다.

---

12. cron을 남용하면 생기는 문제

1) 작업이 너무 잘게 쪼개진다

사소한 체크를 다 cron으로 만들면 스케줄러만 복잡해집니다.

2) main context 없이 도는 작업은 맥락이 부족할 수 있다

isolated cron은 강력하지만, 때로는 최근 대화 맥락이 없는 것이 단점이 됩니다.

3) 리포트와 알림이 너무 많아질 수 있다

정확히 돌기 때문에, noisy job을 많이 만들면 오히려 피로도가 높아집니다.

---

13. 실제 운영 추천안

제가 추천하는 기본 운영안은 이거예요.

Heartbeat

Cron

결국 heartbeat는 assistant의 감각, cron은 assistant의 일정표라고 보면 됩니다.

---

결론

OpenClaw 공식 문서를 기준으로 보면 heartbeat와 cron은 경쟁 관계가 아니라 역할 분담 관계입니다.

따라서 운영적으로 가장 좋은 패턴은,

  1. heartbeat로 여러 lightweight check를 묶고
  2. cron으로 정확한 예약 작업과 isolated job을 처리하는 것

입니다.

---

출처