​

Heartbeat (게이트웨이)

Heartbeat vs Cron? 각 사용 경우에 대한 지침은 Cron vs Heartbeat을 참조하세요.

​

빠른 시작 (초보자)

1. Heartbeat를 활성화 상태로 유지합니다 (기본값은 30m, 또는 Anthropic OAuth/설치 토큰의 경우 1h) 또는 직접 주기를 설정합니다.
2. 에이전트 작업 공간에 작은 HEARTBEAT.md 체크리스트를 만듭니다 (선택 사항이지만 권장됨).
3. Heartbeat 메시지가 어디로 갈지 결정합니다 (target: "last"는 기본값입니다).
4. 선택 사항: 투명성을 위해 Heartbeat 추론 전달을 활성화합니다.
5. 선택 사항: 활동 시간을 로컬 시간으로 제한합니다.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // 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): HEARTBEAT.md가 존재하는 경우 읽기 (작업 공간 컨텍스트). 이를 엄격히 따르십시오. 이전 대화에서 이전 작업을 유추하거나 반복하지 마십시오. 주의가 필요하지 않은 경우, HEARTBEAT_OK로 응답하십시오.
• Heartbeat 프롬프트는 문자 그대로 사용자 메시지로 전송됩니다. 시스템 프롬프트에는 “Heartbeat” 섹션이 포함되며 런이 내부적으로 플래그 처리됩니다.
• 활동 시간 (heartbeat.activeHours)은 구성된 시간대에서 확인됩니다. 창 밖에서는, Heartbeat가 다음 창 안의 틱까지 건너뜁니다.

​

Heartbeat 프롬프트의 목적

• 배경 작업: “미결 과제 고려하기”는 에이전트가 다음 작업 목록(메일, 일정, 알림, 대기 작업)을 검토하고 긴급한 사항을 표시하도록 유도합니다.
• 인간 체크인: “주간에 인간 확인”은 가끔 가벼운 “필요한 것 있습니까?” 메시지를 유도하되 로컬 시간대를 설정하여 야간 스팸을 피합니다 (자세한 내용은 /concepts/timezone).

​

응답 계약

• 주의가 필요하지 않은 경우, **HEARTBEAT_OK**로 응답합니다.
• Heartbeat가 실행되는 동안, OpenClaw는 응답의 시작 또는 끝에 HEARTBEAT_OK가 나타날 때 이를 승인으로 처리합니다. 토큰이 제거되고 남은 내용이 ≤ ackMaxChars (기본값: 300)인 경우 응답은 삭제됩니다.
• HEARTBEAT_OK가 응답의 중간에 나타날 경우, 특별히 처리되지 않습니다.
• 경고의 경우, **HEARTBEAT_OK**를 포함하지 않습니다; 경고 텍스트만 반환합니다.

​

설정

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 기본값: 30m (0m 비활성화)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // 기본값: false (사용 가능한 경우 별도의 Reasoning: 메시지 전달)
        target: "last", // last | none | <채널 id> (코어 또는 플러그인, 예: "bluebubbles")
        to: "+15551234567", // 선택적인 채널-특정 오버라이드
        accountId: "ops-bot", // 선택적 멀티-계정 채널 id
        prompt: "HEARTBEAT.md가 존재하는 경우 읽기 (작업 공간 컨텍스트). 이를 엄격히 따르십시오. 이전 대화에서 이전 작업을 유추하거나 반복하지 마십시오. 주의가 필요하지 않은 경우, HEARTBEAT_OK로 응답하십시오.",
        ackMaxChars: 300, // HEARTBEAT_OK 후 허용되는 최대 문자 수
      },
    },
  },
}

​

범위와 우선순위

• agents.defaults.heartbeat는 글로벌 Heartbeat 동작을 설정합니다.
• agents.list[].heartbeat는 상위로 통합됩니다; 어떤 에이전트가 heartbeat 블록을 가지면, 해당 에이전트만 Heartbeats를 실행합니다.
• channels.defaults.heartbeat는 모든 채널의 가시성 기본값을 설정합니다.
• channels.<channel>.heartbeat는 채널 기본값을 재정의합니다.
• channels.<channel>.accounts.<id>.heartbeat (멀티-계정 채널)은 채널 설정을 재정의합니다.

​

에이전트별 Heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "HEARTBEAT.md가 존재하는 경우 읽기 (작업 공간 컨텍스트). 이를 엄격히 따르십시오. 이전 대화에서 이전 작업을 유추하거나 반복하지 마십시오. 주의가 필요하지 않은 경우, HEARTBEAT_OK로 응답하십시오.",
        },
      },
    ],
  },
}

​

활동 시간의 예시

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // 선택적; 사용자 시간대가 설정된 경우 이를 사용하고, 그렇지 않을 경우 호스트 시간대를 사용
        },
      },
    },
  },
}

​

24시간 설정

• activeHours를 완전히 생략합니다 (시간 창 제한 없음; 이것이 기본 동작입니다).
• 전체 하루 창을 설정합니다: activeHours: { start: "00:00", end: "24:00" }.

​

멀티 계정의 예시

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // 선택적: 특정 토픽/스레드로 라우팅
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

필드 노트

• every: Heartbeat 간격 (기간 문자열; 기본 단위 = 분).
• model: Heartbeat 실행을 위한 선택적 모델 오버라이드 (provider/model).
• includeReasoning: 활성화된 경우, 사용 가능한 경우 별도의 Reasoning: 메시지를 전달 (동일한 형태 /reasoning on).
• session: Heartbeat 실행을 위한 선택적 세션 키.
  • main (기본값): 에이전트 메인 세션.
  • 명시적 세션 키 (openclaw sessions --json이나 sessions CLI에서 복사).
  • 세션 키 형식: Sessions 및 Groups 참조.
• target:
  • last (기본값): 마지막으로 사용된 외부 채널로 전달.
  • 명시적 채널: whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage.
  • none: Heartbeat를 실행하되, 외부로 전달하지 않음.
• to: 선택적인 수신자 오버라이드 (채널-특정 id, 예: WhatsApp의 E.164 또는 Telegram 채팅 id). Telegram 토픽/스레드의 경우 <chatId>:topic:<messageThreadId> 형식을 사용하세요.
• accountId: 멀티-계정 채널을 위한 선택적 계정 id. target: "last"일 때, 계정 id는 계정을 지원하는 해석된 마지막 채널에 적용됩니다; 그렇지 않으면 무시됩니다. 계정 id가 해석된 채널의 구성된 계정과 일치하지 않으면, 전달이 건너뛰어집니다.
• prompt: 기본 프롬프트 본문을 재정의합니다 (병합되지 않음).
• ackMaxChars: 전달 전 HEARTBEAT_OK 후 허용되는 최대 문자 수.
• suppressToolErrorWarnings: true일 경우, Heartbeat 실행 중 도구 에러 경고 페이로드를 억제합니다.
• activeHours: Heartbeat 실행을 시간 창으로 제한. start (HH:MM, 포함; 하루 시작은 00:00 사용), end (HH:MM 제외; 24:00은 하루의 끝까지 허용), 그리고 선택적 timezone을 가진 객체.
  • 생략되었거나 "user": 설정된 경우 agents.defaults.userTimezone를 사용합니다; 그렇지 않을 경우 호스트 시스템 시간대를 기본으로 사용합니다.
  • "local": 항상 호스트 시스템 시간대를 사용합니다.
  • 모든 IANA 식별자 (예: America/New_York): 직접 사용됨; 유효하지 않은 경우 위의 "user" 동작으로 대체됩니다.
  • start와 end는 활성 창이 되려면 같아서는 안 됩니다; 같은 값은 폭이 0인 창(항상 창 밖)으로 처리됩니다.
  • 활동 창 밖에서는, Heartbeat가 다음 창 안쪽의 틱까지 건너뜁니다.

​

전달 동작

• 기본적으로 Heartbeat는 에이전트의 메인 세션에서 실행됩니다 (agent:<id>:<mainKey>), 또는 session.scope = "global"일 때는 global. 특정 채널 세션으로 변경하려면 session을 설정합니다 (Discord/WhatsApp/등등).
• session는 실행 컨텍스트에만 영향을 미칩니다; 전달은 target과 to에 의해 제어됩니다.
• 특정 채널/수신자에게 전달하려면, target + to를 설정합니다. target: "last"로 설정할 경우, 해당 세션의 마지막 외부 채널로 전달됩니다.
• 메인 큐가 바쁠 경우, Heartbeat는 건너뛰어지고 나중에 다시 시도됩니다.
• target이 외부 목표로 해석되지 않으면, 실행은 여전히 발생하지만 아웃바운드 메시지는 전송되지 않습니다.
• Heartbeat 전용 응답은 세션을 유지하지 않습니다; 마지막 updatedAt이 복원되어 유휴 만료가 정상적으로 작동합니다.

​

가시성 제어

channels:
  defaults:
    heartbeat:
      showOk: false # HEARTBEAT_OK 숨기기 (기본값)
      showAlerts: true # 경고 메시지 표시 (기본값)
      useIndicator: true # 표시기 이벤트 생성 (기본값)
  telegram:
    heartbeat:
      showOk: true # Telegram에서 OK 확인 표시
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # 이 계정을 위한 경고 전달 억제

​

각 플래그의 기능

• showOk: 모델이 OK-전용 응답을 반환할 때 HEARTBEAT_OK 확인을 보냅니다.
• showAlerts: 모델이 OK가 아닌 응답을 반환할 때 경고 내용을 보냅니다.
• useIndicator: UI 상태 표면을 위한 표시기 이벤트를 생성합니다.

​

채널별 vs 계정별 예시

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # 모든 Slack 계정
    accounts:
      ops:
        heartbeat:
          showAlerts: false # ops 계정에 대한 경고 억제
  telegram:
    heartbeat:
      showOk: true

​

일반 패턴

​

HEARTBEAT.md (선택 사항)

# Heartbeat 체크리스트

- 빠른 스캔: 메일함에 긴급한 일이 있습니까?
- 주간이라면, 다른 대기 작업이 없을 경우 가벼운 체크인을 수행하십시오.
- 작업이 차단된 경우, _무엇이 필요한지_ 적어두고 다음에 Peter에게 문의하십시오.

​

에이전트가 HEARTBEAT.md를 업데이트할 수 있습니까?

• “매일 일정 확인을 추가하기 위해 HEARTBEAT.md를 업데이트하세요.”
• “HEARTBEAT.md를 더 짧고 받은 편지함 후속 작업에 초점을 맞춰 다시 작성하세요.”

​

수동 웨이크 (주문형)

openclaw system event --text "긴급한 후속 조치를 확인하세요" --mode now

​

추론 전달 (선택 사항)

• agents.defaults.heartbeat.includeReasoning: true

​

비용 인식