🦞 32. HEARTBEAT_OK만 반복될 때 바로 고치는 방법

heartbeat 자동 점검은 돌고 있는데 사용자에게는 HEARTBEAT_OK만 보이고, 정작 해야 할 작업은 하나도 이어지지 않는 장면이 있다. 이때 많은 사람이 “heartbeat가 죽었나?”부터 의심하지만, 실제 현장에서는 프로세스 장애보다 판정 로직이 너무 빨리 OK로 닫혀버린 경우가 훨씬 많다.

특히 운영 메모를 날짜 파일로 쓰는지, memory/오늘.md 같은 고정 파일로 쓰는지, 시작 알림과 완료 알림을 분리했는지에 따라 체감이 크게 달라진다. 여기에 하나가 더 있다. quota reset wakeup이나 scheduled reminder를 받은 뒤 오늘 계획을 다시 읽지 않으면, 이벤트는 정상인데 후속 실행만 비는 장면이 자주 생긴다. 완료 로그는 있는데 체크박스만 다시 [ ]로 보이는 드리프트 장면까지 함께 보려면 34. heartbeat에서 완료한 작업이 다시 미완료로 보일 때를 같이 보면 원인 분리가 훨씬 빨라진다. 기본 구조가 먼저 필요하면 OpenClaw 06: Cron Job 자동화 기본과 OpenClaw 25: 크론·서브에이전트 분산 운영을 먼저 같이 보는 편이 좋다.

30초 진단표

지금 보이는 증상	먼저 확인할 것	바로 이어서 할 일
HEARTBEAT_OK만 반복되고 할 일은 남아 있음	memory/오늘.md와 실제 날짜 파일이 같은 계획을 보고 있는지	기준 파일 1개로 맞춘 뒤 overdue 항목만 다시 판정
scheduled reminder나 quota reset 알림은 왔는데 실행이 안 붙음	알림 직후 오늘 계획 원본을 재로딩했는지	오늘 계획 재확인 → overdue 판정 → 시작 알림 순서 강제
파일은 바뀌었는데 사용자 체감상 아무 일도 안 한 것 같음	시작 알림과 완료 알림이 분리돼 남는지	파일 수정 전에 시작 알림, 끝난 뒤 완료 알림 추가
오전엔 정상인데 오후부터 갑자기 빈 응답처럼 보임	heartbeat마다 같은 캐시 결과를 재사용하는지	매 heartbeat마다 오늘 계획 원본을 다시 읽기

이 표의 목적은 원인을 길게 찾지 않게 하는 것이다. 현장에서는 HEARTBEAT_OK 자체보다 무슨 조건에서 OK가 확정됐는지를 먼저 잡아야 복구가 빨라진다.

이 문서를 바로 봐야 하는 신호

아래 중 하나라도 맞으면, 단순히 “지금 할 일 없음”으로 넘기지 말고 heartbeat 판정 순서를 다시 보는 편이 빠르다.

• 오늘 할 일 [ ] 항목이 분명 있는데도 HEARTBEAT_OK만 계속 온다.
• 작업 파일은 수정되는데 사용자 채널에는 시작/완료 흐름이 보이지 않는다.
• 오전에는 정상인데 오후부터 갑자기 빈 응답처럼 보인다.
• quota reset, scheduled reminder, cron wakeup 뒤에도 후속 액션이 붙지 않는다.

flowchart TD
A[Heartbeat 수신] --> B[오늘 계획 원본 다시 읽기]
B --> C{미완료 항목 존재?}
C -- 아니오 --> H[HEARTBEAT_OK]
C -- 예 --> D{현재 시각 지난 항목 존재?}
D -- 아니오 --> H
D -- 예 --> E[시작 알림]
E --> F[실제 작업 실행]
F --> G[완료 알림 + 체크박스/로그 갱신]

칠판 치트시트

1. heartbeat마다 오늘 계획 원본을 다시 읽는다
2. [ ] 항목 중 지금 시각을 지난 것이 있는지 본다
3. 있으면 HEARTBEAT_OK를 보내지 말고 시작 알림 → 실행 → 완료 알림 순서로 간다
4. 없을 때만 마지막 단계에서 HEARTBEAT_OK를 확정한다

10초 판단: 지금 바로 실행 대상인지 보는 법

아래 세 줄만 만족하면, 이건 설명이 아니라 실행으로 넘어가야 한다.

1. 오늘 계획에 [ ]로 남아 있다.
2. 현재 시각이 예정 시각과 같거나 지났다.
3. 같은 task-key 완료 로그가 아직 없다.

예를 들어 11:00 heartbeat에서 [ ] 11:00 | 상위 유입 페이지 리라이트 1건이 보이고 완료 로그가 없다면, 이 시점에는 HEARTBEAT_OK가 아니라 즉시 실행이 맞다. 반대로 14:00 작업이라면 11:00에는 아직 OK로 닫아도 된다. 이 차이를 명확히 두면 과잉 실행과 빈 응답을 같이 줄일 수 있다.

왜 HEARTBEAT_OK만 반복되는가

대부분 원인은 아래 셋 중 하나로 수렴한다.

1) 오늘 계획 파일을 잘못 읽고 있다

운영 문서가 memory/오늘.md가 아니라 memory/YYYY-MM-DD.md 형태인데도, heartbeat가 한 경로만 고정해서 보면 실제 미완료 항목을 놓친다. 이 경우 사람 눈에는 “할 일이 분명 있는데 시스템은 없다고 한다”로 보인다.

여기서는 파일 경로 자체보다 오늘의 source of truth를 어디로 둘지를 먼저 고정해야 한다. 날짜 파일을 기준으로 운영한다면 heartbeat도 매번 그 날짜 파일을 다시 열어야 한다. 공식 정보는 버전에 따라 달라질 수 있으니 운영 전에 OpenClaw docs와 OpenClaw source repo를 현재 버전 기준으로 함께 보는 습관이 안전하다.

실무 미니 사례

• 오전 9시에 memory/2026-04-13.md에 작업 3개를 만들었다.
• 그런데 heartbeat는 계속 memory/오늘.md만 찾았다.
• 결과적으로 실제 작업은 남아 있는데도 HEARTBEAT_OK가 반복됐다.

검증 포인트

• 사람이 보는 오늘 계획 파일과 heartbeat가 읽는 파일이 같은지 1회 확인한다.
• 둘이 다르면, 로직 문제로 먼저 분류한다.

2) 시간 비교가 빠져 있다

미완료 항목이 있다는 사실만으로는 실행하면 안 되고, 반대로 미완료 항목이 있어도 지금 시각을 지난 항목인지를 확인하지 않으면 영원히 대기만 하거나 영원히 OK만 보낼 수 있다.

예를 들어 14:00 작업은 11:00 heartbeat에서 아직 실행하면 안 된다. 하지만 11:00 작업은 11:05 heartbeat에서 바로 실행 대상이다. 결국 핵심은 체크박스 유무가 아니라 미완료 + 시각 경과 두 조건을 함께 보는 것이다.

실무 미니 사례

• [ ] 11:00 | 상위 유입 페이지 리라이트 1건
• 11:05인데도 시스템이 체크박스 개수만 세고 종료함
• 사용자는 “heartbeat가 멍청해졌다”고 느끼지만, 실제 문제는 시각 비교 누락이다

검증 포인트

• 현재 시각이 지난 항목 1개를 골라 사람이 직접 “이건 지금 실행 대상”이라고 말할 수 있어야 한다.
• 그 설명이 안 되면 OK 판정이 너무 빠르다고 본다.

3) 시작 알림 없이 파일만 수정한다

작업은 실제로 했는데도 사용자는 계속 HEARTBEAT_OK만 기억하는 경우가 있다. 이건 실행 실패라기보다 체감 실패에 가깝다.

운영 관점에서는 시작 알림과 완료 알림이 중요하다. 시작 알림이 있어야 “지금 heartbeat가 일을 잡았구나”를 알 수 있고, 완료 알림이 있어야 “실행 후 체크박스가 바뀌었구나”를 확인할 수 있다. CLI status 문서와 sessions 문서는 현재 상태·세션 범위를 재확인할 때 함께 보면 도움이 된다.

실무 미니 사례

• 내부적으로 문서 파일은 수정됐다.
• 하지만 사용자 채널에는 시작/완료 신호가 하나도 없었다.
• 결과적으로 운영자는 “아무것도 안 했다”고 판단했다.

검증 포인트

• 시작 알림, 완료 알림, 체크박스 갱신 로그가 한 세트로 남는지 본다.
• 셋 중 하나라도 없으면 재발 가능성이 높다.

5분 복구 순서

1) 오늘 계획의 기준 파일을 먼저 고정한다

가장 먼저 할 일은 오늘 계획의 기준 파일을 하나로 정하는 것이다. memory/오늘.md를 쓸지, memory/YYYY-MM-DD.md를 쓸지, 둘 다 쓸지 먼저 정해야 한다.

이 단계가 중요한 이유는 heartbeat가 아무리 자주 돌더라도 잘못된 파일을 읽으면 영원히 맞는 판정을 할 수 없기 때문이다. 실무에서는 파일 존재 여부보다 “운영자가 실제로 손대는 파일”과 “heartbeat가 읽는 파일”이 같은지부터 맞추는 편이 빠르다.

2) 미완료 항목을 다시 세지 말고, 실행 대상만 추린다

다음으로는 [ ] 항목 전체를 세기보다 지금 시각을 지난 항목만 골라낸다. 이때는 아래처럼 생각하면 된다.

• 아직 안 됐고([ ])
• 예정 시각을 지났고
• 동일 task-key 완료 로그가 아직 없으면
• 지금 바로 실행 대상

이렇게 조건을 자르면 HEARTBEAT_OK를 너무 일찍 보내는 실수가 크게 줄어든다.

3) 시작 알림 → 실제 작업 → 완료 알림 순서를 고정한다

순서를 바꾸면 체감이 어긋난다. 특히 파일 수정 후 나중에 알리거나, 완료만 남기고 시작을 생략하면 사람은 heartbeat가 건너뛴 것처럼 느끼기 쉽다.

현장에서는 아래 순서를 그대로 고정하는 편이 가장 안전하다.

1. 시작 알림
2. 실제 작업 실행
3. 체크박스 [x] 반영
4. 완료 로그 한 줄 추가
5. 필요 시 결과 요약 알림

4) 같은 작업을 다시 잡지 않도록 task-key를 본다

heartbeat가 자주 도는 환경에서는 “한 번 끝낸 일”을 다시 잡는 문제가 쉽게 생긴다. 그래서 task-key를 날짜·시간·작업명 기준으로 고정해 두면 중복 실행을 줄이기 쉽다.

예를 들어 2026-04-13|11:00|상위 유입 페이지 리라이트 1건처럼 잡아 두면, 다음 heartbeat는 재실행이 아니라 상태 업데이트만 하게 만들 수 있다. 이 규칙이 없으면 시스템은 바쁘게 움직이는데 산출물은 제자리인 상황이 반복된다.

현장 미니 사례 3개

사례 A) 오전에는 멀쩡했는데 오후부터 갑자기 HEARTBEAT_OK만 온다

• 상황: 오전 heartbeat에서 읽은 상태를 오후에도 그대로 재사용
• 원인: heartbeat마다 오늘 파일을 다시 열지 않음
• 처리: 매 heartbeat마다 오늘 계획 원본 재로딩
• 결과: 오후 overdue 항목을 정상 감지

사례 B) scheduled reminder는 떴는데 후속 액션이 없다

• 상황: 알림 이벤트는 정상 발생
• 원인: 알림을 받은 뒤 실행 대상 판정으로 안 넘어감
• 처리: reminder 수신 후 “오늘 계획 재확인 → overdue 판정” 단계를 강제
• 결과: 알림과 실행이 하나의 흐름으로 이어짐

사례 C) 작업은 했는데 사용자는 계속 HEARTBEAT_OK만 기억한다

• 상황: 내부 파일만 바뀌고 채널 메시지는 생략
• 원인: 시작/완료 알림 순서 누락
• 처리: 시작 알림과 완료 알림을 분리 기록
• 결과: 운영 체감이 좋아지고 디버깅도 쉬워짐

운영자가 바로 써먹을 판별 질문

아래 네 질문에 답하면, 대부분 5분 안에 원인 범위가 줄어든다.

1. heartbeat가 오늘 실제 계획 파일을 보고 있는가?
2. [ ] 항목 중 현재 시각이 지난 것이 있는가?
3. 있으면 시작 알림 → 실행 → 완료 알림이 한 세트로 남는가?
4. 같은 task-key를 이미 끝낸 뒤 또 잡고 있지는 않은가?

네 질문 중 하나라도 “아니오”면, HEARTBEAT_OK 반복은 응답 포맷 문제가 아니라 운영 로직 문제로 보는 편이 맞다.

다음에 읽을 글 (내부링크 10선)

• OpenClaw 06: Cron Job 자동화 기본
• OpenClaw 11: 연동 체크 루틴
• OpenClaw 12: 브라우저 릴레이 연동 구조
• OpenClaw 17: Subagents 실패 패턴 5가지
• OpenClaw 18: 텔레그램 연결끊김 복구
• OpenClaw 20: 운영 아키텍처 규칙 총정리
• OpenClaw 23: node-run 보안 에러 해결
• OpenClaw 25: 크론·서브에이전트 분산 운영
• OpenClaw 31: Quota 리셋 안 됨 해결
• 30. OpenClaw 채널은 연결됐는데 답이 없을 때 해결
• 🚀 OpenClaw 인덱스

다음 추천 읽기: 31. Quota 리셋 안 됨 해결

한 줄 결론

HEARTBEAT_OK 반복 문제는 대개 heartbeat가 죽은 게 아니라, 오늘 계획 원본·시간 비교·알림 순서 중 하나가 빠진 상태다.
오늘 계획을 다시 읽고, overdue만 골라서, 시작 알림 → 실행 → 완료 알림 순서로 고정하면 대부분 바로 풀린다.

※ 이 문서는 생성형 AI를 활용해 작성되었습니다.