openclaw cron

Gateway 스케줄러의 Cron 작업을 관리합니다.

작업 빠르게 생성하기

openclaw cron create는 openclaw cron add의 별칭입니다. 새 작업에서는 일정을 먼저, 프롬프트를 두 번째로 지정하세요.

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --agent ops

채팅 대상에 전달하는 대신 완료된 페이로드를 POST해야 하는 작업에는 --webhook <url>을 사용하세요.

openclaw cron create "0 18 * * 1-5" \  "Summarize today's deploys as JSON." \  --name "Deploy digest" \  --webhook "https://example.invalid/openclaw/cron"

격리된 에이전트/모델 실행을 시작하지 않고 OpenClaw Cron 내부에서 실행되는 결정론적 셸 방식 작업에는 --command를 사용하세요.

openclaw cron create "*/15 * * * *" \  --name "Queue depth probe" \  --command "scripts/check-queue.sh" \  --command-cwd "/srv/app" \  --announce \  --channel telegram \  --to "-1001234567890"

--command <shell>은 argv: ["sh", "-lc", <shell>]을 저장합니다. 정확한 argv 실행에는 --command-argv '["node","scripts/report.mjs"]'를 사용하세요. 명령 작업은 stdout/stderr를 캡처하고 일반 Cron 기록을 남기며, 격리 작업과 동일한 announce, webhook, none 전달 모드를 통해 출력을 라우팅합니다. NO_REPLY만 출력하는 명령은 억제됩니다.

세션

--session은 main, isolated, current 또는 session:<id>를 허용합니다.

전달

openclaw cron list와 openclaw cron show <job-id>는 확인된 전달 경로를 미리 보여 줍니다. channel: "last"의 경우 경로가 기본 세션 또는 현재 세션에서 확인되었는지, 아니면 안전하게 실패할지를 미리 보기에 표시합니다.

공급자 접두사가 붙은 대상은 확인되지 않은 알림 채널을 명확히 구분할 수 있습니다. 예를 들어 to: "telegram:123"은 delivery.channel이 생략되었거나 last일 때 Telegram을 선택합니다. 로드된 Plugin에서 공지한 접두사만 공급자 선택자로 사용됩니다. delivery.channel을 명시한 경우 접두사는 해당 채널과 일치해야 합니다. channel: "whatsapp"과 to: "telegram:123"의 조합은 거부됩니다. imessage: 및 sms: 같은 서비스 접두사는 계속 채널 소유의 대상 구문으로 유지됩니다.

전달 소유권

격리된 Cron 채팅 전달은 에이전트와 러너가 분담합니다.

• 채팅 경로를 사용할 수 있으면 에이전트가 message 도구를 사용하여 직접 전송할 수 있습니다.
• 에이전트가 확인된 대상에 직접 전송하지 않은 경우에만 announce가 최종 응답을 대체 전달합니다.
• webhook은 완료된 페이로드를 URL로 게시합니다.
• none은 러너의 대체 전달을 비활성화합니다.

Webhook 전달을 설정하려면 cron add|create --webhook <url> 또는 cron edit <job-id> --webhook <url>을 사용하세요. --webhook을 --announce, --no-deliver, --channel, --to, --thread-id, --account 같은 채팅 전달 플래그와 함께 사용하지 마세요.

cron edit <job-id>에서는 --clear-channel, --clear-to, --clear-thread-id, --clear-account를 사용하여 개별 전달 라우팅 필드를 해제할 수 있습니다. 각 옵션은 대응하는 설정 플래그와 함께 사용하면 거부됩니다. 러너의 대체 전달만 비활성화하는 --no-deliver와 달리, 이 옵션들은 저장된 필드를 제거하여 작업이 해당 경로 부분을 다시 기본값에서 확인하도록 합니다.

--announce는 최종 응답을 위한 러너의 대체 전달입니다. --no-deliver는 이 대체 전달을 비활성화하지만 채팅 경로를 사용할 수 있을 때 에이전트의 message 도구를 제거하지는 않습니다.

활성 채팅에서 생성된 알림은 대체 알림 전달을 위해 현재 채팅 전달 대상을 보존합니다. 내부 세션 키는 소문자일 수 있으므로 Matrix 방 ID처럼 대소문자를 구분하는 공급자 ID의 신뢰 가능한 기준으로 사용하지 마세요.

실패 전달

실패 알림은 다음 순서로 확인됩니다.

1. 작업의 delivery.failureDestination.
2. 전역 cron.failureDestination.
3. 작업의 기본 알림 대상(위 두 항목 모두 구체적인 대상으로 확인되지 않는 경우).

격리된 Cron 실행은 응답 페이로드가 생성되지 않더라도 실행 수준의 에이전트 실패를 작업 오류로 처리하므로, 모델/공급자 실패도 오류 카운터를 증가시키고 실패 알림을 트리거합니다.

명령 Cron 작업은 격리된 에이전트 턴을 시작하지 않습니다. 종료 코드가 0이면 ok를 기록하고, 0이 아닌 종료 코드, 신호, 시간 초과 또는 출력 없음 시간 초과는 error를 기록하며 동일한 실패 알림 경로를 트리거할 수 있습니다.

격리 실행이 첫 번째 모델 요청 전에 시간 초과되면 openclaw cron show와 openclaw cron runs에 setup timed out before runner start 같은 단계별 오류나 마지막으로 확인된 시작 단계를 명시하는 중단 메시지(예: context-engine)가 포함됩니다. CLI 기반 공급자의 경우 외부 CLI 턴이 시작될 때까지 모델 실행 전 감시 장치가 활성 상태로 유지되므로 세션 조회, 훅, 인증, 프롬프트, CLI 설정 중단이 모델 실행 전 Cron 실패로 보고됩니다.

예약

일회성 작업

--at <datetime>은 일회성 실행을 예약합니다. 오프셋이 없는 날짜 및 시간은 UTC로 처리됩니다. 단, --tz <iana>도 함께 전달하면 지정된 시간대의 현지 시각으로 해석됩니다.

반복 작업

반복 작업은 연속 오류 후 30초, 1분, 5분, 15분, 60분의 지수형 재시도 백오프를 사용합니다. 다음 실행이 성공하면 일정이 정상으로 돌아갑니다.

건너뛴 실행은 실행 오류와 별도로 추적됩니다. 재시도 백오프에는 영향을 주지 않지만, openclaw cron edit <job-id> --failure-alert-include-skipped를 사용하면 반복되는 실행 건너뜀 알림도 실패 경고에 포함할 수 있습니다.

로컬로 구성된 모델 공급자(local loopback, 사설 네트워크 또는 .local의 기본 URL)를 대상으로 하는 격리 작업의 경우, Cron은 에이전트 턴을 시작하기 전에 가벼운 공급자 사전 점검을 실행합니다. api: "ollama" 공급자는 /api/tags에서 점검하며, 그 밖의 로컬 OpenAI 호환 공급자(api: "openai-completions", 예: vLLM, SGLang, LM Studio)는 /models에서 점검합니다. 엔드포인트에 연결할 수 없으면 실행은 skipped로 기록되고 이후 일정에서 다시 시도됩니다. 동일한 로컬 서버를 사용하는 여러 작업이 반복 점검 요청을 집중시키지 않도록 연결 가능 여부 결과는 엔드포인트별로 5분 동안 캐시됩니다.

Cron 작업, 보류 중인 런타임 상태 및 실행 기록은 공유 SQLite 상태 데이터베이스에 저장됩니다. 기존 jobs.json, <name>-state.json, runs/*.jsonl 파일은 한 번 가져온 후 .migrated 접미사를 붙여 이름이 변경됩니다. 가져온 후에는 JSON 파일을 편집하지 말고 openclaw cron add|edit|remove로 일정을 편집하세요.

수동 실행

openclaw cron run <job-id>은 기본적으로 강제 실행하며 수동 실행이 대기열에 추가되는 즉시 반환합니다. 성공 응답에는 { ok: true, enqueued: true, runId }가 포함됩니다. 반환된 runId를 사용하여 나중에 결과를 확인하세요.

openclaw cron run <job-id>openclaw cron runs --id <job-id> --run-id <run-id>

스크립트가 해당 대기 실행이 종료 상태를 기록할 때까지 대기해야 한다면 --wait를 추가하세요.

openclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s

--wait를 사용해도 CLI는 먼저 cron.run을 호출한 다음 반환된 runId에 대해 cron.runs를 폴링합니다. 실행이 ok 상태로 완료된 경우에만 명령이 0으로 종료됩니다. 실행이 error 또는 skipped로 완료되거나, Gateway 응답에 runId가 없거나, --wait-timeout이 만료되면 0이 아닌 값으로 종료됩니다. 기본 시간 초과는 10m이며 기본 폴링 간격은 2s입니다. --poll-interval은 0보다 커야 합니다.

모델

cron add|edit --model <ref>는 작업에 허용된 모델을 선택합니다. cron add|edit --fallbacks <list>는 작업별 대체 모델을 설정합니다. 예: --fallbacks openrouter/gpt-4.1-mini,openai/gpt-5. 대체 모델 없이 엄격하게 실행하려면 --fallbacks ""를 전달하세요. cron edit <job-id> --clear-fallbacks는 작업별 대체 모델 재정의를 제거합니다. cron edit <job-id> --clear-model은 작업별 모델 재정의를 제거하여 작업이 일반적인 Cron 모델 선택 우선순위(저장된 Cron 세션 재정의가 있으면 해당 값, 없으면 에이전트/기본 모델)를 따르도록 하며 --model과 함께 사용할 수 없습니다. cron add|edit --thinking <level>은 작업별 사고 수준 재정의를 설정합니다. cron edit <job-id> --clear-thinking은 이를 제거하여 작업이 일반적인 Cron 사고 수준 우선순위를 따르도록 하며 --thinking과 함께 사용할 수 없습니다.

Cron의 --model은 작업 기본 모델이며 채팅 세션의 /model 재정의가 아닙니다. 이는 다음을 의미합니다.

• 선택한 작업 모델이 실패해도 구성된 대체 모델이 계속 적용됩니다.
• 작업별 페이로드에 fallbacks가 있으면 구성된 대체 모델 목록을 대체합니다.
• 빈 작업별 대체 모델 목록(--fallbacks "" 또는 작업 페이로드/API의 fallbacks: [])은 Cron 실행을 엄격 모드로 만듭니다.
• 작업에 --model이 있지만 대체 모델 목록이 구성되지 않은 경우, OpenClaw는 에이전트 기본 모델이 숨겨진 재시도 대상으로 추가되지 않도록 명시적인 빈 대체 모델 재정의를 전달합니다.
• 로컬 공급자 사전 점검은 Cron 실행을 skipped로 표시하기 전에 구성된 대체 모델을 순회합니다.

openclaw doctor는 payload.model이 이미 설정된 작업을 보고하며, 여기에는 공급자 네임스페이스 개수와 agents.defaults.model 불일치가 포함됩니다. 실시간 채팅과 예약 작업에서 인증, 공급자 또는 요금 청구 동작이 다르게 보일 때 이 검사를 사용하세요.

격리된 Cron 모델 우선순위

격리된 Cron은 다음 순서로 활성 모델을 결정합니다.

1. Gmail 훅 재정의.
2. 작업별 --model.
3. 저장된 Cron 세션 모델 재정의(사용자가 선택한 경우).
4. 에이전트 또는 기본 모델 선택.

빠른 모드

격리된 Cron의 빠른 모드는 확인된 실시간 모델 선택을 따릅니다. 모델 구성의 params.fastMode가 기본적으로 적용되지만 저장된 세션의 fastMode 재정의가 구성보다 우선합니다. 확인된 모드가 auto이면 임계값은 선택된 모델의 params.fastAutoOnSeconds 값을 사용하며 기본값은 60초입니다.

실시간 모델 전환 재시도

격리 실행에서 LiveSessionModelSwitchError가 발생하면 Cron은 재시도하기 전에 전환된 공급자와 모델을 활성 실행에 영구 저장하며, 전환된 인증 프로필 재정의가 있으면 이 값도 저장합니다. 외부 재시도 루프는 최초 시도 후 모델 전환 재시도를 두 번으로 제한하며, 이후에는 무한 반복하는 대신 중단합니다.

실행 출력 및 거부

오래된 확인 응답 억제

격리된 Cron 턴은 오래된 확인 전용 응답을 억제합니다. 첫 번째 결과가 단순한 중간 상태 업데이트이고 이후 최종 응답을 담당하는 하위 에이전트 실행이 없다면, Cron은 전달하기 전에 실제 결과를 얻기 위해 한 번 다시 프롬프트를 보냅니다.

무응답 토큰 억제

격리된 Cron 실행이 무응답 토큰(NO_REPLY 또는 no_reply)만 반환하면 Cron은 직접 외부 전달과 대체 대기열 요약 경로를 모두 억제하므로 채팅에 아무것도 게시되지 않습니다.

구조화된 거부

격리된 Cron 실행은 내장 실행에서 제공하는 구조화된 실행 거부 메타데이터(SYSTEM_RUN_DENIED 또는 INVALID_REQUEST 코드가 지정된 치명적인 실행 도구 오류)를 신뢰할 수 있는 거부 신호로 사용합니다. 또한 이러한 코드 중 하나를 포함하는 중첩된 구조화 오류를 감싸는 Node 호스트의 UNAVAILABLE 래퍼도 인식합니다.

내장 실행에서 구조화된 거부 메타데이터도 제공하지 않는 한 Cron은 최종 출력의 일반 문구나 승인 거부처럼 보이는 표현을 거부로 분류하지 않으므로, 일반적인 어시스턴트 텍스트는 차단된 명령으로 취급되지 않습니다.

cron list와 실행 기록은 차단된 명령을 ok로 보고하는 대신 거부 이유를 표시합니다.

보존

보존 및 정리는 구성에서 제어합니다.

• cron.sessionRetention(기본값 24h, 비활성화하려면 false)은 완료된 격리 실행 세션을 정리합니다.
• cron.runLog.keepLines(기본값 2000)는 작업별로 보존된 SQLite 실행 기록 행을 정리합니다. cron.runLog.maxBytes(기본값 2000000)는 이전 파일 기반 실행 로그와의 호환성을 위해 계속 허용되며, SQLite 정리는 행 수를 기준으로 합니다.

이전 작업 마이그레이션

일반적인 편집

메시지를 변경하지 않고 전달 설정을 업데이트합니다.

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

격리 작업의 전달을 비활성화합니다.

openclaw cron edit <job-id> --no-deliver

격리 작업에 경량 부트스트랩 컨텍스트를 활성화합니다.

openclaw cron edit <job-id> --light-context

특정 채널에 알림을 보냅니다.

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

Telegram 포럼 주제에 알림을 보냅니다.

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

경량 부트스트랩 컨텍스트가 적용된 격리 작업을 생성합니다.

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Lightweight morning brief" \  --session isolated \  --light-context \  --no-deliver

--light-context는 격리된 에이전트 턴 작업에만 적용됩니다. Cron 실행에서 경량 모드는 전체 워크스페이스 부트스트랩 집합을 주입하는 대신 부트스트랩 컨텍스트를 비워 둡니다.

정확한 argv, cwd, env, stdin 및 출력 제한으로 명령 작업을 생성합니다.

openclaw cron create "*/30 * * * *" \  --name "Position export" \  --command-argv '["node","scripts/export-position.mjs"]' \  --command-cwd "/srv/app" \  --command-env "NODE_ENV=production" \  --command-input '{"mode":"summary"}' \  --timeout-seconds 120 \  --no-output-timeout-seconds 30 \  --output-max-bytes 65536 \  --webhook "https://example.invalid/openclaw/cron"

일반적인 관리 명령

수동 실행 및 검사:

openclaw cron listopenclaw cron list --agent opsopenclaw cron get <job-id>openclaw cron show <job-id>openclaw cron run <job-id>openclaw cron run <job-id> --dueopenclaw cron run <job-id> --wait --wait-timeout 10mopenclaw cron run <job-id> --wait --wait-timeout 10m --poll-interval 2sopenclaw cron runs --id <job-id> --limit 50openclaw cron runs --id <job-id> --run-id <run-id>

openclaw cron list는 기본적으로 조건과 일치하는 모든 작업을 표시합니다. 유효한 정규화 에이전트 ID가 일치하는 작업만 표시하려면 --agent <id>를 전달하세요. 저장된 에이전트 ID가 없는 작업은 구성된 기본 에이전트에 속하는 것으로 간주합니다.

openclaw cron get <job-id>은 저장된 작업 JSON을 직접 반환합니다. 전달 경로 미리보기가 포함된 사람이 읽기 쉬운 보기가 필요하면 cron show <job-id>를 사용하세요.

cron list --json과 cron show <job-id> --json은 enabled, state.runningAtMs, state.lastRunStatus에서 계산된 최상위 status 필드를 각 작업에 포함합니다. 값은 disabled, running, ok, error, skipped 또는 idle입니다. 외부 도구에서 작업 상태를 다시 계산하지 않고 읽을 수 있도록 JSON 상태는 표준 형식 그대로 장식 없이 유지됩니다. 사람이 읽는 출력에서는 반복되는 error 상태에 실패 횟수를 표시할 수 있습니다.

cron runs 항목에는 의도된 Cron 대상, 확인된 대상, 메시지 도구 전송, 대체 경로 사용 여부 및 전달 상태가 포함된 전달 진단 정보가 들어 있습니다.

에이전트 및 세션 대상 변경:

openclaw cron edit <job-id> --agent opsopenclaw cron edit <job-id> --clear-agentopenclaw cron edit <job-id> --session currentopenclaw cron edit <job-id> --session "session:daily-brief"

openclaw cron add는 에이전트 턴 작업에서 --agent가 생략되면 경고하고 기본 에이전트(main)로 대체합니다. 특정 에이전트를 고정하려면 생성 시 --agent <id>를 전달하세요.

전달 조정:

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"openclaw cron edit <job-id> --webhook "https://example.invalid/openclaw/cron"openclaw cron edit <job-id> --best-effort-deliveropenclaw cron edit <job-id> --no-best-effort-deliveropenclaw cron edit <job-id> --no-deliver

관련 문서

• CLI 참조
• 예약 작업