Attività pianificate

Cron è lo scheduler integrato del Gateway. Mantiene i job, risveglia l'agente al momento giusto e può consegnare l'output a un canale chat o a un endpoint Webhook.

# Avvio rapido

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>

# Come funziona cron

• Cron viene eseguito dentro il processo Gateway (non dentro il modello).
• Le definizioni dei job persistono in ~/.openclaw/cron/jobs.json, quindi i riavvii non fanno perdere le pianificazioni.
• Lo stato di esecuzione runtime persiste accanto a esse in ~/.openclaw/cron/jobs-state.json. Se tracci le definizioni cron in git, traccia jobs.json e aggiungi jobs-state.json a gitignore.
• Dopo la separazione, le versioni precedenti di OpenClaw possono leggere jobs.json, ma potrebbero trattare i job come nuovi perché i campi runtime ora vivono in jobs-state.json.
• Quando jobs.json viene modificato mentre il Gateway è in esecuzione o arrestato, OpenClaw confronta i campi di pianificazione modificati con i metadati dello slot runtime in sospeso e cancella i valori nextRunAtMs obsoleti. Le riscritture di sola formattazione o solo dell'ordine delle chiavi preservano lo slot in sospeso.
• Tutte le esecuzioni cron creano record di attività in background.
• All'avvio del Gateway, i job agent-turn isolati scaduti vengono ripianificati fuori dalla finestra di connessione del canale invece di essere riprodotti immediatamente, così l'avvio di Discord/Telegram e la configurazione dei comandi nativi restano reattivi dopo i riavvii.
• I job una tantum (--at) vengono eliminati automaticamente dopo il successo per impostazione predefinita.
• Le esecuzioni cron isolate chiudono, con il massimo impegno, le schede e i processi del browser tracciati per la loro sessione cron:<jobId> quando l'esecuzione termina, così l'automazione browser scollegata non lascia processi orfani.
• Le esecuzioni cron isolate che ricevono la concessione ristretta di autopulizia cron possono comunque leggere lo stato dello scheduler e un elenco auto-filtrato del loro job corrente, così i controlli di stato/Heartbeat possono ispezionare la propria pianificazione senza ottenere un accesso più ampio alla mutazione cron.
• Le esecuzioni cron isolate proteggono anche dalle risposte di conferma obsolete. Se il primo risultato è solo un aggiornamento di stato provvisorio (on it, pulling everything together e indicazioni simili) e nessuna esecuzione di subagente discendente è ancora responsabile della risposta finale, OpenClaw richiede una volta il risultato effettivo prima della consegna.
• Le esecuzioni cron isolate preferiscono i metadati strutturati di negazione dell'esecuzione dall'esecuzione incorporata, poi ripiegano su marcatori noti di riepilogo/output finale come SYSTEM_RUN_DENIED e INVALID_REQUEST, così un comando bloccato non viene segnalato come un'esecuzione riuscita.
• Le esecuzioni cron isolate trattano anche gli errori dell'agente a livello di esecuzione come errori del job anche quando non viene prodotto alcun payload di risposta, così gli errori del modello/provider incrementano i contatori di errore e attivano le notifiche di errore invece di contrassegnare il job come riuscito.
• Quando un job agent-turn isolato raggiunge timeoutSeconds, cron interrompe l'esecuzione dell'agente sottostante e gli concede una breve finestra di pulizia. Se l'esecuzione non si svuota, la pulizia di proprietà del Gateway forza la cancellazione della proprietà della sessione di quell'esecuzione prima che cron registri il timeout, così il lavoro chat in coda non resta bloccato dietro una sessione di elaborazione obsoleta.

# Tipi di pianificazione

I timestamp senza fuso orario vengono trattati come UTC. Aggiungi --tz America/New_York per la pianificazione secondo l'ora locale.

Le espressioni ricorrenti all'inizio dell'ora vengono sfalsate automaticamente fino a 5 minuti per ridurre i picchi di carico. Usa --exact per forzare una temporizzazione precisa o --stagger 30s per una finestra esplicita.

# Giorno del mese e giorno della settimana usano la logica OR

Le espressioni Cron vengono analizzate da croner. Quando sia il campo giorno del mese sia il campo giorno della settimana non sono wildcard, croner corrisponde quando uno qualsiasi dei due campi corrisponde, non entrambi. Questo è il comportamento cron standard di 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

Questo si attiva circa 5-6 volte al mese invece di 0-1 volte al mese. OpenClaw usa qui il comportamento OR predefinito di Croner. Per richiedere entrambe le condizioni, usa il modificatore del giorno della settimana + di Croner (0 9 15 * +1) oppure pianifica su un campo e controlla l'altro nel prompt o nel comando del job.

# Stili di esecuzione

# Opzioni payload per job isolati

--model usa il modello consentito selezionato come modello principale di quel job. Non è uguale a un override /model della sessione chat: le catene di fallback configurate si applicano ancora quando il modello principale del job fallisce. Se il modello richiesto non è consentito o non può essere risolto, cron fa fallire l'esecuzione con un errore di validazione esplicito invece di ripiegare silenziosamente sulla selezione del modello agente/predefinito del job.

Se voci jobs.json più vecchie o modificate a mano memorizzano payload.model come "default", "null", una stringa vuota o JSON null, esegui openclaw doctor --fix. Doctor rimuove quei sentinel di override persistiti non validi; il runtime non li supporta come alias di fallback. Ometti il campo model per usare la normale selezione del modello agente/predefinito.

I job Cron possono anche includere fallbacks a livello di payload. Quando presente, quell'elenco sostituisce la catena di fallback configurata per il job. Usa fallbacks: [] nel payload/API del job quando vuoi un'esecuzione cron rigorosa che provi solo il modello selezionato. Se un job ha --model ma non ha fallback né nel payload né configurati, OpenClaw passa un override di fallback vuoto esplicito, così il modello principale dell'agente non viene aggiunto come target di retry extra nascosto.

La precedenza di selezione del modello per i job isolati è:

1. Override del modello dell'hook Gmail (quando l'esecuzione proviene da Gmail e quell'override è consentito)
2. model del payload per job
3. Override del modello della sessione cron memorizzato selezionato dall'utente
4. Selezione del modello agente/predefinito

Anche la modalità fast segue la selezione live risolta. Se la configurazione del modello selezionato ha params.fastMode, cron isolato la usa per impostazione predefinita. Un override fastMode della sessione memorizzata prevale comunque sulla configurazione in entrambe le direzioni.

Se un'esecuzione isolata incontra un handoff live di cambio modello, cron riprova con il provider/modello selezionato e mantiene quella selezione live per l'esecuzione attiva prima di riprovare. Quando il cambio include anche un nuovo profilo auth, cron mantiene anche quell'override del profilo auth per l'esecuzione attiva. I retry sono limitati: dopo il tentativo iniziale più 2 retry di cambio, cron interrompe invece di entrare in un ciclo infinito.

Prima che un'esecuzione cron isolata entri nel runner dell'agente, OpenClaw controlla gli endpoint provider locali raggiungibili per provider configurati api: "ollama" e api: "openai-completions" il cui baseUrl è local loopback, rete privata o .local. Se quell'endpoint è inattivo, l'esecuzione viene registrata come skipped con un errore provider/modello chiaro invece di avviare una chiamata al modello. Il risultato dell'endpoint viene memorizzato in cache per 5 minuti, così molti job in scadenza che usano lo stesso server locale Ollama, vLLM, SGLang o LM Studio inattivo condividono un piccolo probe invece di creare una tempesta di richieste. Le esecuzioni saltate dal preflight del provider non incrementano il backoff degli errori di esecuzione; abilita failureAlert.includeSkipped quando vuoi notifiche ripetute per i salti.

# Consegna e output

Usa --announce --channel telegram --to "-1001234567890" per la consegna al canale. Per gli argomenti dei forum Telegram, usa -1001234567890:topic:123; i chiamanti RPC/config diretti possono anche passare delivery.threadId come stringa o numero. I target Slack/Discord/Mattermost devono usare prefissi espliciti (channel:<id>, user:<id>). Gli ID delle stanze Matrix distinguono maiuscole e minuscole; usa l’ID esatto della stanza o la forma room:!room:server da Matrix.

Quando la consegna announce usa channel: "last" oppure omette channel, un target con prefisso del provider come telegram:123 può selezionare il canale prima che cron ripieghi sulla cronologia della sessione o su un singolo canale configurato. Solo i prefissi annunciati dal Plugin caricato sono selettori di provider. Se delivery.channel è esplicito, il prefisso del target deve indicare lo stesso provider; per esempio, channel: "whatsapp" con to: "telegram:123" viene rifiutato invece di lasciare che WhatsApp interpreti l’ID Telegram come numero di telefono. I prefissi di tipo target e servizio, come channel:<id>, user:<id>, imessage:<handle> e sms:<number>, restano sintassi dei target di proprietà del canale, non selettori di provider.

Per i job isolati, la consegna in chat è condivisa. Se è disponibile una route di chat, l’agente può usare lo strumento message anche quando il job usa --no-deliver. Se l’agente invia al target configurato/corrente, OpenClaw salta l’annuncio di fallback. In caso contrario, announce, webhook e none controllano solo cosa fa il runner con la risposta finale dopo il turno dell’agente.

Quando un agente crea un promemoria isolato da una chat attiva, OpenClaw memorizza il target di consegna live preservato per la route di annuncio di fallback. Le chiavi di sessione interne possono essere in minuscolo; i target di consegna del provider non vengono ricostruiti da quelle chiavi quando è disponibile il contesto della chat corrente.

La consegna announce implicita usa allowlist dei canali configurate per convalidare e reindirizzare i target obsoleti. Le approvazioni dello store di associazione DM non sono destinatari dell’automazione di fallback; imposta delivery.to oppure configura la voce allowFrom del canale quando un job pianificato deve inviare proattivamente a un DM.

Le notifiche di errore seguono un percorso di destinazione separato:

• cron.failureDestination imposta un valore predefinito globale per le notifiche di errore.
• job.delivery.failureDestination lo sovrascrive per singolo job.
• Se nessuno dei due è impostato e il job consegna già tramite announce, le notifiche di errore ora ripiegano su quel target announce primario.
• delivery.failureDestination è supportato solo sui job sessionTarget="isolated", a meno che la modalità di consegna primaria sia webhook.
• failureAlert.includeSkipped: true abilita per un job o per la policy globale degli avvisi cron gli avvisi ripetuti sulle esecuzioni saltate. Le esecuzioni saltate mantengono un contatore separato di salti consecutivi, quindi non influiscono sul backoff degli errori di esecuzione.

# Esempi 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 può esporre endpoint Webhook HTTP per trigger esterni. Abilitali nella configurazione:

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

# Autenticazione

Ogni richiesta deve includere il token dell’hook tramite header:

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

I token nella stringa di query vengono rifiutati.

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

# Integrazione Gmail PubSub

Collega i trigger della posta in arrivo Gmail a OpenClaw tramite Google PubSub.

# Configurazione guidata (consigliata)

openclaw webhooks gmail setup --account [email protected]

Questo scrive la configurazione hooks.gmail, abilita il preset Gmail e usa Tailscale Funnel per l’endpoint push.

# Avvio automatico del Gateway

Quando hooks.enabled=true e hooks.gmail.account è impostato, il Gateway avvia gog gmail watch serve al boot e rinnova automaticamente il watch. Imposta OPENCLAW_SKIP_GMAIL_WATCHER=1 per disattivarlo.

# Configurazione manuale una tantum

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

# Override del modello Gmail

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

# Gestione dei job

# 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

# Configurazione

{
  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 limita sia il dispatch cron pianificato sia l’esecuzione dei turni agente isolati. I turni agente cron isolati usano internamente la lane di esecuzione dedicata cron-nested della coda, quindi aumentare questo valore consente a esecuzioni LLM cron indipendenti di avanzare in parallelo invece di avviare soltanto i loro wrapper cron esterni. La lane condivisa non cron nested non viene ampliata da questa impostazione.

Il sidecar dello stato runtime deriva da cron.store: uno store .json come ~/clawd/cron/jobs.json usa ~/clawd/cron/jobs-state.json, mentre un percorso di store senza suffisso .json aggiunge -state.json.

Se modifichi manualmente jobs.json, lascia jobs-state.json fuori dal controllo versione. OpenClaw usa quel sidecar per slot in sospeso, marker attivi, metadati dell’ultima esecuzione e l’identità della pianificazione che indica allo scheduler quando un job modificato esternamente necessita di un nuovo nextRunAtMs.

Disabilita cron: cron.enabled: false o OPENCLAW_SKIP_CRON=1.

# Risoluzione dei problemi

# Sequenza di comandi

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

# Correlati

• Automazione e attività — tutti i meccanismi di automazione in sintesi
• Attività in background — registro delle attività per le esecuzioni Cron
• Heartbeat — turni periodici della sessione principale
• Fuso orario — configurazione del fuso orario