예약된 작업

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

빠른 시작

openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the cron docs draft" \
  --wake now \
  --delete-after-run

openclaw cron list
openclaw cron get <job-id>
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

​

Cron 작동 방식

• Cron은 Gateway 내부 프로세스에서 실행됩니다(모델 내부가 아님).
• 작업 정의는 ~/.openclaw/cron/jobs.json에 영속화되므로 재시작해도 일정이 손실되지 않습니다.
• 런타임 실행 상태는 그 옆의 ~/.openclaw/cron/jobs-state.json에 영속화됩니다. Cron 정의를 git에서 추적한다면 jobs.json을 추적하고 jobs-state.json은 gitignore에 추가하세요.
• 분리 이후에는 이전 OpenClaw 버전이 jobs.json을 읽을 수는 있지만, 런타임 필드가 이제 jobs-state.json에 있으므로 작업을 새 작업처럼 취급할 수 있습니다.
• Gateway가 실행 중이거나 중지된 상태에서 jobs.json이 편집되면, OpenClaw는 변경된 일정 필드를 보류 중인 런타임 슬롯 메타데이터와 비교하고 오래된 nextRunAtMs 값을 지웁니다. 순수한 포맷 변경이나 키 순서만 바뀐 재작성은 보류 중인 슬롯을 보존합니다.
• 모든 Cron 실행은 백그라운드 작업 레코드를 생성합니다.
• Gateway 시작 시, 기한이 지난 격리된 에이전트 턴 작업은 즉시 재생되는 대신 채널 연결 창 밖으로 다시 예약되므로, 재시작 후에도 Discord/Telegram 시작과 네이티브 명령 설정이 응답성을 유지합니다.
• 일회성 작업(--at)은 기본적으로 성공 후 자동 삭제됩니다.
• 격리된 Cron 실행은 실행이 완료되면 해당 cron:<jobId> 세션의 추적된 브라우저 탭/프로세스를 최선 노력 방식으로 닫으므로, 분리된 브라우저 자동화가 고아 프로세스를 남기지 않습니다.
• 좁은 Cron 자체 정리 권한을 받은 격리된 Cron 실행은 여전히 스케줄러 상태, 현재 작업으로 자체 필터링된 목록, 해당 작업의 실행 기록을 읽을 수 있으므로, 상태/Heartbeat 확인이 더 넓은 Cron 변경 권한을 얻지 않고도 자체 일정을 검사할 수 있습니다.
• 격리된 Cron 실행은 오래된 확인 응답도 방지합니다. 첫 결과가 임시 상태 업데이트(on it, pulling everything together 및 유사한 힌트)일 뿐이고 최종 답변을 책임지는 하위 서브에이전트 실행이 아직 없다면, OpenClaw는 전달 전에 실제 결과를 한 번 다시 프롬프트합니다.
• 격리된 Cron 실행은 내장 실행의 구조화된 실행 거부 메타데이터를 우선 사용한 다음, SYSTEM_RUN_DENIED 및 INVALID_REQUEST 같은 알려진 최종 요약/출력 마커로 폴백하므로, 차단된 명령이 정상 실행으로 보고되지 않습니다.
• 격리된 Cron 실행은 응답 페이로드가 생성되지 않은 경우에도 실행 수준 에이전트 실패를 작업 오류로 처리하므로, 모델/제공자 실패가 작업을 성공으로 지우는 대신 오류 카운터를 증가시키고 실패 알림을 트리거합니다.
• 격리된 에이전트 턴 작업이 timeoutSeconds에 도달하면 Cron은 기본 에이전트 실행을 중단하고 짧은 정리 시간을 부여합니다. 실행이 비워지지 않으면, Cron이 타임아웃을 기록하기 전에 Gateway가 소유한 정리가 해당 실행의 세션 소유권을 강제로 지워, 대기 중인 채팅 작업이 오래된 처리 세션 뒤에 남지 않게 합니다.
• 격리된 에이전트 턴이 러너 시작 전이나 첫 모델 호출 전에 멈추면, Cron은 setup timed out before runner start 또는 stalled before first model call (last phase: context-engine) 같은 단계별 타임아웃을 기록합니다. 이러한 워치독은 외부 CLI 프로세스가 실제로 시작되기 전의 내장 제공자와 CLI 기반 제공자를 포괄하며, 긴 timeoutSeconds 값과 독립적으로 제한되므로 콜드 스타트/인증/컨텍스트 실패가 전체 작업 예산을 기다리지 않고 빠르게 드러납니다.

​

일정 유형

​

월의 일자와 요일은 OR 논리를 사용합니다

# Intended: "9 AM on the 15th, only if it's a Monday"
# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
0 9 15 * 1

​

실행 스타일

​

격리된 작업의 페이로드 옵션

1. Gmail 훅 모델 오버라이드(실행이 Gmail에서 왔고 해당 오버라이드가 허용된 경우)
2. 작업별 페이로드 model
3. 사용자가 선택해 저장한 Cron 세션 모델 오버라이드
4. 에이전트/기본 모델 선택

​

전달 및 출력

• cron.failureDestination은 실패 알림의 전역 기본값을 설정합니다.
• job.delivery.failureDestination은 작업별로 이를 재정의합니다.
• 둘 다 설정되지 않았고 작업이 이미 announce로 전달하는 경우, 실패 알림은 이제 해당 기본 announce 대상으로 폴백합니다.
• delivery.failureDestination은 기본 전달 모드가 webhook인 경우를 제외하고 sessionTarget="isolated" 작업에서만 지원됩니다.
• failureAlert.includeSkipped: true는 작업 또는 전역 cron 알림 정책이 반복적인 건너뜀 실행 알림을 받도록 합니다. 건너뛴 실행은 별도의 연속 건너뜀 카운터를 유지하므로 실행 오류 백오프에 영향을 주지 않습니다.

​

CLI 예시

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

​

Webhook

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

​

인증

• Authorization: Bearer <token>(권장)
• x-openclaw-token: <token>

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'

​

Gmail PubSub 통합

​

마법사 설정(권장)

openclaw webhooks gmail setup --account openclaw@gmail.com

​

Gateway 자동 시작

​

수동 1회 설정

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

​

Gmail 모델 재정의

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

​

작업 관리

# List all jobs
openclaw cron list

# Get one stored job as JSON
openclaw cron get <jobId>

# Show one job, including resolved delivery route
openclaw cron show <jobId>

# Edit a job
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# Force run a job now
openclaw cron run <jobId>

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent

​

구성

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

​

문제 해결

​

명령 단계

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

​

관련 항목

• 자동화 — 모든 자동화 메커니즘 한눈에 보기
• Background Tasks — Cron 실행용 작업 원장
• Heartbeat — 주기적인 메인 세션 턴
• 시간대 — 시간대 구성