OpenClaw Cron 작업 설정: 자동화 스케줄링 가이드

빠른 시작

OpenClaw의 cron 기능을 사용하면 반복적인 작업이나 예약된 알림을 손쉽게 자동화할 수 있습니다. 다음 명령어를 사용하여 작업을 설정하고 관리해 보세요.

# Add a one-shot reminder
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

# Check your jobs
openclaw cron list

# See run history
openclaw cron runs --id <job-id>

Cron 작동 원리

Cron은 모델 내부가 아닌 Gateway 프로세스 내에서 실행되는 내장 스케줄러입니다. 작업 정의는 ~/.openclaw/cron/jobs.json에 저장되므로 재시작 후에도 일정이 유지됩니다.

작업 정의는 ~/.openclaw/cron/jobs.json에 영구 저장되며, 런타임 상태는 ~/.openclaw/cron/jobs-state.json에 저장됩니다. GitHub 등을 통해 설정을 관리한다면 jobs.json은 포함하고 jobs-state.json은 gitignore 처리하는 것이 좋습니다.
버전 업데이트 후 이전 버전의 OpenClaw는 jobs.json을 읽을 수 있지만, 런타임 필드가 jobs-state.json으로 이동했기 때문에 작업을 새로 생성된 것으로 간주할 수 있습니다.
모든 cron 실행은 background task 기록을 생성합니다.
--at 옵션을 사용한 일회성 작업은 기본적으로 성공 후 자동으로 삭제됩니다.
격리된(Isolated) cron 실행은 작업 완료 시 해당 cron:<jobId> 세션의 브라우저 탭이나 프로세스를 최대한 정리하여, 분리된 브라우저 자동화 작업이 좀비 프로세스를 남기지 않도록 합니다.
격리된 cron 실행은 응답 지연을 방지합니다. 첫 번째 결과가 단순한 중간 상태 업데이트이고 최종 답변을 담당하는 하위 에이전트 실행이 없는 경우, OpenClaw는 결과 전달 전에 실제 결과를 얻기 위해 한 번 더 프롬프트를 보냅니다.

cron에 대한 작업 조정은 런타임이 소유합니다. 활성 cron 작업은 런타임이 해당 작업을 실행 중인 것으로 추적하는 동안 유지됩니다. 런타임이 작업 소유를 중단하고 5분의 유예 기간이 지나면 유지 관리 프로세스가 해당 작업을 lost로 표시할 수 있습니다.

일정 유형

종류	CLI 플래그	설명
`at`	`--at`	일회성 타임스탬프 (ISO 8601 또는 `20m`과 같은 상대 시간)
`every`	`--every`	고정 간격
`cron`	`--cron`	5개 또는 6개 필드의 cron 표현식 (선택적으로 `--tz` 사용)

시간대가 없는 타임스탬프는 UTC로 처리됩니다. 로컬 시간대를 사용하려면 --tz America/New_York와 같이 추가하세요.

매 정시마다 반복되는 표현식은 부하를 줄이기 위해 최대 5분까지 자동으로 분산됩니다. 정확한 타이밍을 원하면 --exact를, 명시적인 범위를 지정하려면 --stagger 30s를 사용하세요.

월간 및 요일별 사용 시 OR 논리

cron 표현식은 croner에 의해 파싱됩니다. 월간 일자와 요일 필드가 모두 와일드카드가 아닐 경우, croner는 두 필드 중 하나라도 일치하면 실행합니다. 이는 표준 Vixie cron 동작입니다.

# 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

이 설정은 매달 0~~1회가 아닌 약 5~~6회 실행됩니다. OpenClaw는 여기서 croner의 기본 OR 동작을 사용합니다. 두 조건을 모두 만족시키려면 croner의 + 요일 수정자(0 9 15 * +1)를 사용하거나, 하나의 필드에서 일정을 잡고 작업 프롬프트나 명령어에서 다른 조건을 제어하세요.

실행 스타일

스타일	`--session` 값	실행 위치	권장 용도
Main session	`main`	다음 하트비트 턴	알림, 시스템 이벤트
Isolated	`isolated`	전용 `cron:<jobId>`	보고서, 백그라운드 작업
Current session	`current`	생성 시점에 바인딩	컨텍스트 기반 반복 작업
Custom session	`session:custom-id`	지속되는 명명된 세션	기록을 쌓아가는 워크플로우

Main session 작업은 시스템 이벤트를 대기열에 넣고 선택적으로 하트비트를 깨웁니다(--wake now 또는 --wake next-heartbeat). Isolated 작업은 새로운 세션으로 전용 에이전트 턴을 실행합니다. Custom sessions(session:xxx)는 실행 간에 컨텍스트를 유지하여 이전 요약을 기반으로 하는 일일 스탠드업과 같은 워크플로우를 가능하게 합니다.

격리된 작업의 경우, 런타임 종료 시 해당 cron 세션에 대한 브라우저 정리가 포함됩니다. 정리 실패는 무시되므로 실제 cron 결과가 우선합니다.

격리된 cron 실행이 하위 에이전트를 조정할 때, 전달 시 이전의 중간 텍스트보다 최종 결과물을 우선합니다. 하위 에이전트가 여전히 실행 중이라면 OpenClaw는 부분적인 상위 업데이트를 발표하는 대신 이를 억제합니다.

격리된 작업을 위한 페이로드 옵션

--message: 프롬프트 텍스트 (격리된 작업에 필수)
--model / --thinking: 모델 및 사고 수준 재정의
--light-context: 워크스페이스 부트스트랩 파일 주입 건너뛰기
--tools exec,read: 작업이 사용할 수 있는 도구 제한

--model은 해당 작업에 허용된 모델을 사용합니다. 요청된 모델이 허용되지 않으면 cron은 경고를 기록하고 작업의 에이전트/기본 모델 선택으로 대체합니다. 구성된 대체 체인은 여전히 적용되지만, 명시적인 작업별 대체 목록이 없는 단순 모델 재정의는 더 이상 에이전트 기본 모델을 숨겨진 추가 재시도 대상으로 추가하지 않습니다.

격리된 작업의 모델 선택 우선순위는 다음과 같습니다.

Gmail 훅 모델 재정의 (실행이 Gmail에서 왔고 해당 재정의가 허용된 경우)
작업별 페이로드 model
저장된 cron 세션 모델 재정의
에이전트/기본 모델 선택

Fast 모드 역시 결정된 라이브 선택을 따릅니다. 선택된 모델 구성에 params.fastMode가 있으면 격리된 cron은 기본적으로 이를 사용합니다. 저장된 세션의 fastMode 재정의는 구성보다 우선합니다.

격리된 실행이 라이브 모델 전환 핸드오프에 도달하면, cron은 전환된 제공자/모델로 재시도하고 재시도 전에 해당 라이브 선택을 유지합니다. 전환에 새로운 인증 프로필이 포함된 경우 cron은 해당 인증 프로필 재정의도 유지합니다. 재시도는 제한되어 있으며, 초기 시도 후 2회의 전환 재시도를 거친 뒤에는 무한 루프를 방지하기 위해 cron이 중단됩니다.

AI Setup Assistant

전달 및 출력 방식

OpenClaw는 작업 결과를 어떻게 전달할지 결정하는 다양한 모드를 제공합니다. 아래 표를 참고하여 작업 성격에 맞는 전달 방식을 선택해 보세요.

모드	동작 방식
`announce`	대상 채널로 요약본 전송 (isolated 모드 기본값)
`webhook`	완료된 이벤트 페이로드를 특정 URL로 POST 전송
`none`	내부적으로만 처리하며 별도 전달 없음

채널로 결과를 보내려면 --announce --channel telegram --to "-1001234567890" 옵션을 사용하세요. Telegram 포럼 토픽의 경우 -1001234567890:topic:123 형식을 사용하면 됩니다. Slack, Discord, Mattermost 대상은 channel:<id> 또는 user:<id>와 같이 명시적인 접두사를 붙여야 합니다.

cron으로 실행되는 isolated 작업의 경우, 러너(runner)가 최종 전달 경로를 결정합니다. 에이전트는 일반 텍스트 요약본을 반환하도록 요청받으며, 이 요약본은 announce, webhook을 통해 전송되거나 none 모드일 경우 내부적으로 유지됩니다. --no-deliver 옵션은 전달 권한을 에이전트에게 넘기지 않고 작업을 내부적으로만 처리합니다.

만약 원래 작업 내용에 외부 수신자에게 메시지를 보내라는 명시적인 지시가 있다면, 에이전트는 직접 메시지를 보내려 하지 말고 출력 결과에 수신자와 위치를 기록해야 합니다.

실패 알림은 별도의 경로를 따릅니다:

cron.failureDestination은 실패 알림에 대한 전역 기본값을 설정합니다.
job.delivery.failureDestination은 작업별로 이를 재정의합니다.
두 설정이 모두 없고 작업이 announce를 통해 전달되는 경우, 실패 알림은 해당 기본 announce 대상으로 전달됩니다.
delivery.failureDestination은 기본 전달 모드가 webhook인 경우를 제외하고, sessionTarget="isolated" 작업에서만 지원됩니다.

CLI 예시

OpenClaw를 사용하여 작업을 예약하고 결과를 확인하는 구체적인 방법입니다. 상황에 맞는 명령어를 참고해 보세요.

일회성 알림 (메인 세션):

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

전달 기능을 포함한 반복적인 isolated 작업:

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"

모델 및 사고(thinking) 설정을 재정의한 isolated 작업:

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

AI Setup Assistant

Webhooks

Gateway는 외부 트리거를 위해 HTTP webhook 엔드포인트를 노출할 수 있습니다. 설정에서 다음과 같이 활성화하세요.

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

인증

모든 요청에는 헤더를 통해 hook 토큰이 포함되어야 합니다.

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

쿼리 스트링 토큰은 거부됩니다.

POST /hooks/wake

메인 세션을 위한 시스템 이벤트를 대기열에 추가합니다.

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"}'

text (필수): 이벤트 설명
mode (선택): now (기본값) 또는 next-heartbeat

POST /hooks/agent

격리된 agent 턴을 실행합니다.

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-mini"}'

필드: message (필수), name, agentId, wakeMode, deliver, channel, to, model, thinking, timeoutSeconds.

매핑된 hooks (POST /hooks/<name>)

사용자 지정 hook 이름은 설정의 hooks.mappings를 통해 확인됩니다. 매핑을 사용하면 템플릿이나 코드 변환을 통해 임의의 페이로드를 wake 또는 agent 작업으로 변환할 수 있습니다.

보안

hook 엔드포인트는 루프백, tailnet 또는 신뢰할 수 있는 리버스 프록시 뒤에 두세요.
전용 hook 토큰을 사용하세요. Gateway 인증 토큰을 재사용하지 마세요.
hooks.path는 전용 하위 경로로 유지하세요. / 경로는 거부됩니다.
hooks.allowedAgentIds를 설정하여 명시적인 agentId 라우팅을 제한하세요.
호출자가 선택한 세션이 필요한 경우가 아니라면 hooks.allowRequestSessionKey=false로 유지하세요.
hooks.allowRequestSessionKey를 활성화하는 경우, 허용된 세션 키 형태를 제한하기 위해 hooks.allowedSessionKeyPrefixes도 함께 설정하세요.
hook 페이로드는 기본적으로 안전 경계로 감싸져 있습니다.

Gmail PubSub 통합

OpenClaw Webhooks 기능을 사용하여 Google PubSub을 통해 Gmail 받은 편지함 트리거를 연결할 수 있습니다.

사전 요구 사항: gcloud CLI, gog (gogcli), OpenClaw hooks 활성화, 공개 HTTPS 엔드포인트를 위한 Tailscale.

마법사 설정 (권장)

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

이 명령은 hooks.gmail 설정을 작성하고, Gmail 프리셋을 활성화하며, 푸시 엔드포인트에 Tailscale Funnel을 사용합니다.

Gateway 자동 시작

hooks.enabled=true이고 hooks.gmail.account가 설정되어 있으면, Gateway는 부팅 시 gog gmail watch serve를 시작하고 watch를 자동 갱신합니다. 이 기능을 사용하지 않으려면 OPENCLAW_SKIP_GMAIL_WATCHER=1을 설정하세요.

수동 일회성 설정

gog에서 사용하는 OAuth 클라이언트를 소유한 GCP 프로젝트를 선택하세요:

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

토픽을 생성하고 Gmail 푸시 액세스 권한을 부여하세요:

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

watch를 시작하세요:

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",
    },
  },
}

작업 관리하기

반복되는 작업을 자동화하고 싶을 때 OpenClaw cron 기능을 사용하면 일정을 효율적으로 제어할 수 있습니다. 아래 명령어를 통해 등록된 작업을 조회하거나 수정하고, 필요에 따라 즉시 실행하는 등 유연하게 관리해 보세요.

모든 작업 목록을 확인하려면 openclaw cron list를 사용하세요.
특정 작업을 수정하려면 openclaw cron edit <jobId> —message “Updated prompt” —model “opus” 명령어를 입력하세요.
작업을 지금 바로 강제로 실행하려면 **openclaw cron run <jobId>**를 사용하세요.
예정된 시간에만 실행되도록 하려면 openclaw cron run <jobId> —due를 입력하세요.
작업 실행 기록을 확인하려면 openclaw cron runs —id <jobId> —limit 50을 사용하세요.
작업을 삭제하려면 **openclaw cron remove <jobId>**를 실행하세요.
멀티 에이전트 환경에서 작업을 추가하거나 에이전트 설정을 변경하려면 아래 명령어를 활용하세요.

# List all jobs
openclaw cron list

# 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

모델 재정의 시 참고할 사항은 다음과 같습니다.

openclaw cron add|edit —model … 명령은 해당 작업에 선택된 모델을 변경합니다.
모델이 허용된 경우, 해당 provider와 모델이 격리된 에이전트 실행에 그대로 적용됩니다.
모델이 허용되지 않은 경우, cron은 경고를 표시하고 작업의 에이전트 또는 기본 모델 설정으로 돌아갑니다.
설정된 폴백 체인은 여전히 유효하지만, 명시적인 작업별 폴백 목록 없이 —model만 재정의하는 경우, 에이전트 기본값으로 조용히 넘어가는 추가 재시도 대상이 되지 않습니다.

설정 구성하기

OpenClaw cron 설정은 JSON 형식의 구성 파일을 통해 세밀하게 조정할 수 있습니다. 아래 설정을 통해 재시도 정책이나 로그 보관 주기 등을 직접 관리해 보세요.

{
  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 },
  },
}

런타임 상태 사이드카는 cron.store에서 파생됩니다. 예를 들어 ~/clawd/cron/jobs.json과 같은 JSON 저장소는 ~/clawd/cron/jobs-state.json을 사용하며, JSON 확장자가 없는 저장소 경로는 뒤에 -state.json이 붙습니다.

cron 기능을 비활성화하려면 cron.enabled: false로 설정하거나 OPENCLAW_SKIP_CRON=1 환경 변수를 사용하세요.

일회성 재시도: 일시적인 오류(rate limit, overload, network, server error)는 지수 백오프를 사용하여 최대 3회까지 재시도합니다. 영구적인 오류는 즉시 비활성화됩니다.

반복 재시도: 재시도 간에는 지수 백오프(30초에서 60분 사이)가 적용됩니다. 백오프는 다음 성공적인 실행 후에 초기화됩니다.

유지 관리: cron.sessionRetention(기본값 24h)은 격리된 실행 세션 항목을 정리합니다. cron.runLog.maxBytes 및 cron.runLog.keepLines는 실행 로그 파일을 자동으로 정리합니다.

문제 해결

OpenClaw를 사용하다 보면 예상치 못한 동작이나 설정 오류를 마주할 수 있습니다. 아래의 CLI 명령어를 사용하여 시스템 상태를 점검하고 문제를 진단해 보세요.

다음 명령어를 통해 Gateway 및 cron 작업의 현재 상태를 확인합니다.

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

Cron 작업이 실행되지 않을 때

OpenClaw의 cron 작업이 의도대로 동작하지 않는다면 다음 사항들을 먼저 확인해 보세요.

cron.enabled 설정과 OPENCLAW_SKIP_CRON 환경 변수가 올바르게 지정되었는지 확인합니다.
Gateway가 중단 없이 계속 실행 중인지 확인합니다.
cron 스케줄의 경우, 호스트의 시간대와 설정된 시간대(--tz)가 일치하는지 확인합니다.
실행 결과에 reason: not-due가 표시된다면, openclaw cron run <jobId> --due 명령어로 수동 실행을 시도했을 때 아직 작업 실행 시점이 도래하지 않았음을 의미합니다.

Cron은 실행되었으나 결과가 전달되지 않을 때

작업은 완료되었지만 메시지가 전송되지 않는다면 다음 원인들을 검토해야 합니다.

전달 모드가 none으로 설정되어 있으면 외부 메시지 전송이 발생하지 않습니다.
전달 대상(channel 또는 to)이 누락되었거나 잘못된 경우, 외부 전송 단계가 건너뛰어집니다.
채널 인증 오류(unauthorized, Forbidden)가 발생하면 자격 증명 문제로 인해 전송이 차단된 것입니다.
격리된 실행 결과로 NO_REPLY 또는 no_reply 토큰만 반환되는 경우, OpenClaw는 직접적인 외부 전송과 대기열 요약 경로를 모두 억제하므로 채팅으로 아무런 응답이 전달되지 않습니다.
cron이 소유한 격리 작업의 경우, 에이전트가 메시지 도구를 대체 수단으로 사용하지 않도록 주의하세요. 실행 주체가 최종 전달을 담당하며, --no-deliver 옵션은 직접 전송을 허용하는 대신 내부적으로 처리하도록 합니다.

시간대 관련 주의사항

OpenClaw에서 시간대를 다룰 때는 다음 규칙을 기억하세요.

--tz 옵션 없이 cron을 설정하면 Gateway 호스트의 시간대를 사용합니다.
시간대 설정이 없는 at 스케줄은 기본적으로 UTC로 처리됩니다.
하트비트의 activeHours는 설정된 시간대 해석 방식을 따릅니다.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.