하트비트

개요

하트비트(Heartbeat)는 OpenClaw의 주기적 에이전트 실행 메커니즘이다. 일정 간격으로 에이전트의 메인 세션에 턴을 발생시켜, 에이전트가 자율적으로 할 일을 확인하고 처리할 수 있게 한다.

동작 방식

1. 설정된 간격(기본 30분)마다 하트비트 실행
2. 에이전트에 HEARTBEAT.md 파일을 읽으라는 프롬프트 전송
3. 에이전트가 대기 중인 작업 확인
4. 할 일이 있으면 처리, 없으면 HEARTBEAT_OK 응답

[30분 경과] → 하트비트 프롬프트 → 에이전트가 HEARTBEAT.md 확인
                                         │
                             ┌────────────┴────────────┐
                             │                         │
                        할 일 있음                  할 일 없음
                             │                         │
                        작업 수행                  HEARTBEAT_OK

설정 옵션

{
  "automation": {
    "heartbeat": {
      "every": "30m",              // 실행 간격
      "target": "main",           // 전달 대상 (세션)
      "lightContext": false,       // 경량 컨텍스트 사용 여부
      "isolatedSession": false,   // 격리 세션 사용 여부
      "activeHours": {            // 활성 시간대 설정
        "start": "09:00",
        "end": "22:00",
        "timezone": "Asia/Seoul"
      }
    }
  }
}

설정 항목 상세

every (간격)

하트비트 실행 간격을 설정한다.

target (전달 대상)

하트비트 프롬프트를 전달할 대상을 지정한다.

• "main" - 메인 세션 (기본값)
• 특정 채널이나 세션 지정 가능

lightContext

true로 설정하면 경량 컨텍스트로 실행한다. 과거 대화 히스토리를 최소한으로 포함하여 토큰을 절약한다.

isolatedSession

true로 설정하면 별도의 격리 세션에서 하트비트를 실행한다. 메인 세션의 컨텍스트를 사용하지 않는다.

activeHours (활성 시간대)

하트비트가 실행되는 시간대를 제한한다. 야간에는 하트비트를 중단하여 불필요한 비용을 절약한다.

비용 최적화

하트비트는 주기적으로 실행되므로 비용에 주의해야 한다.

일반 세션 실행

메인 세션에서 하트비트를 실행하면 전체 컨텍스트가 로드된다.

• 약 ~100K 토큰/실행 소비
• 30분마다 실행 시 하루 48회 = 약 4.8M 토큰/일

isolatedSession 사용 (권장)

격리 세션에서 실행하면 최소한의 컨텍스트만 사용한다.

• 약 ~2-5K 토큰/실행 소비
• 30분마다 실행 시 하루 48회 = 약 96K-240K 토큰/일

권장: isolatedSession: true로 설정하면 토큰 사용량을 95% 이상 절감할 수 있다.

비용 최적화 설정 예시

{
  "automation": {
    "heartbeat": {
      "every": "30m",
      "isolatedSession": true,       // 격리 세션으로 비용 절감
      "lightContext": true,          // 경량 컨텍스트
      "activeHours": {               // 업무 시간만 실행
        "start": "09:00",
        "end": "22:00",
        "timezone": "Asia/Seoul"
      }
    }
  }
}

이 설정으로:

• 격리 세션: ~2-5K 토큰/실행
• 활성 시간 13시간: 하루 26회 실행
• 하루 총 약 52K-130K 토큰

HEARTBEAT.md 작성 가이드

워크스페이스에 HEARTBEAT.md 파일을 작성하여 하트비트 시 에이전트가 확인할 작업을 정의한다.

# 하트비트 체크리스트

## 확인 항목
- [ ] 미응답 고객 문의 확인
- [ ] 예약된 작업 실행
- [ ] 시스템 상태 모니터링

## 현재 대기 작업
- 없음

## 메모
- 할 일이 없으면 HEARTBEAT_OK로 응답

에이전트는 이 파일을 읽고 대기 중인 작업이 있으면 처리하고, 없으면 HEARTBEAT_OK를 응답한다.