​

Heartbeat

하트비트 vs 크론? 각 기능의 용도와 차이는 크론 vs 하트비트를 참고하세요.

​

빠른 시작 (초보자용)

1. Heartbeat를 켜 둡니다. 기본값은 30m이며 Anthropic OAuth/setup-token을 쓰면 1h입니다.
2. agent workspace에 간단한 HEARTBEAT.md 체크리스트를 둡니다. 선택 사항이지만 권장됩니다.
3. 메시지를 어디로 보낼지 정합니다. 기본값은 target: "none"이고, 마지막 대화 상대에게 보내려면 target: "last"를 사용합니다.
4. 선택 사항으로 heartbeat reasoning delivery를 켭니다.
5. heartbeat 실행에 HEARTBEAT.md만 필요하다면 경량 bootstrap context를 사용합니다.
6. 필요하면 로컬 시간 기준 active hours로 heartbeat를 제한합니다.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // explicit delivery to last contact (default is "none")
        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

​

기본 설정값

• 실행 간격: 30m (Anthropic OAuth/설정 토큰 인증 모드 감지 시 1h). agents.defaults.heartbeat.every 또는 에이전트별 agents.list[].heartbeat.every에서 설정하며, 0m으로 지정 시 비활성화됨.
• 프롬프트 본문 (agents.defaults.heartbeat.prompt로 수정 가능): Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.
• 하트비트 프롬프트는 사용자 메시지로서 원문 그대로 전송됨. 시스템 프롬프트에는 “Heartbeat” 섹션이 추가되며, 내부적으로 해당 실행이 하트비트임을 인지함.
• 활동 시간대(heartbeat.activeHours)는 설정된 타임존을 기준으로 검사됨. 지정된 시간 범위 밖에서는 다음 활성 시간까지 실행을 건너뜀.

​

하트비트 프롬프트의 용도

• 백그라운드 작업 처리: “미결 업무 검토” 지시를 통해 에이전트가 인박스, 캘린더, 미리 알림, 대기 중인 작업을 확인하고 긴급한 사항을 보고하도록 유도함.
• 사용자 안부 확인: 낮 시간대에는 “도움이 필요한지 가볍게 확인”하도록 유도함. 이때 설정된 로컬 타임존을 참조하여 밤 시간대에 불필요한 알림이 가지 않도록 방지함 (타임존 개념 참조).

​

응답 규격 (Contract)

• 별도의 조치가 필요 없는 경우 모델은 반드시 **HEARTBEAT_OK**로 응답해야 함.
• 하트비트 실행 중 OpenClaw는 응답의 시작 또는 끝에 HEARTBEAT_OK가 포함된 경우 이를 수신 확인(Ack)으로 처리함. 해당 토큰은 제거되며, 남은 텍스트 길이가 ackMaxChars(기본값 300) 이하인 경우 최종 응답을 전송하지 않고 무시함.
• 만약 HEARTBEAT_OK가 응답 중간에 나타나면 특별한 처리를 하지 않음.
• 알림이나 보고 사항이 있는 경우 HEARTBEAT_OK를 포함하지 말고 보고 내용만 작성해야 함.

​

상세 설정 레퍼런스

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // deliver separate Reasoning: message when available
        lightContext: false, // true keeps only HEARTBEAT.md in bootstrap context
        target: "last", // default: none | options: last | none | <channel id>
        to: "+82101234567", // optional channel-specific recipient override
        accountId: "ops-bot", // optional multi-account channel id
        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
      },
    },
  },
}

​

우선순위 및 범위

• agents.defaults.heartbeat: 전역 하트비트 동작 설정.
• agents.list[].heartbeat: 에이전트별 설정이 전역 설정을 덮어씀. 특정 에이전트에 하트비트 블록이 정의되면 해당 에이전트들만 하트비트를 수행함.
• channels.defaults.heartbeat: 모든 채널에 적용될 가시성 기본값.
• channels.<channel>.heartbeat: 개별 채널 설정이 기본값을 덮어씀.
• channels.<channel>.accounts.<id>.heartbeat: 다중 계정 채널의 경우 계정별로 더 세밀하게 제어 가능.

​

활동 시간대 설정 예시

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Seoul", // optional; otherwise uses userTimezone or host timezone
        },
      },
    },
  },
}

​

24시간 가동 설정

• activeHours 설정을 아예 생략함 (기본 동작).
• 전체 시간 범위를 지정함: activeHours: { start: "00:00", end: "24:00" }.

​

주요 필드 설명

• every: 실행 간격 (시간 단위 문자열, 기본값은 ‘분’).
• model: 하트비트 실행에 사용할 별도의 모델 지정 (provider/model).
• includeReasoning: 활성화 시 /reasoning on과 동일하게 Reasoning: 접두사가 붙은 사고 과정을 별도 메시지로 전달함.
• lightContext: true 설정 시 부트스트랩 파일 중 HEARTBEAT.md만 유지하여 컨텍스트 토큰을 절약함.
• session: 실행에 사용할 세션 키 (기본값 main).
• target:
  • last: 마지막으로 사용된 외부 채널로 응답 전송.
  • 채널 ID: whatsapp, telegram, discord 등 특정 채널 지정.
  • none (기본값): 외부 전송 없이 내부 상태만 업데이트함.
• directPolicy: DM 전송 정책 제어. allow (기본값) 또는 block (억제) 지정.
• activeHours: 실행 시간 창 설정. start (포함), end (미포함) 형식이며 timezone 지정을 지원함.

​

전송 동작 특징

• 하트비트는 기본적으로 에이전트의 메인 세션(agent:<id>:<mainKey>)에서 실행됨. session 설정을 통해 특정 채널 세션으로 변경 가능함.
• session 설정은 오직 실행 컨텍스트에만 영향을 주며, 실제 외부 전송 여부는 target과 to 설정이 결정함.
• 메인 작업 대기열(Queue)이 사용 중인 경우 하트비트는 실행을 건너뛰고 나중에 다시 시도함.
• 하트비트 전용 응답은 세션을 ‘활성’ 상태로 유지하지 않음. 마지막 대화 시점(updatedAt)이 복원되어 유휴 세션 만료 로직이 정상적으로 작동함.

​

가시성 제어 (Visibility)

channels:
  defaults:
    heartbeat:
      showOk: false # hide HEARTBEAT_OK (default)
      showAlerts: true # show alert content (default)
      useIndicator: true # emit UI indicator events (default)

• showOk: 모델이 OK 응답만 했을 때도 메시지를 전송함.
• showAlerts: 모델이 보고 사항을 작성했을 때 내용을 전송함.
• useIndicator: UI 상의 상태 표시기 이벤트를 전송함.

​

HEARTBEAT.md 활용 (선택 사항)

• 프롬프트 비대화를 방지하기 위해 내용을 간결하게 유지함.
• 에이전트에게 “HEARTBEAT.md를 직접 수정하여 체크리스트를 최신화하라”고 지시할 수도 있음.
• 보안 주의: 비밀번호나 API 키 등 민감한 정보는 프롬프트 컨텍스트에 포함되므로 절대 이 파일에 작성하지 말 것.

​

수동 실행 (On-demand)

openclaw system event --text "Check urgent tasks now" --mode now

​

비용 및 성능 고려 사항