크론 작업 (Gateway 스케줄러)

크론 vs 하트비트? 각각 언제 사용해야 하는지는 크론 vs 하트비트를 참고하세요.

크론은 Gateway에 내장된 스케줄러입니다. 작업을 영속적으로 저장하고, 적절한 시점에 에이전트를 깨우며, 선택적으로 채팅에 결과를 전달할 수 있습니다.

“매일 아침 이걸 실행해줘” 또는 “20분 후에 에이전트를 깨워줘” 같은 작업이 필요하다면, 크론이 바로 그 메커니즘입니다.

트러블슈팅: /automation/troubleshooting

요약

  • 크론은 Gateway 내부에서 실행됩니다 (모델 내부가 아닙니다).
  • 작업은 ~/.openclaw/cron/ 아래에 영속적으로 저장되므로, 재시작해도 스케줄이 사라지지 않습니다.
  • 두 가지 실행 방식:
    • 메인 세션: 시스템 이벤트를 대기열에 넣고, 다음 하트비트에서 실행합니다.
    • 격리 세션: cron:<jobId> 내에서 전용 에이전트 턴을 실행하며, 전달 방식을 지정할 수 있습니다 (기본값: announce, 또는 none).
  • 웨이크업은 일급 기능으로, 작업에서 “지금 깨우기”와 “다음 하트비트” 중 선택할 수 있습니다.
  • 작업별로 delivery.mode = "webhook" + delivery.to = "<url>"을 통해 웹훅 전송을 설정할 수 있습니다.
  • 레거시 호환을 위해 notify: true가 설정된 기존 작업은 cron.webhook이 설정되어 있을 때 대체 전송을 수행합니다. 이러한 작업은 webhook 전달 모드로 마이그레이션하세요.
  • 업그레이드 시 openclaw doctor --fix를 실행하면, 스케줄러가 처리하기 전에 레거시 크론 저장소 필드를 정규화할 수 있습니다.

빠른 시작 (실행 가능)

일회성 리마인더를 만들고, 확인한 후 즉시 실행합니다:

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 run <job-id>
openclaw cron runs --id <job-id>

전달 기능이 포함된 반복 격리 작업 스케줄 설정:

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"

도구 호출 등가 형식 (Gateway 크론 도구)

정규 JSON 구조와 예시는 도구 호출용 JSON 스키마를 참고하세요.

크론 작업 저장 위치

크론 작업은 기본적으로 Gateway 호스트의 ~/.openclaw/cron/jobs.json에 영속적으로 저장됩니다. Gateway가 파일을 메모리에 로드하고 변경 시 다시 기록하므로, 수동 편집은 Gateway가 중지된 상태에서만 안전합니다. 변경은 openclaw cron add/edit 또는 크론 도구 호출 API를 사용하세요.

초보자를 위한 개요

크론 작업은 다음과 같이 생각하면 됩니다: 언제 실행할지 + 무엇을 할지.

  1. 스케줄 선택

    • 일회성 리마인더 → schedule.kind = "at" (CLI: --at)
    • 반복 작업 → schedule.kind = "every" 또는 schedule.kind = "cron"
    • ISO 타임스탬프에 시간대가 생략되면 UTC로 처리됩니다.

  2. 실행 위치 선택

    • sessionTarget: "main" → 메인 컨텍스트로 다음 하트비트에서 실행합니다.
    • sessionTarget: "isolated" → cron:<jobId>에서 전용 에이전트 턴을 실행합니다.

  3. 페이로드 선택

    • 메인 세션 → payload.kind = "systemEvent"
    • 격리 세션 → payload.kind = "agentTurn"

선택 사항: 일회성 작업 (schedule.kind = "at")은 성공 후 기본적으로 삭제됩니다. deleteAfterRun: false로 설정하면 유지됩니다 (성공 후 비활성화됨).

개념

작업

크론 작업은 다음 정보가 저장된 레코드입니다:

  • 스케줄 (언제 실행할지),
  • 페이로드 (무엇을 할지),
  • 선택적 전달 모드 (announce, webhook, 또는 none).
  • 선택적 에이전트 바인딩 (agentId): 특정 에이전트로 작업을 실행합니다. 없거나 알 수 없는 경우 기본 에이전트로 대체됩니다.

작업은 안정적인 jobId로 식별됩니다 (CLI/Gateway API에서 사용). 에이전트 도구 호출에서 jobId가 정규 형식이며, 레거시 id는 호환성을 위해 허용됩니다. 일회성 작업은 성공 후 기본적으로 자동 삭제됩니다. deleteAfterRun: false로 설정하면 유지할 수 있습니다.

스케줄

크론은 세 가지 스케줄 종류를 지원합니다:

  • at: schedule.at을 통한 일회성 타임스탬프 (ISO 8601).
  • every: 고정 간격 (ms).
  • cron: 5필드 크론 표현식 (또는 6필드, 초 포함)과 선택적 IANA 시간대.

크론 표현식은 croner를 사용합니다. 시간대가 생략되면 Gateway 호스트의 로컬 시간대가 사용됩니다.

여러 게이트웨이에 걸친 정시 부하 집중을 줄이기 위해, OpenClaw는 정시 반복 표현식(예: 0 * * * *, 0 */2 * * *)에 대해 작업별로 최대 5분의 결정론적 분산 윈도우를 적용합니다. 0 7 * * *과 같은 고정 시간 표현식은 정확한 시간을 유지합니다.

모든 크론 스케줄에서 schedule.staggerMs로 명시적 분산 윈도우를 설정할 수 있습니다 (0이면 정확한 타이밍 유지). CLI 단축키:

  • --stagger 30s (또는 1m, 5m)로 명시적 분산 윈도우를 설정합니다.
  • --exact로 staggerMs = 0을 강제합니다.

메인 vs 격리 실행

메인 세션 작업 (시스템 이벤트)

메인 작업은 시스템 이벤트를 대기열에 넣고 선택적으로 하트비트 러너를 깨웁니다. payload.kind = "systemEvent"를 사용해야 합니다.

  • wakeMode: "now" (기본값): 이벤트가 즉시 하트비트 실행을 트리거합니다.
  • wakeMode: "next-heartbeat": 이벤트가 다음 예정된 하트비트까지 대기합니다.

일반 하트비트 프롬프트 + 메인 세션 컨텍스트가 필요한 경우에 적합합니다. 하트비트를 참고하세요.

격리 작업 (전용 크론 세션)

격리 작업은 cron:<jobId> 세션에서 전용 에이전트 턴을 실행합니다.

주요 동작:

  • 추적을 위해 프롬프트에 [cron:<jobId> <작업 이름>] 접두사가 붙습니다.
  • 각 실행은 새로운 세션 ID로 시작합니다 (이전 대화 이력이 이어지지 않음).
  • 기본 동작: delivery가 생략되면, 격리 작업은 요약을 전달합니다 (delivery.mode = "announce").
  • delivery.mode에 따라 동작이 결정됩니다:
    • announce: 대상 채널에 요약을 전달하고 메인 세션에 간략한 요약을 게시합니다.
    • webhook: 완료 이벤트 페이로드에 요약이 포함된 경우 delivery.to로 POST합니다.
    • none: 내부 전용 (전달 없음, 메인 세션 요약 없음).
  • wakeMode는 메인 세션 요약 게시 시점을 제어합니다:
    • now: 즉시 하트비트.
    • next-heartbeat: 다음 예정된 하트비트까지 대기.

메인 채팅 기록을 어지럽히지 않아야 하는 빈번하거나 시끄러운 “백그라운드 잡무”에 격리 작업을 사용하세요.

페이로드 구조 (실행 내용)

두 가지 페이로드 종류가 지원됩니다:

  • systemEvent: 메인 세션 전용, 하트비트 프롬프트를 통해 라우팅됩니다.
  • agentTurn: 격리 세션 전용, 전용 에이전트 턴을 실행합니다.

일반적인 agentTurn 필드:

  • message: 필수 텍스트 프롬프트.
  • model / thinking: 선택적 오버라이드 (아래 참고).
  • timeoutSeconds: 선택적 타임아웃 오버라이드.
  • lightContext: 워크스페이스 부트스트랩 파일 주입이 필요 없는 작업을 위한 선택적 경량 부트스트랩 모드.

전달 설정:

  • delivery.mode: none | announce | webhook.
  • delivery.channel: last 또는 특정 채널.
  • delivery.to: 채널별 대상 (announce) 또는 웹훅 URL (webhook 모드).
  • delivery.bestEffort: announce 전달이 실패해도 작업 실패로 처리하지 않습니다.

Announce 전달은 해당 실행의 메시지 도구 발송을 억제합니다. 채팅으로 타겟팅하려면 delivery.channel/delivery.to를 사용하세요. delivery.mode = "none"이면 메인 세션에 요약이 게시되지 않습니다.

격리 작업에 delivery가 생략되면, OpenClaw는 기본적으로 announce로 설정합니다.

Announce 전달 흐름

delivery.mode = "announce"일 때, 크론은 아웃바운드 채널 어댑터를 통해 직접 전달합니다. 메인 에이전트가 메시지를 작성하거나 전달하기 위해 시작되지 않습니다.

동작 세부사항:

  • 콘텐츠: 격리 실행의 아웃바운드 페이로드(텍스트/미디어)를 일반 청킹 및 채널 포맷팅으로 전달합니다.
  • 하트비트 전용 응답 (실질적 콘텐츠 없는 HEARTBEAT_OK)은 전달되지 않습니다.
  • 격리 실행이 이미 같은 대상으로 메시지 도구를 통해 메시지를 보낸 경우, 중복을 방지하기 위해 전달이 건너뛰어집니다.
  • 전달 대상이 없거나 유효하지 않으면 delivery.bestEffort = true가 아닌 한 작업이 실패합니다.
  • delivery.mode = "announce"일 때만 메인 세션에 짧은 요약이 게시됩니다.
  • 메인 세션 요약은 wakeMode를 따릅니다: now는 즉시 하트비트를 트리거하고, next-heartbeat는 다음 예정된 하트비트까지 대기합니다.

Webhook 전달 흐름

delivery.mode = "webhook"일 때, 크론은 완료 이벤트에 요약이 포함된 경우 delivery.to로 완료 이벤트 페이로드를 POST합니다.

동작 세부사항:

  • 엔드포인트는 유효한 HTTP(S) URL이어야 합니다.
  • Webhook 모드에서는 채널 전달을 시도하지 않습니다.
  • Webhook 모드에서는 메인 세션 요약이 게시되지 않습니다.
  • cron.webhookToken이 설정되어 있으면, 인증 헤더는 Authorization: Bearer <cron.webhookToken>입니다.
  • 더 이상 사용되지 않는 대체 방식: notify: true가 설정된 레거시 작업은 (설정된 경우) cron.webhook으로 여전히 게시되며, 마이그레이션 경고가 표시됩니다. delivery.mode = "webhook"으로 마이그레이션하세요.

모델 및 사고 레벨 오버라이드

격리 작업 (agentTurn)은 모델과 사고 레벨을 오버라이드할 수 있습니다:

  • model: 제공자/모델 문자열 (예: anthropic/claude-sonnet-4-20250514) 또는 별칭 (예: opus)
  • thinking: 사고 레벨 (off, minimal, low, medium, high, xhigh; GPT-5.2 + Codex 모델만 해당)

참고: 메인 세션 작업에도 model을 설정할 수 있지만, 공유 메인 세션 모델이 변경됩니다. 예기치 않은 컨텍스트 변경을 피하려면 격리 작업에서만 모델 오버라이드를 권장합니다.

해석 우선순위:

  1. 작업 페이로드 오버라이드 (최우선)
  2. 훅별 기본값 (예: hooks.gmail.model)
  3. 에이전트 설정 기본값

경량 부트스트랩 컨텍스트

격리 작업 (agentTurn)은 lightContext: true를 설정하여 경량 부트스트랩 컨텍스트로 실행할 수 있습니다.

  • 워크스페이스 부트스트랩 파일 주입이 필요 없는 예약 잡무에 사용하세요.
  • 실제로 임베디드 런타임은 bootstrapContextMode: "lightweight"로 실행되며, 의도적으로 크론 부트스트랩 컨텍스트를 비워둡니다.
  • CLI 등가 명령: openclaw cron add --light-context ... 및 openclaw cron edit --light-context.

전달 (채널 + 대상)

격리 작업은 최상위 delivery 설정을 통해 채널로 출력을 전달할 수 있습니다:

  • delivery.mode: announce (채널 전달), webhook (HTTP POST), 또는 none.
  • delivery.channel: whatsapp / telegram / discord / slack / mattermost (플러그인) / signal / imessage / last.
  • delivery.to: 채널별 수신 대상.

announce 전달은 격리 작업 (sessionTarget: "isolated")에서만 유효합니다. webhook 전달은 메인 및 격리 작업 모두에서 유효합니다.

delivery.channel이나 delivery.to가 생략되면, 크론은 메인 세션의 “마지막 경로” (에이전트가 마지막으로 응답한 곳)로 대체할 수 있습니다.

대상 형식 참고:

  • Slack/Discord/Mattermost(플러그인) 대상은 모호함을 피하기 위해 명시적 접두사를 사용해야 합니다 (예: channel:<id>, user:<id>). Mattermost의 순수 26자 ID는 사용자 우선으로 해석됩니다 (사용자가 존재하면 DM, 아니면 채널) — 결정론적 라우팅을 위해 user:<id> 또는 channel:<id>를 사용하세요.
  • Telegram 토픽은 :topic: 형식을 사용해야 합니다 (아래 참고).

Telegram 전달 대상 (토픽 / 포럼 스레드)

Telegram은 message_thread_id를 통해 포럼 토픽을 지원합니다. 크론 전달에서는 to 필드에 토픽/스레드를 인코딩할 수 있습니다:

  • -1001234567890 (채팅 ID만)
  • -1001234567890:topic:123 (권장: 명시적 토픽 마커)
  • -1001234567890:123 (약식: 숫자 접미사)

telegram:... / telegram:group:...과 같은 접두사 대상도 허용됩니다:

  • telegram:group:-1001234567890:topic:123

도구 호출용 JSON 스키마

Gateway cron.* 도구를 직접 호출할 때 (에이전트 도구 호출 또는 RPC) 이 구조를 사용하세요. CLI 플래그는 20m 같은 사람이 읽을 수 있는 기간을 허용하지만, 도구 호출에서는 schedule.at에 ISO 8601 문자열을, schedule.everyMs에 밀리초를 사용해야 합니다.

cron.add 매개변수

일회성 메인 세션 작업 (시스템 이벤트):

{
  "name": "Reminder",
  "schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": { "kind": "systemEvent", "text": "Reminder text" },
  "deleteAfterRun": true
}

전달 기능이 포함된 반복 격리 작업:

{
  "name": "Morning brief",
  "schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "agentTurn",
    "message": "Summarize overnight updates.",
    "lightContext": true
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890",
    "bestEffort": true
  }
}

참고:

  • schedule.kind: at (at), every (everyMs), 또는 cron (expr, 선택적 tz).
  • schedule.at은 ISO 8601을 허용합니다 (시간대 선택 사항, 생략 시 UTC로 처리).
  • everyMs는 밀리초입니다.
  • sessionTarget은 "main" 또는 "isolated"이어야 하며 payload.kind와 일치해야 합니다.
  • 선택적 필드: agentId, description, enabled, deleteAfterRun (at의 경우 기본값 true), delivery.
  • wakeMode는 생략 시 기본값 "now"입니다.

cron.update 매개변수

{
  "jobId": "job-123",
  "patch": {
    "enabled": false,
    "schedule": { "kind": "every", "everyMs": 3600000 }
  }
}

참고:

  • jobId가 정규 형식이며, id는 호환성을 위해 허용됩니다.
  • 에이전트 바인딩을 해제하려면 패치에서 agentId: null을 사용하세요.

cron.run 및 cron.remove 매개변수

{ "jobId": "job-123", "mode": "force" }
{ "jobId": "job-123" }

저장소 및 기록

  • 작업 저장소: ~/.openclaw/cron/jobs.json (Gateway 관리 JSON).
  • 실행 기록: ~/.openclaw/cron/runs/<jobId>.jsonl (JSONL, 크기 및 행 수로 자동 정리).
  • sessions.json의 격리 크론 실행 세션은 cron.sessionRetention (기본값 24h; false로 설정하면 비활성화)에 따라 정리됩니다.
  • 저장소 경로 오버라이드: 설정의 cron.store.

재시도 정책

작업이 실패하면 OpenClaw는 오류를 일시적 (재시도 가능) 또는 영구적 (즉시 비활성화)으로 분류합니다.

일시적 오류 (재시도됨)

  • 속도 제한 (429, too many requests, resource exhausted)
  • 제공자 과부하 (예: Anthropic 529 overloaded_error, 과부하 대체 요약)
  • 네트워크 오류 (timeout, ECONNRESET, fetch failed, socket)
  • 서버 오류 (5xx)
  • Cloudflare 관련 오류

영구적 오류 (재시도 없음)

  • 인증 실패 (invalid API key, unauthorized)
  • 설정 또는 유효성 검사 오류
  • 기타 비일시적 오류

기본 동작 (설정 없음)

일회성 작업 (schedule.kind: "at"):

  • 일시적 오류 시: 지수 백오프로 최대 3회 재시도 (30초 → 1분 → 5분).
  • 영구적 오류 시: 즉시 비활성화.
  • 성공 또는 건너뛰기 시: 비활성화 (또는 deleteAfterRun: true이면 삭제).

반복 작업 (cron / every):

  • 오류 발생 시: 다음 예정된 실행 전에 지수 백오프 적용 (30초 → 1분 → 5분 → 15분 → 60분).
  • 작업은 활성 상태를 유지하며, 다음 성공적인 실행 후 백오프가 초기화됩니다.

기본값을 오버라이드하려면 cron.retry를 설정하세요 (설정 참고).

설정

{
  cron: {
    enabled: true, // 기본값 true
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1, // 기본값 1
    // 선택 사항: 일회성 작업의 재시도 정책 오버라이드
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhook: "https://example.invalid/legacy", // notify:true 작업용 더 이상 사용되지 않는 대체
    webhookToken: "replace-with-dedicated-webhook-token", // webhook 모드용 선택적 bearer 토큰
    sessionRetention: "24h", // 기간 문자열 또는 false
    runLog: {
      maxBytes: "2mb", // 기본값 2_000_000 바이트
      keepLines: 2000, // 기본값 2000
    },
  },
}

실행 로그 정리 동작:

  • cron.runLog.maxBytes: 정리 전 최대 실행 로그 파일 크기.
  • cron.runLog.keepLines: 정리 시 최신 N행만 유지.
  • 둘 다 cron/runs/<jobId>.jsonl 파일에 적용됩니다.

Webhook 동작:

  • 권장: 작업별로 delivery.mode: "webhook"과 delivery.to: "https://..."를 설정합니다.
  • Webhook URL은 유효한 http:// 또는 https:// URL이어야 합니다.
  • 전송 시 페이로드는 크론 완료 이벤트 JSON입니다.
  • cron.webhookToken이 설정되어 있으면, 인증 헤더는 Authorization: Bearer <cron.webhookToken>입니다.
  • cron.webhookToken이 설정되어 있지 않으면, Authorization 헤더가 전송되지 않습니다.
  • 더 이상 사용되지 않는 대체: notify: true가 설정된 레거시 작업은 (설정된 경우) 여전히 cron.webhook을 사용합니다.

크론 완전 비활성화:

  • cron.enabled: false (설정)
  • OPENCLAW_SKIP_CRON=1 (환경 변수)

유지보수

크론에는 격리 실행 세션 보존과 실행 로그 정리라는 두 가지 내장 유지보수 경로가 있습니다.

기본값

  • cron.sessionRetention: 24h (false로 설정하면 실행 세션 정리 비활성화)
  • cron.runLog.maxBytes: 2_000_000 바이트
  • cron.runLog.keepLines: 2000

동작 방식

  • 격리 실행은 세션 항목 (...:cron:<jobId>:run:<uuid>)과 트랜스크립트 파일을 생성합니다.
  • 리퍼가 cron.sessionRetention보다 오래된 만료된 실행 세션 항목을 제거합니다.
  • 세션 저장소에서 더 이상 참조되지 않는 제거된 실행 세션의 경우, OpenClaw는 트랜스크립트 파일을 아카이브하고 동일한 보존 기간에 따라 오래된 삭제 아카이브를 정리합니다.
  • 각 실행 추가 후 cron/runs/<jobId>.jsonl 크기가 확인됩니다:
    • 파일 크기가 runLog.maxBytes를 초과하면, 최신 runLog.keepLines행으로 트리밍됩니다.

고볼륨 스케줄러 성능 주의사항

고빈도 크론 설정은 대규모 실행 세션 및 실행 로그 풋프린트를 생성할 수 있습니다. 유지보수가 내장되어 있지만, 느슨한 제한은 불필요한 IO와 정리 작업을 유발할 수 있습니다.

주의할 점:

  • 격리 실행이 많은 상태에서 긴 cron.sessionRetention 기간
  • 큰 runLog.maxBytes와 결합된 높은 cron.runLog.keepLines
  • 동일한 cron/runs/<jobId>.jsonl에 쓰는 다수의 시끄러운 반복 작업

권장 사항:

  • 디버깅/감사 요구에 맞게 cron.sessionRetention을 가능한 한 짧게 유지
  • 적절한 runLog.maxBytes와 runLog.keepLines로 실행 로그를 제한
  • 시끄러운 백그라운드 작업을 불필요한 잡담을 피하는 전달 규칙과 함께 격리 모드로 이동
  • openclaw cron runs로 주기적으로 증가량을 확인하고, 로그가 커지기 전에 보존 기간을 조정

커스텀 예시

실행 세션을 1주일 동안 보관하고 더 큰 실행 로그를 허용:

{
  cron: {
    sessionRetention: "7d",
    runLog: {
      maxBytes: "10mb",
      keepLines: 5000,
    },
  },
}

격리 실행 세션 정리를 비활성화하되 실행 로그 정리는 유지:

{
  cron: {
    sessionRetention: false,
    runLog: {
      maxBytes: "5mb",
      keepLines: 3000,
    },
  },
}

고볼륨 크론 사용에 맞게 튜닝 (예시):

{
  cron: {
    sessionRetention: "12h",
    runLog: {
      maxBytes: "3mb",
      keepLines: 1500,
    },
  },
}

CLI 빠른 시작

일회성 리마인더 (UTC ISO, 성공 후 자동 삭제):

openclaw cron add \
  --name "Send reminder" \
  --at "2026-01-12T18:00:00Z" \
  --session main \
  --system-event "Reminder: submit expense report." \
  --wake now \
  --delete-after-run

일회성 리마인더 (메인 세션, 즉시 깨우기):

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

반복 격리 작업 (WhatsApp으로 announce):

openclaw cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --announce \
  --channel whatsapp \
  --to "+15551234567"

명시적 30초 분산이 있는 반복 크론 작업:

openclaw cron add \
  --name "Minute watcher" \
  --cron "0 * * * * *" \
  --tz "UTC" \
  --stagger 30s \
  --session isolated \
  --message "Run minute watcher checks." \
  --announce

반복 격리 작업 (Telegram 토픽으로 전달):

openclaw cron add \
  --name "Nightly summary (topic)" \
  --cron "0 22 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize today; send to the nightly topic." \
  --announce \
  --channel telegram \
  --to "-1001234567890:topic:123"

모델 및 사고 레벨 오버라이드가 포함된 격리 작업:

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 \
  --channel whatsapp \
  --to "+15551234567"

에이전트 선택 (멀티 에이전트 설정):

# 작업을 "ops" 에이전트에 고정 (해당 에이전트가 없으면 기본 에이전트로 대체)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops

# 기존 작업의 에이전트 변경 또는 해제
openclaw cron edit <jobId> --agent ops
openclaw cron edit <jobId> --clear-agent

수동 실행 (force가 기본값, 예정된 경우에만 실행하려면 --due 사용):

openclaw cron run <jobId>
openclaw cron run <jobId> --due

cron.run은 이제 작업이 완료된 후가 아니라, 수동 실행이 대기열에 추가되면 확인을 반환합니다. 성공적인 대기열 응답은 { ok: true, enqueued: true, runId }와 같습니다. 작업이 이미 실행 중이거나 --due에서 실행할 항목이 없으면 응답은 { ok: true, ran: false, reason }으로 유지됩니다. openclaw cron runs --id <jobId> 또는 cron.runs 게이트웨이 메서드를 사용하여 최종 완료 항목을 확인하세요.

기존 작업 편집 (패치 필드):

openclaw cron edit <jobId> \
  --message "Updated prompt" \
  --model "opus" \
  --thinking low

기존 크론 작업을 정확한 스케줄대로 실행하도록 강제 (분산 없음):

openclaw cron edit <jobId> --exact

실행 기록:

openclaw cron runs --id <jobId> --limit 50

작업을 생성하지 않고 즉시 시스템 이벤트 발생:

openclaw system event --mode now --text "Next heartbeat: check battery."

Gateway API 인터페이스

  • cron.list, cron.status, cron.add, cron.update, cron.remove
  • cron.run (force 또는 due), cron.runs 작업 없이 즉시 시스템 이벤트를 보내려면 openclaw system event를 사용하세요.

트러블슈팅

”아무것도 실행되지 않음”

  • 크론이 활성화되어 있는지 확인: cron.enabled와 OPENCLAW_SKIP_CRON.
  • Gateway가 지속적으로 실행 중인지 확인 (크론은 Gateway 프로세스 내에서 실행됨).
  • cron 스케줄의 경우: 시간대 (--tz)와 호스트 시간대를 확인하세요.

반복 작업이 실패 후 계속 지연됨

  • OpenClaw는 연속 오류 후 반복 작업에 지수 재시도 백오프를 적용합니다: 30초, 1분, 5분, 15분, 그 후 60분 간격.
  • 다음 성공적인 실행 후 백오프가 자동으로 초기화됩니다.
  • 일회성 (at) 작업은 일시적 오류(속도 제한, 과부하, 네트워크, 서버 오류)를 백오프와 함께 최대 3회 재시도하며, 영구적 오류는 즉시 비활성화합니다. 재시도 정책을 참고하세요.

Telegram이 잘못된 곳으로 전달됨

  • 포럼 토픽의 경우, 명확하고 모호하지 않도록 -100…:topic:<id>를 사용하세요.
  • 로그나 저장된 “마지막 경로” 대상에서 telegram:... 접두사를 보더라도 정상입니다. 크론 전달은 이를 허용하고 토픽 ID를 올바르게 파싱합니다.

서브에이전트 announce 전달 재시도

  • 서브에이전트 실행이 완료되면, 게이트웨이는 결과를 요청자 세션에 announce합니다.
  • announce 흐름이 false를 반환하면 (예: 요청자 세션이 사용 중), 게이트웨이는 announceRetryCount를 통해 추적하면서 최대 3회 재시도합니다.
  • endedAt 이후 5분이 지난 announce는 오래된 항목이 무한 루프되는 것을 방지하기 위해 강제 만료됩니다.
  • 로그에서 반복적인 announce 전달이 보이면, 높은 announceRetryCount 값을 가진 서브에이전트 레지스트리 항목을 확인하세요.
arrow_back
이전
Hooks
다음
Cron Vs Heartbeat
arrow_forward