OpenClaw 자동화 문제 해결: 5분 만에 크론 및 전송 오류 수정

자동화가 조용히 멈춰버리면 정말 당황스럽죠. 분명히 설정을 마쳤는데 왜 동작하지 않는지, 어디서부터 손을 대야 할지 막막한 개발자분들을 위해 준비했습니다.

이 가이드는 cron과 heartbeat를 포함한 스케줄러 및 전송 이슈를 해결하는 데 도움을 드립니다.

명령어 단계별 확인

먼저 시스템의 전반적인 상태를 파악해야 합니다. 아래 명령어들을 순서대로 실행해 보세요.

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

그다음 자동화 관련 체크를 진행합니다.

openclaw cron status
openclaw cron list
openclaw system heartbeat last

Cron이 실행되지 않을 때

Cron이 아예 트리거되지 않는다면 아래 명령어들로 상태를 점검하세요.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

정상적인 출력 결과는 다음과 같아요.

• cron status에서 활성화 상태로 표시되고, 미래의 nextWakeAtMs 값이 보입니다.
• Job이 활성화되어 있고 유효한 schedule 및 timezone 설정을 가지고 있습니다.
• cron runs 결과가 ok이거나 명확한 skip 이유를 보여줍니다.

자주 발생하는 문제 징후는 다음과 같습니다.

• cron: scheduler disabled; jobs will not run automatically → 설정이나 환경 변수에서 cron이 비활성화된 상태입니다.
• cron: timer tick failed → 스케줄러 틱에서 크래시가 발생했습니다. 주변의 스택 추적이나 로그 컨텍스트를 살펴보세요.
• 실행 출력에 reason: not-due 표시 → --force 옵션 없이 수동 실행을 호출했으나, 아직 Job 실행 시간이 되지 않았습니다.

Cron은 실행됐지만 전송되지 않을 때

Cron은 정상적으로 트리거되었는데 실제 전송이 이루어지지 않는 경우입니다.

openclaw cron runs --id <jobId> --limit 20
openclaw cron list
openclaw channels status --probe
openclaw logs --follow

정상적인 출력 결과는 다음과 같아요.

• Run 상태가 ok로 표시됩니다.
• 개별 Job에 대해 delivery mode와 target이 올바르게 설정되어 있습니다.
• Channel probe 결과 대상 channel이 연결된 것으로 나타납니다.

자주 발생하는 문제 징후는 다음과 같습니다.

• 실행은 성공했지만 delivery mode가 none인 경우 → 외부 메시지 전송이 예정되어 있지 않습니다.
• 전송 대상이 누락되었거나 잘못된 경우 (channel 또는 to) → 내부적으로는 실행에 성공해도 외부 전송은 건너뜁니다.
• Channel 인증 에러 (unauthorized, missing_scope, Forbidden) → channel의 자격 증명이나 권한 문제로 전송이 차단되었습니다.

Heartbeat가 억제되거나 건너뛰어질 때

Heartbeat가 예상대로 작동하지 않을 때는 다음을 확인하세요.

openclaw system heartbeat last
openclaw logs --follow
openclaw config get agents.defaults.heartbeat
openclaw channels status --probe

정상적인 출력 결과는 다음과 같아요.

• Heartbeat가 활성화되어 있고 간격(interval)이 0이 아닙니다.
• 마지막 heartbeat 결과가 ran이거나, 납득할 만한 skip 이유가 있습니다.

자주 발생하는 문제 징후는 다음과 같습니다.

• heartbeat skipped와 함께 reason=quiet-hours 표시 → 설정된 activeHours 이외의 시간대입니다.
• requests-in-flight → 메인 레인이 바빠서 heartbeat가 뒤로 밀린 상태입니다.
• empty-heartbeat-file → HEARTBEAT.md 파일은 존재하지만 실행 가능한 내용이 없습니다.
• alerts-disabled → 가시성(visibility) 설정으로 인해 외부 heartbeat 메시지가 억제되었습니다.

Timezone 및 activeHours 주의 사항

시간대 설정은 자동화에서 가장 흔히 실수하는 부분입니다.

openclaw config get agents.defaults.heartbeat.activeHours
openclaw config get agents.defaults.heartbeat.activeHours.timezone
openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
openclaw cron list
openclaw logs --follow

기억해야 할 빠른 규칙들입니다.

• Config path not found: agents.defaults.userTimezone 메시지는 해당 키가 설정되지 않았음을 의미합니다. 이 경우 heartbeat는 호스트의 timezone을 따르거나, 설정되어 있다면 activeHours.timezone을 사용합니다.
• --tz 옵션이 없는 Cron은 Gateway 호스트의 timezone을 사용합니다.
• Heartbeat의 activeHours는 설정된 timezone 우선순위(user, local, 또는 명시적인 IANA tz)를 따릅니다.
• timezone 정보가 없는 ISO 타임스탬프는 cron at 스케줄에서 UTC로 처리됩니다.

자주 발생하는 문제 징후는 다음과 같습니다.

• 호스트의 timezone이 변경된 후 Job이 엉뚱한 시간에 실행됩니다.
• activeHours.timezone 설정 오류로 인해 실제 활동 시간인데도 heartbeat가 계속 건너뛰어집니다.

문제가 계속 해결되지 않는다면 AI Setup Assistant에게 도움을 요청해 보세요.

다음 단계

• /automation/cron-jobs
• /gateway/heartbeat
• /automation/cron-vs-heartbeat
• /concepts/timezone