​

Heartbeat (Gateway(게이트웨이))

Heartbeat vs Cron? 각각을 언제 사용해야 하는지에 대한 안내는 Cron vs Heartbeat를 참고하십시오.

​

빠른 시작 (초보자)

1. Heartbeat 를 활성화된 상태로 유지합니다 (기본값은 30m, Anthropic OAuth/setup-token 의 경우 1h) 또는 원하는 주기를 설정합니다.
2. 에이전트 워크스페이스에 작은 HEARTBEAT.md 체크리스트를 생성합니다 (선택 사항이지만 권장).
3. Heartbeat 메시지를 보낼 위치를 결정합니다 (기본값은 target: "last").
4. 선택 사항: 투명성을 위해 Heartbeat 추론 전달을 활성화합니다.
5. 선택 사항: Heartbeat 를 활성 시간 (로컬 시간)으로 제한합니다.

{
  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/setup-token 이 감지된 인증 모드인 경우 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” 섹션이 포함되며 실행은 내부적으로 플래그 처리됩니다.
• 활성 시간 (heartbeat.activeHours)은 구성된 타임존에서 확인됩니다. 해당 시간대 밖에서는 다음 활성 시간 내 틱까지 Heartbeat 가 건너뛰어집니다.

​

Heartbeat 프롬프트의 용도

• 백그라운드 작업: “미완료 작업을 고려”는 에이전트가 후속 작업 (수신함, 캘린더, 리마인더, 대기 작업)을 검토하고 긴급한 항목을 표시하도록 유도합니다.
• 사람 확인: “낮 시간대에 가끔 사람에게 체크인”은 가벼운 “필요한 것이 있나요?” 메시지를 유도하지만, 구성된 로컬 타임존을 사용하여 야간 스팸을 피합니다 (참고: /concepts/timezone).

​

응답 계약

• 주의가 필요하지 않다면 HEARTBEAT_OK 로 응답합니다.
• Heartbeat 실행 중에는, 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, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific 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 는 전역 Heartbeat 동작을 설정합니다.
• agents.list[].heartbeat 는 그 위에 병합됩니다. 어떤 에이전트든 heartbeat 블록이 있으면 해당 에이전트만 Heartbeat 를 실행합니다.
• 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: "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.",
        },
      },
    ],
  },
}

​

활성 시간 예시

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

​

다중 계정 예시

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          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).
• accountId: 다중 계정 채널을 위한 선택적 계정 id. target: "last" 인 경우, 계정 id 는 계정을 지원하는 경우에만 해석된 마지막 채널에 적용되며, 그렇지 않으면 무시됩니다. 계정 id 가 해석된 채널에 구성된 계정과 일치하지 않으면 전달은 건너뛰어집니다.
• prompt: 기본 프롬프트 본문을 재정의합니다 (병합되지 않음).
• ackMaxChars: HEARTBEAT_OK 이후 전달 전까지 허용되는 최대 문자 수.
• activeHours: Heartbeat 실행을 시간 창으로 제한합니다. start (HH:MM, 포함), end (HH:MM, 제외; 일 종료를 위한 24:00 허용), 선택적 timezone 를 포함하는 객체입니다.
  • 생략되거나 "user": 설정된 agents.defaults.userTimezone 가 있으면 이를 사용하고, 없으면 호스트 시스템 타임존으로 대체합니다.
  • "local": 항상 호스트 시스템 타임존을 사용합니다.
  • 임의의 IANA 식별자 (예: America/New_York): 직접 사용되며, 유효하지 않으면 위의 "user" 동작으로 대체됩니다.
  • 활성 창 밖에서는 다음 활성 시간 내 틱까지 Heartbeat 가 건너뛰어집니다.

​

전달 동작

• Heartbeat 는 기본적으로 에이전트의 메인 세션에서 실행됩니다 (agent:<id>:<mainKey>), 또는 session.scope = "global" 인 경우 global 에서 실행됩니다. 특정 채널 세션 (Discord/WhatsApp 등)으로 재정의하려면 session 를 설정하십시오.
• session 는 실행 컨텍스트에만 영향을 주며, 전달은 target 및 to 로 제어됩니다.
• 특정 채널/수신자로 전달하려면 target + to 를 설정하십시오. target: "last" 를 사용하면 해당 세션의 마지막 외부 채널을 사용하여 전달됩니다.
• 메인 큐가 바쁜 경우 Heartbeat 는 건너뛰어지며 나중에 재시도됩니다.
• target 가 외부 대상이 없는 것으로 해석되면, 실행은 수행되지만 외부로 전송되는 메시지는 없습니다.
• Heartbeat 전용 응답은 세션을 유지하지 않습니다. 마지막 updatedAt 가 복원되어 유휴 만료가 정상적으로 동작합니다.

​

가시성 제어

channels:
  defaults:
    heartbeat:
      showOk: false # Hide HEARTBEAT_OK (default)
      showAlerts: true # Show alert messages (default)
      useIndicator: true # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true # Show OK acknowledgments on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alert delivery for this account

​

각 플래그의 동작

• showOk: 모델이 OK 전용 응답을 반환할 때 HEARTBEAT_OK 확인을 전송합니다.
• showAlerts: 모델이 비 OK 응답을 반환할 때 알림 콘텐츠를 전송합니다.
• useIndicator: UI 상태 표시를 위한 인디케이터 이벤트를 발생시킵니다.

​

채널별 vs 계정별 예시

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

​

일반적인 패턴

​

HEARTBEAT.md (선택 사항)

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

​

에이전트가 HEARTBEAT.md 를 업데이트할 수 있나요?

• “HEARTBEAT.md 를 업데이트하여 일일 캘린더 확인을 추가하세요.”
• “HEARTBEAT.md 를 더 짧고 수신함 후속 작업에 집중하도록 다시 작성하세요.”

​

수동 웨이크 (온디맨드)

openclaw system event --text "Check for urgent follow-ups" --mode now

​

추론 전달 (선택 사항)

• agents.defaults.heartbeat.includeReasoning: true

​

비용 고려