예약된 작업

Cron은 Gateway에 내장된 스케줄러입니다. 작업을 유지하고, 적절한 시간에 에이전트를 깨우며, 출력을 채팅 채널이나 Webhook 엔드포인트로 다시 전달할 수 있습니다.

# 빠른 시작

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 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 소유 정리가 해당 실행의 세션 소유권을 강제로 지워 대기 중인 채팅 작업이 오래된 처리 세션 뒤에 남지 않도록 합니다.

# 스케줄 유형

시간대가 없는 타임스탬프는 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 동작입니다.

# 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)를 사용하거나, 한 필드에 스케줄을 걸고 다른 필드는 작업의 프롬프트나 명령에서 가드하세요.

# 실행 스타일

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

--model은 선택된 허용 모델을 해당 작업의 기본 모델로 사용합니다. 이는 채팅 세션 /model 오버라이드와 같지 않습니다. 작업 기본 모델이 실패하면 구성된 폴백 체인이 계속 적용됩니다. 요청된 모델이 허용되지 않았거나 해석할 수 없으면, Cron은 작업의 에이전트/기본 모델 선택으로 조용히 폴백하는 대신 명시적인 검증 오류로 실행을 실패 처리합니다.

이전 또는 수동 편집된 jobs.json 항목이 payload.model을 "default", "null", 빈 문자열 또는 JSON null로 저장하고 있다면 openclaw doctor --fix를 실행하세요. Doctor는 이러한 유효하지 않은 유지된 오버라이드 센티널을 제거합니다. 런타임은 이를 폴백 별칭으로 지원하지 않습니다. 일반 에이전트/기본 모델 선택을 사용하려면 모델 필드를 생략하세요.

Cron 작업은 페이로드 수준 fallbacks도 포함할 수 있습니다. 이 목록이 있으면 작업에 대해 구성된 폴백 체인을 대체합니다. 선택된 모델만 시도하는 엄격한 Cron 실행을 원할 때는 작업 페이로드/API에서 fallbacks: []를 사용하세요. 작업에 --model이 있지만 페이로드 또는 구성된 폴백이 없다면, OpenClaw는 명시적인 빈 폴백 오버라이드를 전달하여 에이전트 기본 모델이 숨겨진 추가 재시도 대상으로 덧붙지 않도록 합니다.

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

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

Fast 모드도 해석된 라이브 선택을 따릅니다. 선택된 모델 구성에 params.fastMode가 있으면 격리된 Cron은 기본적으로 이를 사용합니다. 저장된 세션 fastMode 오버라이드는 어느 방향이든 구성보다 여전히 우선합니다.

격리된 실행이 라이브 모델 전환 핸드오프를 만나면, Cron은 전환된 제공자/모델로 재시도하고 재시도 전에 해당 라이브 선택을 활성 실행에 유지합니다. 전환에 새 인증 프로필도 포함되어 있으면, Cron은 해당 인증 프로필 오버라이드도 활성 실행에 유지합니다. 재시도는 제한됩니다. 최초 시도 후 전환 재시도 2회를 넘기면, Cron은 무한 루프 대신 중단합니다.

격리된 Cron 실행이 에이전트 러너에 진입하기 전에, OpenClaw는 baseUrl이 local loopback, 사설 네트워크 또는 .local인 구성된 api: "ollama" 및 api: "openai-completions" 제공자에 대해 도달 가능한 로컬 제공자 엔드포인트를 확인합니다. 해당 엔드포인트가 다운되어 있으면 실행은 모델 호출을 시작하는 대신 명확한 제공자/모델 오류와 함께 skipped로 기록됩니다. 엔드포인트 결과는 5분 동안 캐시되므로, 동일한 죽은 로컬 Ollama, vLLM, SGLang 또는 LM Studio 서버를 사용하는 많은 만료 작업은 요청 폭주를 만드는 대신 하나의 작은 프로브를 공유합니다. 건너뛴 제공자 프리플라이트 실행은 실행 오류 백오프를 증가시키지 않습니다. 반복적인 건너뜀 알림을 원한다면 failureAlert.includeSkipped를 활성화하세요.

# 전달 및 출력

채널 전달에는 --announce --channel telegram --to "-1001234567890"를 사용하세요. Telegram 포럼 주제에는 -1001234567890:topic:123을 사용하세요. 직접 RPC/config 호출자는 delivery.threadId를 문자열이나 숫자로 전달할 수도 있습니다. Slack/Discord/Mattermost 대상은 명시적 접두사(channel:<id>, user:<id>)를 사용해야 합니다. Matrix 방 ID는 대소문자를 구분하므로, 정확한 방 ID 또는 Matrix의 room:!room:server 형식을 사용하세요.

announce 전달이 channel: "last"를 사용하거나 channel을 생략하는 경우, telegram:123 같은 제공자 접두사가 붙은 대상은 cron이 세션 기록이나 단일 구성 채널로 대체되기 전에 채널을 선택할 수 있습니다. 로드된 Plugin이 광고한 접두사만 제공자 선택자입니다. delivery.channel이 명시적이면 대상 접두사는 같은 제공자 이름이어야 합니다. 예를 들어 channel: "whatsapp"와 to: "telegram:123" 조합은 WhatsApp이 Telegram ID를 전화번호로 해석하게 두지 않고 거부됩니다. channel:<id>, user:<id>, imessage:<handle>, sms:<number> 같은 대상 종류 및 서비스 접두사는 제공자 선택자가 아니라 채널 소유 대상 구문으로 남습니다.

격리된 작업의 경우 채팅 전달은 공유됩니다. 채팅 경로를 사용할 수 있으면 작업이 --no-deliver를 사용하더라도 에이전트가 message 도구를 사용할 수 있습니다. 에이전트가 구성된/현재 대상에 보내면 OpenClaw는 대체 announce를 건너뜁니다. 그렇지 않으면 announce, webhook, none은 에이전트 턴 이후 러너가 최종 응답으로 무엇을 할지만 제어합니다.

에이전트가 활성 채팅에서 격리된 알림을 생성하면 OpenClaw는 대체 announce 경로를 위해 보존된 실시간 전달 대상을 저장합니다. 내부 세션 키는 소문자일 수 있지만, 현재 채팅 컨텍스트를 사용할 수 있을 때 제공자 전달 대상은 해당 키에서 재구성되지 않습니다.

암시적 announce 전달은 구성된 채널 허용 목록을 사용해 오래된 대상을 검증하고 다시 라우팅합니다. DM 페어링 저장소 승인은 대체 자동화 수신자가 아닙니다. 예약 작업이 DM으로 선제적으로 보내야 하는 경우 delivery.to를 설정하거나 채널 allowFrom 항목을 구성하세요.

실패 알림은 별도의 대상 경로를 따릅니다.

• 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

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

{
  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 통합

Google PubSub을 통해 Gmail 받은편지함 트리거를 OpenClaw에 연결합니다.

# 마법사 설정(권장)

openclaw webhooks gmail setup --account [email protected]

이는 hooks.gmail config를 작성하고, Gmail preset을 활성화하며, 푸시 엔드포인트에 Tailscale Funnel을 사용합니다.

# Gateway 자동 시작

hooks.enabled=true이고 hooks.gmail.account가 설정되면 Gateway는 부팅 시 gog gmail watch serve를 시작하고 watch를 자동 갱신합니다. 제외하려면 OPENCLAW_SKIP_GMAIL_WATCHER=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:[email protected] \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account [email protected] \
  --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

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

maxConcurrentRuns는 예약된 cron 디스패치와 격리된 에이전트 턴 실행을 모두 제한합니다. 격리된 cron 에이전트 턴은 내부적으로 큐의 전용 cron-nested 실행 레인을 사용하므로, 이 값을 높이면 독립적인 cron LLM 실행이 외부 cron 래퍼만 시작하는 대신 병렬로 진행될 수 있습니다. 공유 비 cron nested 레인은 이 설정으로 확장되지 않습니다.

런타임 상태 사이드카는 cron.store에서 파생됩니다. ~/clawd/cron/jobs.json 같은 .json 저장소는 ~/clawd/cron/jobs-state.json을 사용하고, .json 접미사가 없는 저장소 경로는 -state.json을 덧붙입니다.

jobs.json을 직접 편집하는 경우 jobs-state.json은 소스 제어에 포함하지 마세요. OpenClaw는 해당 사이드카를 대기 중 슬롯, 활성 마커, 마지막 실행 메타데이터, 그리고 외부에서 편집된 작업에 새로운 nextRunAtMs가 필요할 때 스케줄러에 알려주는 일정 식별자에 사용합니다.

cron 비활성화: cron.enabled: false 또는 OPENCLAW_SKIP_CRON=1.

# 문제 해결

# 명령어 단계

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 실행의 작업 원장
• Heartbeat — 주기적인 메인 세션 턴
• 시간대 — 시간대 구성