자동화 트러블슈팅

스케줄러 및 전달 문제 (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

크론이 실행되지 않음

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

정상적인 출력 예시:

cron status가 활성화 상태와 미래의 nextWakeAtMs를 보고합니다.
작업이 활성화되어 있고 유효한 스케줄/시간대가 설정되어 있습니다.
cron runs가 ok 또는 명시적인 건너뛰기 사유를 표시합니다.

일반적인 징후:

cron: scheduler disabled; jobs will not run automatically → 설정/환경 변수에서 크론이 비활성화되어 있습니다.
cron: timer tick failed → 스케줄러 틱이 충돌했습니다. 주변의 스택/로그 컨텍스트를 확인하세요.
실행 출력에 reason: not-due → --force 없이 수동 실행을 호출했지만 작업이 아직 실행 시점이 아닙니다.

크론이 실행되었지만 전달 없음

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

정상적인 출력 예시:

실행 상태가 ok입니다.
격리 작업에 전달 모드/대상이 설정되어 있습니다.
채널 프로브가 대상 채널이 연결되었다고 보고합니다.

일반적인 징후:

실행은 성공했지만 전달 모드가 none → 외부 메시지가 예상되지 않습니다.
전달 대상이 누락/유효하지 않음 (channel/to) → 실행은 내부적으로 성공하지만 아웃바운드가 건너뛰어질 수 있습니다.
채널 인증 오류 (unauthorized, missing_scope, Forbidden) → 채널 자격 증명/권한에 의해 전달이 차단됩니다.

하트비트가 억제되거나 건너뛰어짐

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

정상적인 출력 예시:

하트비트가 0이 아닌 간격으로 활성화되어 있습니다.
마지막 하트비트 결과가 ran입니다 (또는 건너뛰기 사유가 이해됩니다).

일반적인 징후:

heartbeat skipped, reason=quiet-hours → activeHours 범위 밖입니다.
requests-in-flight → 메인 레인이 사용 중이어서 하트비트가 지연됩니다.
empty-heartbeat-file → HEARTBEAT.md에 실행 가능한 내용이 없고 태그된 크론 이벤트가 대기열에 없어서 간격 하트비트가 건너뛰어졌습니다.
alerts-disabled → 가시성 설정이 아웃바운드 하트비트 메시지를 억제합니다.

시간대 및 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는 키가 설정되지 않았음을 의미합니다. 하트비트는 호스트 시간대로 대체됩니다 (또는 설정된 경우 activeHours.timezone).
--tz 없는 크론은 게이트웨이 호스트 시간대를 사용합니다.
하트비트 activeHours는 설정된 시간대 해석을 사용합니다 (user, local, 또는 명시적 IANA 시간대).
시간대 없는 ISO 타임스탬프는 크론 at 스케줄에서 UTC로 처리됩니다.

일반적인 징후:

호스트 시간대 변경 후 작업이 잘못된 벽시계 시간에 실행됩니다.
activeHours.timezone이 잘못되어 낮 시간에 하트비트가 항상 건너뛰어집니다.