트리거와 스케줄

OpenClaw에서 자동 실행을 만들 때는 이전 문서에 있던 독립 트리거 CLI나 임의 YAML 스키마를 쓰지 않습니다. 2026-07-13 기준 공식 표면은 Gateway Cron, Cron 이벤트 조건, 시스템 이벤트, Heartbeat, Hooks입니다.

기준일: 2026-07-13 공식 기준: Scheduled tasks, Automation, System CLI, Heartbeat

핵심 개념

표면	역할	공식 관리 명령
Cron	정확한 시간, 반복 주기, 일회성 알림을 Gateway가 실행	openclaw cron ...
Cron 이벤트 조건	every 또는 cron 스케줄이 도래했을 때 조건 스크립트가 fire: true를 반환하면 실행	openclaw cron add --trigger-script ...
System event	main session에 시스템 이벤트를 넣고 즉시 또는 다음 Heartbeat에서 깨움	openclaw system event ...
Heartbeat	main session에서 주기적으로 맥락을 확인하는 agent turn	openclaw system heartbeat ...
Hooks	세션 생명주기나 Gateway 이벤트에 반응하는 스크립트	openclaw hooks ...

Cron은 실행 기록과 task record를 남깁니다. Heartbeat는 periodic main-session turn이며 task record를 만들지 않습니다. 따라서 "주기적으로 확인"이라는 말만으로 Heartbeat를 선택하지 말고, 기록과 정확한 실행 시각이 필요한지 먼저 판단해야 합니다.

선택 기준

필요	선택	이유
매일 9시에 보고서 실행	Cron	정확한 시간과 run history가 필요
20분 뒤 한 번 알림	Cron --at	일회성 스케줄은 성공 후 자동 삭제 가능
PR 상태가 바뀔 때만 실행	Cron 이벤트 조건	스케줄 도래 시 조건 스크립트가 발화 여부 결정
main session이 inbox/calendar를 넓게 확인	Heartbeat	전체 세션 맥락을 유지하면서 묶어서 확인
외부 작업 완료를 main session에 알림	System event	이벤트를 넣고 --mode now 또는 다음 Heartbeat로 전달
/reset, Gateway startup, tool call 같은 생명주기 반응	Hooks 또는 plugin hooks	이벤트 기반 스크립트 표면

피해야 할 표면은 독립 트리거 관리 CLI, top-level 트리거 YAML, 메시지/Heartbeat 액션 스키마처럼 공식 CLI reference에 없는 오래된 형태입니다.

실습

정확한 시간에 agent turn 만들기

openclaw cron create "0 7 * * *" \
  "Summarize overnight updates." \
  --name "Morning brief" \
  --session isolated \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

일회성 시스템 이벤트 넣기

openclaw cron create "20m" \
  --name "Calendar reminder" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now \
  --delete-after-run

조건 스크립트로 발화 제어하기

openclaw cron add \
  --name "PR CI watcher" \
  --every 30s \
  --trigger-script ./watch-pr-ci.js \
  --message "Respond to the CI status change." \
  --session isolated

조건 스크립트는 { fire, message?, state? }를 반환해야 합니다. fire: false이면 run history를 만들지 않고 상태만 저장한 뒤 다음 스케줄로 넘어갑니다.

시스템 이벤트를 직접 넣기

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

--mode next-heartbeat는 다음 정기 Heartbeat에 태우고, --mode now는 즉시 Heartbeat wake를 요청합니다.

관리 명령 확인하기

openclaw cron list
openclaw cron show <job-id>
openclaw cron run <job-id> --wait --wait-timeout 10m
openclaw cron runs --id <job-id> --limit 50
openclaw system heartbeat last
openclaw logs --limit 200

도구에 입력할 프롬프트

OpenClaw에 자동화를 설계시킬 때:

내 요구사항을 Cron, Cron 이벤트 조건, System event, Heartbeat, Hooks 중 하나로 분류해줘.
공식 CLI 명령만 사용하고, 독립 트리거 CLI나 임의 YAML 스키마는 쓰지 마.
정확한 실행 시각, task 기록 필요 여부, 세션 맥락 필요 여부를 기준으로 선택 근거를 표로 정리해줘.

체크리스트

• 정확한 시간 또는 일회성 알림이면 Cron을 선택했다.
• main session 맥락을 유지하는 느슨한 주기 확인이면 Heartbeat를 선택했다.
• 조건부 실행은 Cron 이벤트 조건으로 설계했다.
• 독립 트리거 관리 CLI를 쓰지 않았다.
• 비공식 top-level 트리거 YAML을 쓰지 않았다.
• Cron 실행 확인은 cron list/show/runs, Heartbeat 확인은 system heartbeat last, 로그 확인은 logs 옵션으로만 했다.

다음 단계

• 자동화 개요 - Cron, Heartbeat, tasks, hooks의 전체 선택 기준
• Cron 표현식 가이드 - 스케줄 표현식과 타임존
• Heartbeat 가이드 - main session periodic turn 설정