예약된 작업 (Cron)

Cron은 Gateway의 내장 스케줄러입니다. 작업을 영속적으로 저장하고, 적절한 시점에 에이전트를 깨우며, 출력을 채팅 채널이나 웹훅 엔드포인트로 다시 전달할 수 있습니다.

빠른 시작

# 일회성 리마인더 추가
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 runs --id <job-id>

cron 작동 방식

Cron은 모델 내부가 아니라 Gateway 프로세스 내부에서 실행됩니다.
작업은 ~/.openclaw/cron/jobs.json에 영속 저장되므로 재시작해도 예약이 사라지지 않습니다.
모든 cron 실행은 백그라운드 작업 레코드를 생성합니다.
일회성 작업(--at)은 기본적으로 성공 후 자동 삭제됩니다.
격리된 cron 실행은 완료 시 해당 cron:<jobId> 세션에 대해 추적 중인 브라우저 탭/프로세스를 가능한 범위에서 종료하므로, 분리된 브라우저 자동화가 고아 프로세스를 남기지 않도록 합니다.
격리된 cron 실행은 오래된 확인 응답도 방지합니다. 첫 번째 결과가 단지 임시 상태 업데이트(on it, pulling everything together 및 이와 유사한 안내)이고, 최종 답변을 아직 담당 중인 하위 에이전트 실행이 없는 경우, OpenClaw는 실제 결과를 전달하기 전에 한 번 더 재프롬프트합니다.

cron의 작업 재조정은 런타임이 소유합니다. 이전 하위 세션 행이 여전히 존재하더라도, cron 런타임이 해당 작업을 실행 중으로 계속 추적하는 동안 활성 cron 작업은 살아 있는 상태로 유지됩니다. 런타임이 더 이상 작업을 소유하지 않고 5분의 유예 시간이 지나면, 유지 관리가 해당 작업을 lost로 표시할 수 있습니다.

예약 유형

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

시간대가 없는 타임스탬프는 UTC로 처리됩니다. 로컬 벽시계 기준 예약을 사용하려면 --tz America/New_York를 추가하세요. 매시 정각에 반복되는 표현식은 부하 급증을 줄이기 위해 최대 5분까지 자동으로 분산됩니다. 정확한 시각을 강제하려면 --exact를 사용하고, 명시적인 범위를 지정하려면 --stagger 30s를 사용하세요.

day-of-month와 day-of-week는 OR 로직을 사용합니다

Cron 표현식은 croner로 파싱됩니다. day-of-month와 day-of-week 필드가 모두 와일드카드가 아닐 경우, croner는 두 필드가 모두 일치할 때가 아니라 둘 중 하나가 일치할 때 일치로 판단합니다. 이는 표준 Vixie cron 동작입니다.

# 의도: "15일이 월요일일 때만 오전 9시"
# 실제: "매월 15일 오전 9시, 그리고 매주 월요일 오전 9시"
0 9 15 * 1

이 표현식은 월 0~~1회가 아니라 월 약 5~~6회 실행됩니다. OpenClaw는 여기서 Croner의 기본 OR 동작을 사용합니다. 두 조건을 모두 요구하려면 Croner의 + day-of-week 수정자(0 9 15 * +1)를 사용하거나, 한 필드만으로 예약하고 다른 조건은 작업의 프롬프트나 명령에서 별도로 검사하세요.

실행 스타일

스타일	`--session` 값	실행 위치	적합한 용도
메인 세션	`main`	다음 heartbeat 턴	리마인더, 시스템 이벤트
격리됨	`isolated`	전용 `cron:<jobId>`	보고서, 백그라운드 작업
현재 세션	`current`	생성 시점에 바인딩됨	컨텍스트 인식 반복 작업
사용자 지정 세션	`session:custom-id`	영속적 이름 지정 세션	기록을 기반으로 하는 워크플로

메인 세션 작업은 시스템 이벤트를 큐에 넣고 필요하면 heartbeat를 깨웁니다(--wake now 또는 --wake next-heartbeat). 격리됨 작업은 새 세션으로 전용 에이전트 턴을 실행합니다. 사용자 지정 세션(session:xxx)은 실행 간 컨텍스트를 유지하므로, 이전 요약을 바탕으로 하는 일일 스탠드업 같은 워크플로를 구현할 수 있습니다. 격리된 작업의 경우, 이제 런타임 정리 단계에 해당 cron 세션에 대한 가능한 범위의 브라우저 정리가 포함됩니다. 정리 실패는 실제 cron 결과가 우선되도록 무시됩니다. 격리된 cron 실행이 하위 에이전트를 오케스트레이션할 때는, 전달 과정에서도 오래된 상위 임시 텍스트보다 최종 하위 출력이 우선됩니다. 하위 에이전트가 아직 실행 중이면, OpenClaw는 해당 부분적인 상위 업데이트를 알리지 않고 억제합니다.

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

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

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

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

빠른 모드도 해결된 실제 선택을 따릅니다. 선택된 모델 구성에 params.fastMode가 있으면, 격리된 cron은 기본적으로 이를 사용합니다. 저장된 세션 fastMode 재정의는 어느 방향에서든 구성보다 우선합니다. 격리된 실행 중 실제 모델 전환 handoff가 발생하면, cron은 전환된 provider/model로 재시도하고 재시도 전에 해당 실제 선택을 저장합니다. 전환에 새 인증 프로필도 포함되어 있으면, cron은 그 인증 프로필 재정의도 저장합니다. 재시도 횟수는 제한됩니다. 초기 시도 후 전환 재시도 2회가 지나면 cron은 무한 반복 대신 중단합니다.

전달 및 출력

모드	동작
`announce`	대상 채널에 요약 전달(격리됨의 기본값)
`webhook`	완료된 이벤트 페이로드를 URL로 POST
`none`	내부 전용, 전달 없음

채널 전달에는 --announce --channel telegram --to "-1001234567890"를 사용하세요. Telegram 포럼 토픽에는 -1001234567890:topic:123을 사용하세요. Slack/Discord/Mattermost 대상은 명시적 접두사(channel:<id>, user:<id>)를 사용해야 합니다. cron이 소유한 격리 작업의 경우, 실행기가 최종 전달 경로를 소유합니다. 에이전트는 일반 텍스트 요약을 반환하도록 프롬프트되며, 그 요약은 이후 announce, webhook을 통해 전송되거나 none의 경우 내부에만 유지됩니다. --no-deliver는 전달 책임을 에이전트로 되돌리지 않습니다. 대신 실행을 내부 전용으로 유지합니다. 원래 작업이 일부 외부 수신자에게 메시지를 보내라고 명시적으로 지시하는 경우, 에이전트는 직접 전송을 시도하는 대신 그 메시지를 누구/어디로 보내야 하는지 출력을 통해 알려야 합니다. 실패 알림은 별도의 대상 경로를 따릅니다.

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

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"

모델 및 thinking 재정의가 포함된 격리 작업:

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

웹훅

Gateway는 외부 트리거를 위한 HTTP 웹훅 엔드포인트를 노출할 수 있습니다. 구성에서 활성화하세요.

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

인증

모든 요청은 헤더를 통해 hook token을 포함해야 합니다.

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

격리된 에이전트 턴을 실행합니다.

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.

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

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

보안

hook 엔드포인트는 loopback, tailnet 또는 신뢰할 수 있는 reverse proxy 뒤에 두세요.
전용 hook token을 사용하세요. gateway 인증 토큰을 재사용하지 마세요.
hooks.path는 전용 하위 경로로 유지하세요. /는 거부됩니다.
명시적 agentId 라우팅을 제한하려면 hooks.allowedAgentIds를 설정하세요.
호출자가 세션을 선택해야 하는 경우가 아니라면 hooks.allowRequestSessionKey=false로 유지하세요.
hooks.allowRequestSessionKey를 활성화하는 경우, 허용되는 session key 형태를 제한하기 위해 hooks.allowedSessionKeyPrefixes도 함께 설정하세요.
hook 페이로드는 기본적으로 안전 경계로 감싸집니다.

Gmail PubSub 통합

Google PubSub를 통해 Gmail 받은편지함 트리거를 OpenClaw에 연결합니다. 사전 요구 사항: gcloud CLI, gog (gogcli), 활성화된 OpenClaw hooks, 공개 HTTPS 엔드포인트용 Tailscale.

마법사 설정 (권장)

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

이 명령은 hooks.gmail 구성을 작성하고, Gmail 프리셋을 활성화하며, push 엔드포인트에 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 push 액세스 권한을 부여합니다.

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 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>

# 에이전트 선택(멀티 에이전트 구성)
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/model이 격리된 에이전트 실행에 전달됩니다.
허용되지 않으면 cron은 경고를 표시하고 작업의 에이전트/기본 모델 선택으로 폴백합니다.
구성된 폴백 체인은 계속 적용되지만, 명시적인 작업별 폴백 목록이 없는 일반 --model 재정의는 더 이상 에이전트 기본 모델로 조용히 추가 재시도되는 대상이 되지 않습니다.

구성

{
  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 비활성화: 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 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이 실행되지 않음

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이 소유한 격리 작업의 경우, 에이전트가 폴백으로 message 도구를 사용할 것이라고 기대하지 마세요. 최종 전달은 실행기가 소유하며, --no-deliver는 직접 전송을 허용하는 대신 내부 전용으로 유지합니다.

시간대 관련 주의사항

--tz가 없는 cron은 gateway 호스트 시간대를 사용합니다.
시간대가 없는 at 일정은 UTC로 처리됩니다.
Heartbeat activeHours는 구성된 시간대 해석을 사용합니다.

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

예약된 작업

예약된 작업 (Cron)

빠른 시작

cron 작동 방식

예약 유형

day-of-month와 day-of-week는 OR 로직을 사용합니다

실행 스타일

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

전달 및 출력

CLI 예시

웹훅

인증

POST /hooks/wake

POST /hooks/agent

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

보안

Gmail PubSub 통합

마법사 설정 (권장)

Gateway 자동 시작

수동 일회성 설정

Gmail 모델 재정의

작업 관리

구성

문제 해결

명령 순서

Cron이 실행되지 않음

Cron이 실행됐지만 전달되지 않음

시간대 관련 주의사항

관련 문서

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​예약된 작업 (Cron)

​빠른 시작

​cron 작동 방식

​예약 유형

​day-of-month와 day-of-week는 OR 로직을 사용합니다

​실행 스타일

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

​전달 및 출력

​CLI 예시

​웹훅

​인증

​POST /hooks/wake

​POST /hooks/agent

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

​보안

​Gmail PubSub 통합

​마법사 설정 (권장)

​Gateway 자동 시작

​수동 일회성 설정

​Gmail 모델 재정의

​작업 관리

​구성

​문제 해결

​명령 순서

​Cron이 실행되지 않음

​Cron이 실행됐지만 전달되지 않음

​시간대 관련 주의사항

​관련 문서

예약된 작업 (Cron)

빠른 시작

cron 작동 방식

예약 유형

day-of-month와 day-of-week는 OR 로직을 사용합니다

실행 스타일

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

전달 및 출력

CLI 예시

웹훅

인증

POST /hooks/wake

POST /hooks/agent

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

보안

Gmail PubSub 통합

마법사 설정 (권장)

Gateway 자동 시작

수동 일회성 설정

Gmail 모델 재정의

작업 관리

구성

문제 해결

명령 순서

Cron이 실행되지 않음

Cron이 실행됐지만 전달되지 않음

시간대 관련 주의사항

관련 문서