HEARTBEAT.md와 주기 점검
Heartbeat는 Agent가 주기적으로 상태를 점검하는 기능입니다. 점검 지침을 작성하는 것만으로 자동 실행이나 Task 생성이 설정되는 것은 아닙니다.
현재 ClawPod Portal에서 heartbeat cadence나 delivery policy를 고객이 직접 설정하는 화면은 확인되지 않았습니다. 따라서 이 페이지는 runtime 기능과 HEARTBEAT.md의 역할을 설명하며, tenant에 기본 제공되는 Portal 자동화 기능이라고 약속하지 않습니다.
HEARTBEAT.md는 무엇인가요?
HEARTBEAT.md는 heartbeat가 실행될 때 Agent가 확인할 짧은 checklist입니다. 새 session bootstrap 대상이지만, heartbeat가 runtime config에서 비활성화되면 normal run에서도 heartbeat 전용 지침을 생략할 수 있습니다.
# Heartbeat Checklist
- [ ] pending message와 실패한 webhook event가 있는지 확인한다.
- [ ] 담당 Room에 이미 같은 알림이 전달됐는지 확인한다.
- [ ] 장기적으로 기록할 확정 결정이 있는지 확인한다.
## When action is needed
- 영향받는 Agent, 조직, event ID를 요약한다.
- 외부 변경은 승인 여부를 먼저 확인한다.
빈 파일이나 제목만 있는 HEARTBEAT.md는 model call을 생략할 수 있습니다. 따라서 “실행하지 않아도 되는 경우”를 길게 적기보다, 정말 필요한 점검만 짧게 둡니다.
실행 조건 확인
점검 실행 여부와 주기, 알림 전달은 Agent의 설정과 준비 상태에 따라 달라집니다. 이 가이드는 모든 Agent가 일정한 간격으로 실행되거나 알림을 전달한다고 보장하지 않습니다.
Portal에서 주기와 전달 대상을 직접 설정하는 절차는 제공하지 않습니다. 실행 조건을 바꿔야 한다면 대상 Agent와 원하는 점검 목적을 운영 담당자에게 전달하세요. 설정 파일이나 명령을 추측해 변경하지 마세요.
HEARTBEAT_OK와 알림
Heartbeat에 문제가 없을 때 Agent는 HEARTBEAT_OK로 acknowledgement할 수 있습니다. 이는 “아무 조치가 필요 없다”는 신호이며, heartbeat 밖의 일반 사용자 응답에 섞어 쓰는 표현이 아닙니다.
중요한 이상이 있을 때는 반복 알림 대신 확인된 영향, 근거, 필요한 승인, 다음 조치를 짧게 전달하게 하세요. heartbeat는 메시지 spam이나 승인 없는 외부 작업을 위한 기능이 아닙니다.
heartbeat와 cron·Task의 차이
| 필요 | 적합한 방식 |
|---|---|
| 가벼운 상태 점검을 한 session 맥락에서 묶어 처리 | Heartbeat |
| 특정 시각에 반드시 실행할 독립 작업 | 현재 ClawPod Cloud 소비자 기능에는 해당 scheduler 설정 경로가 없습니다. 조직이 별도로 제공하는 scheduler가 있을 때만 그 운영 절차를 사용 |
| 실행된 작업의 상태·결과 기록 | Task record |
Task 완료는 다음 heartbeat를 깨울 수 있지만, heartbeat 자체가 Task를 생성하거나 정확히 한 번 실행됨을 보장하지는 않습니다.
운영 checklist
- 이 Agent에 heartbeat가 실제로 실행될 때에만
HEARTBEAT.md의 checklist가 사용됩니다. HEARTBEAT.md는 짧고 저비용인 점검만 담습니다.- 외부 변경은 명시적 승인 없이는 실행하지 않게 합니다.
- 같은 alert를 반복 전송하지 않게 Room·event 기록을 확인합니다.
- 비활성화·active hours·delivery target을 바꾸기 전에는 영향받는 조직과 Agent를 확인합니다.