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

# Szybki start

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>

# Jak działa Cron

• Cron działa wewnątrz procesu Gateway (nie wewnątrz modelu).
• Definicje zadań są utrwalane w ~/.openclaw/cron/jobs.json, więc ponowne uruchomienia nie powodują utraty harmonogramów.
• Stan wykonania w czasie działania jest utrwalany obok, w ~/.openclaw/cron/jobs-state.json. Jeśli śledzisz definicje Cron w git, śledź jobs.json i dodaj jobs-state.json do gitignore.
• Po podziale starsze wersje OpenClaw mogą odczytywać jobs.json, ale mogą traktować zadania jako nowe, ponieważ pola czasu działania znajdują się teraz w jobs-state.json.
• Gdy jobs.json zostanie edytowany podczas działania Gateway lub gdy jest on zatrzymany, OpenClaw porównuje zmienione pola harmonogramu z oczekującymi metadanymi slotu czasu działania i czyści nieaktualne wartości nextRunAtMs. Czyste zmiany formatowania lub wyłącznie kolejności kluczy zachowują oczekujący slot.
• Wszystkie wykonania Cron tworzą rekordy zadania w tle.
• Podczas uruchamiania Gateway zaległe izolowane zadania tury agenta są planowane poza oknem łączenia kanałów zamiast być natychmiast odtwarzane, dzięki czemu uruchamianie Discord/Telegram i konfiguracja poleceń natywnych pozostają responsywne po restartach.
• Zadania jednorazowe (--at) domyślnie automatycznie usuwają się po sukcesie.
• Izolowane uruchomienia Cron w najlepszym możliwym zakresie zamykają śledzone karty/prcesy przeglądarki dla swojej sesji cron:<jobId> po zakończeniu uruchomienia, dzięki czemu odłączona automatyzacja przeglądarki nie pozostawia osieroconych procesów.
• Izolowane uruchomienia Cron, które otrzymają wąskie uprawnienie samooczyszczania Cron, nadal mogą odczytywać status harmonogramu i samofiltrowaną listę swojego bieżącego zadania, dzięki czemu kontrole statusu/heartbeat mogą sprawdzać własny harmonogram bez uzyskiwania szerszego dostępu do mutowania Cron.
• Izolowane uruchomienia Cron chronią też 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 jest już odpowiedzialne za ostateczną odpowiedź, OpenClaw ponownie pyta raz o rzeczywisty wynik przed dostarczeniem.
• Izolowane uruchomienia Cron preferują ustrukturyzowane metadane odmowy wykonania z osadzonego uruchomienia, a następnie wracają do znanych znaczników końcowego podsumowania/wyjścia, takich jak SYSTEM_RUN_DENIED i INVALID_REQUEST, dzięki czemu zablokowane polecenie nie jest zgłaszane jako udane uruchomienie.
• Izolowane uruchomienia Cron traktują też awarie agenta na poziomie uruchomienia jako błędy zadania nawet wtedy, gdy nie powstaje ładunek odpowiedzi, dzięki czemu awarie modelu/providera zwiększają liczniki błędów i wyzwalają powiadomienia o awarii zamiast oznaczać zadanie jako udane.
• Gdy izolowane zadanie tury agenta osiągnie timeoutSeconds, Cron przerywa bazowe uruchomienie agenta i daje mu krótkie okno na oczyszczenie. Jeśli uruchomienie nie zostanie opróżnione, oczyszczanie należące do Gateway wymusza wyczyszczenie własności sesji tego uruchomienia, zanim Cron zapisze przekroczenie limitu czasu, dzięki czemu zakolejkowana praca czatu nie zostaje za nieaktualną sesją przetwarzania.

# Typy harmonogramów

Znaczniki czasu bez strefy czasowej są traktowane jako UTC. Dodaj --tz America/New_York, aby planować według lokalnego czasu zegarowego.

Cykliczne wyrażenia na początku godziny są automatycznie rozkładane z przesunięciem do 5 minut, aby zmniejszyć skoki obciążenia. Użyj --exact, aby wymusić precyzyjny czas, lub --stagger 30s, aby podać 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ą wieloznaczne, croner dopasowuje, gdy pasuje którekolwiek z pól, a nie oba. Jest to standardowe zachowanie 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

To uruchamia się około 5–6 razy w miesiącu zamiast 0–1 razy w miesiącu. 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 zaplanuj według jednego pola i zabezpiecz drugie w prompcie lub poleceniu zadania.

# Style wykonywania

# Opcje ładunku dla zadań izolowanych

--model używa wybranego dozwolonego modelu jako podstawowego modelu tego zadania. To nie jest to samo co nadpisanie /model 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.

Jeśli starsze lub ręcznie edytowane wpisy jobs.json przechowują payload.model jako "default", "null", pusty ciąg albo JSON null, uruchom openclaw doctor --fix. Doctor usuwa te nieprawidłowe utrwalone sentinele nadpisań; runtime nie obsługuje ich jako aliasów fallback. Pomiń pole modelu, aby użyć normalnego wyboru modelu agenta/domyślnego.

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

Priorytet wyboru modelu dla zadań izolowanych jest następujący:

1. Nadpisanie modelu haka Gmail (gdy uruchomienie pochodzi z Gmail i to nadpisanie jest dozwolone)
2. model w ładunku 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 używa jej domyślnie. Zapisane nadpisanie fastMode sesji nadal wygrywa z konfiguracją w obu kierunkach.

Jeśli izolowane uruchomienie trafi na przekazanie przełącznika modelu na żywo, Cron ponawia z przełączonym providerem/modelem i utrwala tę aktywną selekcję dla bieżącego uruchomienia przed ponowieniem. Gdy przełączenie niesie też nowy profil autoryzacji, Cron utrwala również nadpisanie tego profilu autoryzacji dla aktywnego uruchomienia. Ponowienia są ograniczone: po początkowej próbie plus 2 ponowieniach przełączenia Cron przerywa zamiast zapętlać się bez końca.

Zanim izolowane uruchomienie Cron wejdzie do runnera agenta, OpenClaw sprawdza osiągalne lokalne punkty końcowe providerów dla skonfigurowanych providerów api: "ollama" i api: "openai-completions", których baseUrl jest local loopback, siecią prywatną lub .local. Jeśli ten punkt końcowy jest niedostępny, uruchomienie jest zapisywane jako skipped z jasnym błędem providera/modelu zamiast rozpoczynać wywołanie modelu. Wynik punktu końcowego jest buforowany przez 5 minut, więc wiele wymagalnych 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ń. Pominięte uruchomienia preflight providera nie zwiększają backoffu błędów wykonania; włącz failureAlert.includeSkipped, gdy chcesz powtarzane powiadomienia o pominięciu.

# Dostarczanie i wynik

Użyj --announce --channel telegram --to "-1001234567890" do dostarczania na kanał. W przypadku tematów forum Telegram użyj -1001234567890:topic:123; bezpośredni wywołujący RPC/konfiguracji mogą też przekazać delivery.threadId jako ciąg znaków 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" albo 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 providera są tylko prefiksy ogłaszane przez załadowany Plugin. Jeśli delivery.channel jest jawny, prefiks celu musi wskazywać tego samego providera; na przykład channel: "whatsapp" z to: "telegram:123" jest odrzucane zamiast pozwolić WhatsApp zinterpretować 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 providera.

W przypadku izolowanych zadań dostarczanie czatu jest współdzielone. Jeśli trasa czatu jest dostępna, agent może używać narzędzia message, nawet gdy zadanie używa --no-deliver. Jeśli agent wysyła do skonfigurowanego/bieżącego celu, OpenClaw pomija awaryjne 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 awaryjnej trasy announce. Wewnętrzne klucze sesji mogą być pisane małymi literami; cele dostarczania providera nie są odtwarzane z tych kluczy, gdy dostępny jest bieżący kontekst czatu.

Niejawne dostarczanie announce używa skonfigurowanych list dozwolonych kanałów do weryfikowania i przekierowywania nieaktualnych celów. Zatwierdzenia z magazynu par DM nie są odbiorcami automatyzacji awaryjnej; ustaw delivery.to albo skonfiguruj wpis kanału allowFrom, gdy zaplanowane zadanie ma proaktywnie wysyłać do DM.

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

• cron.failureDestination ustawia globalną wartość domyślną dla powiadomień o awariach.
• job.delivery.failureDestination nadpisuje ją dla danego zadania.
• Jeśli żadna z nich nie jest ustawiona, a zadanie już dostarcza przez announce, powiadomienia o awariach wracają teraz do tego głównego celu announce.
• delivery.failureDestination jest obsługiwane tylko w zadaniach sessionTarget="isolated", chyba że głównym trybem dostarczania jest webhook.
• failureAlert.includeSkipped: true włącza dla zadania lub globalnej polityki alertów cron powtarzane alerty o pominiętych uruchomieniach. Pominięte uruchomienia utrzymują 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 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

# Webhooki

Gateway może udostępniać endpointy HTTP Webhook dla wyzwalaczy zewnętrznych. 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 ciągu zapytania 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 (zalecana)

openclaw webhooks gmail setup --account [email protected]

Zapisuje to konfigurację hooks.gmail, włącza preset Gmail i używa Tailscale Funnel dla endpointu 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 zrezygnować.

# Ręczna jednorazowa konfiguracja

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

# Nadpisanie modelu Gmail

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

# Zarządzanie zadaniami

# 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

# Konfiguracja

{
  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 ogranicza zarówno zaplanowane dispatchowanie cron, jak i wykonanie tury izolowanego agenta. Tury izolowanych agentów cron używają wewnętrznie dedykowanej kolejki wykonawczej 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. Współdzielona nie-cronowa kolejka nested nie jest poszerzana przez to ustawienie.

Plik pomocniczy stanu runtime jest wyprowadzany z cron.store: magazyn .json, taki jak ~/clawd/cron/jobs.json, używa ~/clawd/cron/jobs-state.json, natomiast ścieżka magazynu bez sufiksu .json dodaje -state.json.

Jeśli ręcznie edytujesz jobs.json, pozostaw jobs-state.json poza kontrolą wersji. OpenClaw używa tego pliku pomocniczego dla oczekujących slotów, aktywnych markerów, metadanych ostatniego uruchomienia i tożsamości harmonogramu, która mówi schedulerowi, kiedy zewnętrznie edytowane zadanie wymaga świeżego nextRunAtMs.

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

# Rozwiązywanie problemów

# Drabinka poleceń

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

# Powiązane

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