Zaplanowane zadania

Cron to wbudowany harmonogram Gateway. Utrwala zadania, wybudza agenta we właściwym czasie i może dostarczać wynik z powrotem do kanału czatu lub punktu końcowego Webhook.

Szybki start

openclaw cron create "2026-02-01T16:00:00Z" \  --name "Reminder" \  --session main \  --system-event "Reminder: check the cron docs draft" \  --wake now \  --delete-after-run

openclaw cron listopenclaw cron get <job-id>openclaw cron show <job-id>

openclaw cron runs --id <job-id>

Jak działa cron

• Cron działa wewnątrz procesu Gateway (nie wewnątrz modelu).
• Definicje zadań, stan wykonania i historia uruchomień są utrwalane we współdzielonej bazie stanu SQLite OpenClaw, więc ponowne uruchomienia nie powodują utraty harmonogramów.
• Po uaktualnieniu uruchom openclaw doctor --fix, aby zaimportować starsze pliki ~/.openclaw/cron/jobs.json, jobs-state.json oraz runs/*.jsonl do SQLite i zmienić ich nazwy, dodając sufiks .migrated. Nieprawidłowo sformatowane wiersze zadań są pomijane w czasie wykonywania i kopiowane do jobs-quarantine.json w celu późniejszej naprawy lub przeglądu.
• cron.store nadal określa logiczny klucz magazynu cron i ścieżkę importu doctor. Po imporcie edycja tego pliku JSON nie zmienia już aktywnych zadań cron; zamiast tego użyj openclaw cron add|edit|remove albo metod RPC Cron w Gateway.
• Wszystkie wykonania cron tworzą rekordy zadania w tle.
• Podczas uruchamiania Gateway zaległe izolowane zadania tur agenta są ponownie planowane poza oknem łączenia kanału, zamiast odtwarzać się natychmiast, dzięki czemu uruchamianie Discord/Telegram i konfiguracja poleceń natywnych pozostają responsywne po restartach.
• Zadania jednorazowe (--at) domyślnie automatycznie usuwają się po powodzeniu.
• Izolowane uruchomienia Cron w trybie best-effort zamykają śledzone karty/procesy przeglądarki dla swojej sesji cron:<jobId> po zakończeniu uruchomienia, więc odłączona automatyzacja przeglądarki nie zostawia osieroconych procesów.
• Izolowane uruchomienia Cron, które otrzymują wąskie uprawnienie samoczyszczenia cron, nadal mogą odczytywać status harmonogramu, przefiltrowaną do siebie listę bieżącego zadania oraz historię uruchomień tego zadania, więc kontrole statusu/Heartbeat mogą sprawdzać własny harmonogram bez uzyskiwania szerszego dostępu do modyfikacji cron.
• Izolowane uruchomienia Cron zabezpieczają się także przed nieaktualnymi odpowiedziami potwierdzającymi. Jeśli pierwszy wynik jest tylko tymczasową aktualizacją statusu (on it, pulling everything together i podobne wskazówki), a żadne potomne uruchomienie subagenta nie odpowiada już za ostateczną odpowiedź, OpenClaw ponawia monit raz, prosząc o właściwy wynik przed dostarczeniem.
• Izolowane uruchomienia Cron używają ustrukturyzowanych metadanych odmowy wykonania z osadzonego uruchomienia, w tym opakowań node-host UNAVAILABLE, których zagnieżdżony komunikat błędu zaczyna się od SYSTEM_RUN_DENIED albo INVALID_REQUEST, dzięki czemu zablokowane polecenie nie jest raportowane jako udane uruchomienie, a zwykła proza asystenta nie jest traktowana jako odmowa.
• Izolowane uruchomienia Cron traktują także awarie agenta na poziomie uruchomienia jako błędy zadania, nawet gdy nie powstaje żaden payload odpowiedzi, więc awarie modelu/dostawcy zwiększają liczniki błędów i wyzwalają powiadomienia o awarii zamiast oznaczać zadanie jako udane.
• Gdy izolowane zadanie tury agenta osiąga timeoutSeconds, Cron przerywa bazowe uruchomienie agenta i daje mu krótkie okno na sprzątanie. Jeśli uruchomienie nie zostanie opróżnione, sprzątanie należące do Gateway wymusza wyczyszczenie własności sesji tego uruchomienia, zanim Cron zapisze limit czasu, więc zakolejkowana praca czatu nie pozostaje za nieaktualną sesją przetwarzania.
• Jeśli izolowana tura agenta zatrzyma się przed startem runnera albo przed pierwszym wywołaniem modelu, Cron zapisuje limit czasu specyficzny dla fazy, taki jak setup timed out before runner start albo stalled before first model call (last phase: context-engine). Te watchdogi obejmują osadzonych dostawców i dostawców opartych na CLI, zanim ich zewnętrzny proces CLI faktycznie się uruchomi, oraz są limitowane niezależnie od długich wartości timeoutSeconds, dzięki czemu awarie zimnego startu/uwierzytelniania/kontekstu ujawniają się szybko, zamiast czekać na pełny budżet zadania.
• Jeśli używasz systemowego cron albo innego zewnętrznego harmonogramu do uruchamiania openclaw agent, opakuj go eskalacją hard-kill, mimo że CLI obsługuje SIGTERM/SIGINT. Uruchomienia obsługiwane przez Gateway proszą Gateway o przerwanie zaakceptowanych uruchomień; lokalne i osadzone uruchomienia fallback otrzymują ten sam sygnał przerwania. Dla GNU timeout preferuj timeout -k 60 600 openclaw agent ... zamiast zwykłego timeout 600 ...; wartość -k jest zabezpieczeniem nadzorcy, jeśli proces nie może się opróżnić. W jednostkach systemd zachowaj ten sam kształt, używając sygnału zatrzymania SIGTERM oraz okna łaski, takiego jak TimeoutStopSec, przed ewentualnym końcowym zabiciem. Jeśli ponowienie użyje tego samego --run-id, gdy oryginalne uruchomienie Gateway jest nadal aktywne, duplikat zostanie zgłoszony jako będący w toku zamiast uruchamiać drugie wykonanie.

Typy harmonogramów

Znaczniki czasu bez strefy czasowej są traktowane jako UTC. Dodaj --tz America/New_York dla harmonogramowania według lokalnego czasu zegarowego.

Powtarzające się wyrażenia na początek godziny są automatycznie rozpraszane o maksymalnie 5 minut, aby ograniczyć skoki obciążenia. Użyj --exact, aby wymusić precyzyjny czas, albo --stagger 30s, aby ustawić jawne okno.

Dzień miesiąca i dzień tygodnia używają logiki OR

Wyrażenia Cron są parsowane przez croner. Gdy pola dnia miesiąca i dnia tygodnia nie są symbolami wieloznacznymi, croner dopasowuje, gdy pasuje którekolwiek z pól, a nie oba. To standardowe zachowanie cron Vixie.

# 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

To uruchamia się około 5-6 razy miesięcznie zamiast 0-1 razy miesięcznie. OpenClaw używa tutaj domyślnego zachowania OR Cronera. Aby wymagać obu warunków, użyj modyfikatora dnia tygodnia + Cronera (0 9 15 * +1) albo harmonogramuj według jednego pola i zabezpiecz drugie w monicie lub poleceniu zadania.

Style wykonywania

Payloady poleceń

Używaj payloadów poleceń dla deterministycznych skryptów, które powinny działać w harmonogramie Gateway bez uruchamiania izolowanej tury agenta opartej na modelu. Zadania poleceń wykonują się na hoście Gateway, przechwytują stdout/stderr, zapisują uruchomienie w historii cron i ponownie używają tych samych trybów dostarczania announce, webhook i none co zadania izolowane.

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

--command <shell> przechowuje argv: ["sh", "-lc", <shell>]. Użyj --command-argv '["node","scripts/report.mjs"]', gdy chcesz dokładnego wykonania argv bez parsowania powłoki. Opcjonalne pola --command-env KEY=VALUE, --command-input, --timeout-seconds, --no-output-timeout-seconds i --output-max-bytes kontrolują środowisko procesu, stdin i limity wyjścia.

Jeśli stdout nie jest pusty, ten tekst jest dostarczonym wynikiem. Jeśli stdout jest pusty, a stderr nie jest pusty, dostarczany jest stderr. Jeśli oba strumienie są obecne, cron dostarcza mały blok stdout: / stderr:. Zerowy kod wyjścia zapisuje uruchomienie jako ok; niezerowe wyjście, sygnał, timeout lub timeout braku wyjścia zapisuje error i może wyzwolić alerty o niepowodzeniu. Polecenie, które wypisuje tylko NO_REPLY, używa standardowego tłumienia cichego tokenu cron i nie publikuje niczego z powrotem na czacie.

Opcje payloadu dla izolowanych zadań

--model używa wybranego dozwolonego modelu jako podstawowego modelu tego zadania. To nie to samo co nadpisanie /model w sesji czatu: skonfigurowane łańcuchy fallback nadal mają zastosowanie, gdy podstawowy model zadania zawiedzie. Jeśli żądany model nie jest dozwolony lub nie można go rozwiązać, cron kończy uruchomienie niepowodzeniem z jawnym błędem walidacji zamiast po cichu wracać do wyboru modelu agenta/domyślnego dla zadania.

Zadania Cron mogą też przenosić fallbacks na poziomie payloadu. Gdy taka lista jest obecna, zastępuje skonfigurowany łańcuch fallbacków dla zadania. Użyj fallbacks: [] w payloadzie/API zadania, gdy chcesz ścisłego uruchomienia cron, które próbuje tylko wybranego modelu. Jeśli zadanie ma --model, ale nie ma fallbacków ani w payloadzie, ani w konfiguracji, OpenClaw przekazuje jawne puste nadpisanie fallback, aby podstawowy model agenta nie został dołączony jako ukryty dodatkowy cel ponowienia.

Kontrole preflight lokalnych providerów przechodzą po skonfigurowanych fallbackach przed oznaczeniem uruchomienia cron jako skipped; fallbacks: [] utrzymuje tę ścieżkę preflight jako ścisłą.

Kolejność wyboru modelu dla izolowanych zadań to:

1. Nadpisanie modelu hooka Gmail (gdy uruchomienie pochodziło z Gmail i to nadpisanie jest dozwolone)
2. model w payloadzie zadania
3. Wybrane przez użytkownika zapisane nadpisanie modelu sesji cron
4. Wybór modelu agenta/domyślnego

Tryb szybki również podąża za rozwiązaną aktywną selekcją. Jeśli konfiguracja wybranego modelu ma params.fastMode, izolowany cron domyślnie go używa. Zapisane nadpisanie sesji fastMode nadal wygrywa z konfiguracją w obu kierunkach. Tryb automatyczny używa progu params.fastAutoOnSeconds wybranego modelu, gdy jest obecny, domyślnie 60 sekund.

Jeśli izolowane uruchomienie trafi na aktywne przekazanie przełączenia modelu, cron ponawia z przełączonym providerem/modelem i utrwala tę aktywną selekcję dla aktywnego uruchomienia przed ponowieniem. Gdy przełączenie przenosi też nowy profil uwierzytelniania, cron utrwala również to nadpisanie profilu uwierzytelniania dla aktywnego uruchomienia. Ponowienia są ograniczone: po początkowej próbie plus 2 ponowieniach przełączenia cron przerywa zamiast zapętlać się w nieskończoność.

Zanim izolowane uruchomienie cron wejdzie do runnera agenta, OpenClaw sprawdza osiągalne lokalne endpointy providerów dla skonfigurowanych providerów api: "ollama" i api: "openai-completions", których baseUrl jest local loopback, w sieci prywatnej lub .local. Jeśli ten endpoint jest niedostępny, uruchomienie jest zapisywane jako skipped z czytelnym błędem providera/modelu zamiast rozpoczynać wywołanie modelu. Wynik endpointu jest buforowany przez 5 minut, więc wiele oczekujących zadań używających tego samego niedziałającego lokalnego serwera Ollama, vLLM, SGLang lub LM Studio współdzieli jedną małą próbę zamiast tworzyć burzę żądań. Uruchomienia pominięte przez preflight providera nie zwiększają backoffu błędów wykonania; włącz failureAlert.includeSkipped, gdy chcesz powtarzanych powiadomień o pominięciach.

Dostarczanie i wyjście

Użyj --announce --channel telegram --to "-1001234567890" do dostarczania na kanał. Dla tematów forum Telegram użyj -1001234567890:topic:123; OpenClaw akceptuje też należący do Telegram skrót -1001234567890:123. Bezpośredni wywołujący RPC/konfiguracji mogą przekazać delivery.threadId jako string lub liczbę. Cele Slack/Discord/Mattermost powinny używać jawnych prefiksów (channel:<id>, user:<id>). Identyfikatory pokojów Matrix rozróżniają wielkość liter; użyj dokładnego identyfikatora pokoju albo formy room:!room:server z Matrix.

Gdy dostarczanie announce używa channel: "last" lub pomija channel, cel z prefiksem providera, taki jak telegram:123, może wybrać kanał, zanim cron wróci do historii sesji albo pojedynczego skonfigurowanego kanału. Selektorami providerów są tylko prefiksy ogłaszane przez załadowany Plugin. Jeśli delivery.channel jest jawne, prefiks celu musi wskazywać tego samego providera; na przykład channel: "whatsapp" z to: "telegram:123" jest odrzucane zamiast pozwalać WhatsApp interpretować identyfikator Telegram jako numer telefonu. Prefiksy rodzaju celu i usługi, takie jak channel:<id>, user:<id>, imessage:<handle> i sms:<number>, pozostają składnią celu należącą do kanału, a nie selektorami providerów.

Dla izolowanych zadań dostarczanie czatu jest współdzielone. Jeśli trasa czatu jest dostępna, agent może użyć narzędzia message, nawet gdy zadanie używa --no-deliver. Jeśli agent wysyła do skonfigurowanego/bieżącego celu, OpenClaw pomija fallback announce. W przeciwnym razie announce, webhook i none kontrolują tylko to, co runner robi z końcową odpowiedzią po turze agenta.

Gdy agent tworzy izolowane przypomnienie z aktywnego czatu, OpenClaw zapisuje zachowany aktywny cel dostarczania dla trasy fallback announce. Wewnętrzne klucze sesji mogą być małymi literami; cele dostarczania providerów nie są rekonstruowane z tych kluczy, gdy dostępny jest bieżący kontekst czatu.

Niejawne dostarczanie announce używa skonfigurowanych list dozwolonych kanałów do walidacji i przekierowywania przestarzałych celów. Zatwierdzenia ze store parowania DM nie są odbiorcami automatyzacji fallback; ustaw delivery.to albo skonfiguruj wpis allowFrom kanału, gdy zaplanowane zadanie ma proaktywnie wysyłać do DM.

Język wyjścia

Zadania Cron nie wywnioskują języka odpowiedzi z kanału, ustawień regionalnych ani poprzednich wiadomości. Umieść regułę języka w zaplanowanej wiadomości lub szablonie:

openclaw cron edit <jobId> \  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."

W przypadku plików szablonów trzymaj instrukcję językową w renderowanym prompcie i sprawdź, czy placeholdery takie jak {{language}} są wypełnione przed uruchomieniem zadania. Jeśli wyjście miesza języki, określ regułę jawnie, na przykład: "Use Chinese for narrative text and keep technical terms in English."

Powiadomienia o niepowodzeniach używają osobnej ścieżki docelowej:

• cron.failureDestination ustawia globalną wartość domyślną dla powiadomień o niepowodzeniach.
• job.delivery.failureDestination nadpisuje ją dla zadania.
• Jeśli żadna z nich nie jest ustawiona, a zadanie już dostarcza przez announce, powiadomienia o niepowodzeniach wracają teraz do tego podstawowego celu announce.
• delivery.failureDestination jest obsługiwane tylko w zadaniach sessionTarget="isolated", chyba że podstawowy tryb dostarczania to webhook.
• failureAlert.includeSkipped: true włącza dla zadania lub globalnej polityki alertów cron powtarzane alerty o pominiętych uruchomieniach. Pominięte uruchomienia mają osobny licznik kolejnych pominięć, więc nie wpływają na backoff błędów wykonania.

Przykłady CLI

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

openclaw cron create "0 7 * * *" \  "Summarize overnight updates." \  --name "Morning brief" \  --tz "America/Los_Angeles" \  --session isolated \  --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

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

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

Webhooks

Gateway może udostępniać endpointy HTTP Webhook dla zewnętrznych wyzwalaczy. Włącz w konfiguracji:

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

Uwierzytelnianie

Każde żądanie musi zawierać token hooka w nagłówku:

• Authorization: Bearer <token> (zalecane)
• x-openclaw-token: <token>

Tokeny w query string są odrzucane.

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

Integracja Gmail PubSub

Podłącz wyzwalacze skrzynki odbiorczej Gmail do OpenClaw przez Google PubSub.

Konfiguracja kreatorem (zalecane)

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

To zapisuje konfigurację hooks.gmail, włącza preset Gmail i używa Tailscale Funnel dla punktu końcowego push.

Automatyczne uruchamianie Gateway

Gdy hooks.enabled=true i ustawiono hooks.gmail.account, Gateway uruchamia gog gmail watch serve przy starcie i automatycznie odnawia obserwację. Ustaw OPENCLAW_SKIP_GMAIL_WATCHER=1, aby z tego zrezygnować.

Ręczna jednorazowa konfiguracja

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

gcloud pubsub topics create gog-gmail-watchgcloud pubsub topics add-iam-policy-binding gog-gmail-watch \  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \  --role=roles/pubsub.publisher

gog gmail watch start \  --account openclaw@gmail.com \  --label INBOX \  --topic projects/<project-id>/topics/gog-gmail-watch

Nadpisanie modelu Gmail

{  hooks: {    gmail: {      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

Zarządzanie zadaniami

# List all jobsopenclaw cron list # Get one stored job as JSONopenclaw cron get <jobId> # Show one job, including resolved delivery routeopenclaw cron show <jobId> # Edit a jobopenclaw cron edit <jobId> --message "Updated prompt" --model "opus" # Force run a job nowopenclaw cron run <jobId> # Force run a job now and wait for its terminal statusopenclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s # Run only if dueopenclaw cron run <jobId> --due # View run historyopenclaw cron runs --id <jobId> --limit 50 # View one exact runopenclaw cron runs --id <jobId> --run-id <runId> # Delete a jobopenclaw cron remove <jobId> # Agent selection (multi-agent setups)openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent opsopenclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId> zwraca wynik po zakolejkowaniu ręcznego uruchomienia. Użyj --wait dla hooków zamykania, skryptów konserwacyjnych lub innej automatyzacji, która musi blokować działanie do zakończenia zakolejkowanego uruchomienia. Tryb oczekiwania odpytuje dokładnie zwrócone runId; kończy się kodem 0 dla statusu ok i kodem niezerowym dla error, skipped albo przekroczenia limitu oczekiwania.

Narzędzie agenta cron zwraca zwarte podsumowania zadań (id, name, enabled, nextRunAtMs, scheduleKind, lastRunStatus) z cron(action: "list"); użyj cron(action: "get", jobId: "..."), aby uzyskać jedną pełną definicję zadania. Bezpośredni wywołujący Gateway mogą przekazać compact: true do cron.list; pominięcie tej opcji zachowuje istniejącą pełną odpowiedź z podglądami dostarczania.

openclaw cron create jest aliasem openclaw cron add, a nowe zadania mogą używać pozycyjnego harmonogramu ("0 9 * * 1", "every 1h", "20m" albo znacznika czasu ISO), po którym następuje pozycyjny prompt agenta. Użyj --webhook <url> w cron add|create albo cron edit, aby wysłać metodą POST payload zakończonego uruchomienia do punktu końcowego HTTP. Dostarczania Webhook nie można łączyć z flagami dostarczania na czat, takimi jak --announce, --channel, --to, --thread-id lub --account. W cron edit opcje --clear-channel, --clear-to, --clear-thread-id i --clear-account usuwają te pola routingu pojedynczo (każda jest odrzucana razem z odpowiadającą jej flagą ustawiającą), co różni się od --no-deliver, które wyłącza awaryjne dostarczanie przez runner.

Konfiguracja

{  cron: {    enabled: true,    store: "~/.openclaw/cron/jobs.json",    maxConcurrentRuns: 8,    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 ogranicza zarówno zaplanowaną dyspozycję Cron, jak i wykonywanie izolowanych tur agenta, a domyślnie wynosi 8. Izolowane tury agenta Cron używają wewnętrznie dedykowanej kolejki wykonywania cron-nested, więc zwiększenie tej wartości pozwala niezależnym uruchomieniom LLM Cron postępować równolegle, zamiast uruchamiać tylko ich zewnętrzne wrappery Cron. To ustawienie nie poszerza współdzielonej kolejki nie-Cron nested.

cron.store jest logicznym kluczem magazynu i starszą ścieżką importu dla doctor. Uruchom openclaw doctor --fix, aby zaimportować istniejące magazyny JSON do SQLite i je zarchiwizować; przyszłe zmiany Cron powinny przechodzić przez CLI lub API Gateway.

Wyłącz Cron: cron.enabled: false lub OPENCLAW_SKIP_CRON=1.

Rozwiązywanie problemów

Drabinka poleceń

openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --followopenclaw doctor

Powiązane

• Automatyzacja — wszystkie mechanizmy automatyzacji w skrócie
• Zadania w tle — rejestr zadań dla wykonań Cron
• Heartbeat — okresowe tury sesji głównej
• Strefa czasowa — konfiguracja strefy czasowej