Heartbeat 가이드

Heartbeat는 별도 job 목록을 실행하는 스케줄러가 아닙니다. 2026-07-13 기준 OpenClaw Heartbeat는 Gateway가 주기적으로 main session agent turn을 실행해 중요한 follow-up을 드러내는 표면입니다.

기준일: 2026-07-13 공식 기준: Heartbeat, System CLI, Automation, HEARTBEAT.md template

핵심 개념

• Heartbeat는 기본적으로 main session에서 실행됩니다.
• Heartbeat run 자체는 background task record를 만들지 않습니다.
• 기본 cadence는 30m입니다. Anthropic OAuth/token auth 기본값이 적용되는 경우 unset 상태에서는 1h가 될 수 있습니다.
• HEARTBEAT.md가 있으면 기본 prompt가 그 파일을 읽도록 지시합니다.
• 빈 HEARTBEAT.md 또는 주석/빈 목록 수준의 파일은 모델 호출을 건너뛰게 할 수 있습니다.
• Heartbeat는 cron work가 active 또는 queued 상태이면 자동으로 defer됩니다.
• HEARTBEAT_OK는 OK-only acknowledgment를 숨기는 데 쓰입니다.

공식 CLI 표면은 다음 세 가지입니다.

openclaw system heartbeat last
openclaw system heartbeat enable
openclaw system heartbeat disable

독립 Heartbeat 목록/상태/로그 CLI는 현재 공식 CLI reference의 표면이 아닙니다. Heartbeat 운영은 openclaw system heartbeat ... 하위 명령으로 확인합니다.

선택 기준

요구	Heartbeat 적합 여부	이유
inbox, calendar, notification을 30분마다 느슨하게 확인	적합	main session 맥락으로 여러 확인을 묶음
매일 9시 보고서	부적합	정확한 시각과 기록은 Cron이 담당
실행 기록과 실패 알림이 필요한 job	부적합	Heartbeat는 task record를 만들지 않음
외부 task 완료를 main session에 빨리 알림	보조 표면	openclaw system event --mode now가 heartbeat wake를 사용
비용 절감을 위해 매번 전체 맥락을 피함	조건부 적합	lightContext와 isolatedSession을 조합
특정 시간대에만 check-in	적합	activeHours로 시간 창 제한

실습

기본 Heartbeat 설정

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "none"
      }
    }
  }
}

마지막 외부 채널로 알림 보내기

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        directPolicy: "allow"
      }
    }
  }
}

가벼운 맥락으로 실행하기

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        lightContext: true,
        isolatedSession: true,
        skipWhenBusy: true
      }
    }
  }
}

운영 시간 제한하기

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        activeHours: {
          start: "08:00",
          end: "24:00",
          timezone: "Asia/Seoul"
        }
      }
    }
  }
}

start와 end를 같은 값으로 두면 zero-width window로 처리되어 Heartbeat가 항상 skip됩니다. 하루 종일 실행하려면 activeHours를 생략하거나 start: "00:00", end: "24:00"을 사용합니다.

HEARTBEAT.md 작성하기

<!-- Heartbeat checklist. Keep this short because every due heartbeat may read it. -->

- Check calendar for urgent changes.
- Check inbox for messages that need same-day attention.
- If nothing needs attention, reply HEARTBEAT_OK.

상태 확인과 일시 중지

openclaw system heartbeat last
openclaw system heartbeat disable
openclaw system heartbeat enable
openclaw logs --limit 200

도구에 입력할 프롬프트

Heartbeat prompt를 좁힐 때:

HEARTBEAT.md를 읽고 오늘 처리해야 할 긴급 follow-up만 알려줘.
새 작업을 추론하거나 오래된 대화를 반복하지 마.
알릴 내용이 없으면 HEARTBEAT_OK만 반환해줘.

설정 검토를 맡길 때:

이 Heartbeat 설정이 공식 필드만 쓰는지 검토해줘.
every, target, directPolicy, lightContext, isolatedSession, skipWhenBusy, activeHours, prompt, timeoutSeconds만 기준으로 설명하고,
독립 Heartbeat 목록/상태/로그 CLI는 제안하지 마.

체크리스트

• Heartbeat를 job scheduler가 아니라 periodic main-session turn으로 설명했다.
• 정확한 시각 실행이 필요한 작업은 Cron으로 분리했다.
• HEARTBEAT.md는 짧고 안정적인 체크리스트로 유지했다.
• 0m으로 disable할 수 있다는 점을 알고 있다.
• 외부 delivery가 필요하면 target, to, accountId, directPolicy를 공식 필드로 설정했다.
• 확인 명령은 openclaw system heartbeat last|enable|disable과 openclaw logs만 사용했다.

다음 단계

• 자동화 개요 - Cron과 Heartbeat 선택 기준
• Cron 표현식 가이드 - 정확한 시간 기반 실행
• Gateway 설정 - Heartbeat가 의존하는 Gateway 운영