Tâches planifiées

Cron est le planificateur intégré de la Gateway. Il persiste les tâches, réveille l’agent au bon moment et peut renvoyer le résultat vers un channel de discussion ou un point de terminaison webhook.

Quick start

1. Ajouter un rappel unique

   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

2. Vérifier vos tâches

   openclaw cron list
   openclaw cron get

   openclaw cron show

3. Voir l'historique d'exécution

   openclaw cron runs --id

Fonctionnement de cron

• Cron s’exécute au sein du processus du Gateway (et non au sein du modèle).
• Les définitions de tâches, l’état d’exécution et l’historique des exécutions sont persistés dans la base de données d’état SQLite partagée d’OpenClaw, de sorte que les redémarrages ne fassent pas perdre les planifications.
• Lors de la mise à niveau, exécutez openclaw doctor --fix pour importer les fichiers ~/.openclaw/cron/jobs.json, jobs-state.json et runs/*.jsonl hérités vers SQLite et les renommer avec le suffixe .migrated. Les lignes de tâches malformées sont ignorées lors de l’exécution et copiées dans jobs-quarantine.json pour réparation ou examen ultérieur.
• cron.store nomme toujours la clé logique de stockage cron et le chemin d’importation du docteur. Après l’importation, la modification de ce fichier JSON ne change plus les tâches cron actives ; utilisez plutôt openclaw cron add|edit|remove ou les méthodes RPC du cron du GatewayRPC.
• Toutes les exécutions cron créent des enregistrements de tâche d’arrière-plan.
• Au démarrage du Gateway, les tâches isolées en attente d’exécution par l’agent (agent-turn) en retard sont replanifiées en dehors de la fenêtre de connexion du canal au lieu d’être rejouées immédiatement, afin que le démarrage de Discord/Telegram et la configuration des commandes natives restent réactifs après les redémarrages.
• Les tâches ponctuelles (--at) sont supprimées automatiquement après succès par défaut.
• Les exécutions cron isolées tentent au mieux de fermer les onglets/processus de navigateur suivis pour leur cron:<jobId> session lorsque l’exécution est terminée, afin que l’automatisation de navigateur détachée ne laisse pas de processus orphelins.
• Les exécutions cron isolées qui reçoivent la subvention étroite d’auto-nettoyage cron peuvent toujours lire le statut du planificateur, une liste auto-filtrée de leur tâche actuelle et l’historique d’exécution de cette tâche, afin que les vérifications de statut/heartbeat puissent inspecter leur propre planification sans obtenir un accès plus large à la mutation cron.
• Les exécutions cron isolées se protègent également contre les réponses d’accusé de réception périmées. Si le premier résultat est seulement une mise à jour de l’état provisoire (on it, pulling everything together, et indices similaires) et qu’aucune exécution de sous-agent descendant n’est encore responsable de la réponse finale, OpenClaw redemande une fois le résultat réel avant la livraison.
• Les exécutions cron isolées utilisent des métadonnées structurées de refus d’exécution provenant de l’exécution intégrée, y compris les wrappers UNAVAILABLE de nœud hôte dont le message d’erreur imbriqué commence par SYSTEM_RUN_DENIED ou INVALID_REQUEST, afin qu’une commande bloquée ne soit pas signalée comme une exécution réussie tandis que la prose ordinaire de l’assistant n’est pas traitée comme un refus.
• Les exécutions cron isolées traitent également les échecs de l’agent au niveau de l’exécution comme des erreurs de tâche même lorsqu’aucune charge utile de réponse n’est produite, de sorte que les échecs du modèle/fournisseur incrémentent les compteurs d’erreurs et déclenchent des notifications d’échec au lieu de marquer la tâche comme réussie.
• Lorsqu’une tâche isolée de tour d’agent atteint timeoutSeconds, le cron interrompt l’exécution de l’agent sous-jacente et lui accorde une courte fenêtre de nettoyage. Si l’exécution ne se vide pas, le nettoyage propriété du Gateway force la suppression de la propriété de session de cette exécution avant que le cron n’enregistre le délai d’attente, afin que le travail de chat en file d’attente ne reste pas derrière une session de traitement périmée.
• Si un tour d’agent isolé stalle avant le démarrage du lanceur ou avant le premier appel de modèle, cron enregistre un délai d’attente spécifique à la phase tel que setup timed out before runner start ou stalled before first model call (last phase: context-engine). Ces chiens de garde couvrent les fournisseurs intégrés et les fournisseurs basés sur CLI avant que leur processus externe CLI ne soit réellement démarré, et sont plafonnés indépendamment des longues valeurs timeoutSeconds afin que les échecs de démarrage à froid, d’authentification ou de contexte apparaissent rapidement au lieu d’attendre le budget complet de la tâche.
• Si vous utilisez le cron système ou un autre planificateur externe pour exécuter openclaw agent, enveloppez-le d’une escalade de terminaison forcée même si le CLI gère SIGTERM/SIGINT. Les exécutions soutenues par Gateway demandent au Gateway d’annuler les exécutions acceptées ; les exécutions de secours locales et intégrées reçoivent le même signal d’annulation. Pour GNU timeout, préférez timeout -k 60 600 openclaw agent ... à un simple timeout 600 ... ; la valeur -k est le filet de sécurité du superviseur si le processus ne peut pas se drainer. Pour les unités systemd, gardez la même forme en utilisant un signal d’arrêt SIGTERM plus une fenêtre de grâce telle que TimeoutStopSec avant toute terminaison finale. Si une nouvelle tentative réutilise un --run-id alors que l’exécution Gateway d’origine est toujours active, le doublon est signalé comme étant en cours au lieu de démarrer une deuxième exécution.

Note

La réconciliation des tâches pour cron est d’abord gérée par le runtime, puis secondairement sauvegardée par l’historique durable : une tâche cron active reste vivante tant que le runtime cron suit toujours ce travail comme étant en cours d’exécution, même si une ancienne ligne de session enfant existe toujours. Une fois que le runtime cesse de posséder le travail et que la fenêtre de grâce de 5 minutes expire, la maintenance vérifie les journaux d’exécution persistants et l’état du travail pour l’exécution `cron:

:

correspondante. Si cet historique durable montre un résultat terminal, le grand livre des tâches est finalisé à partir de celui-ci ; sinon la maintenance détenue par le Gateway peut marquer la tâche commelost`. L’audit hors ligne du CLI peut récupérer à partir de l’historique durable, mais il ne traite pas son propre ensemble vide de travaux actifs en cours comme une preuve qu’une exécution cron détenue par le Gateway a disparu.

Types de planification

Type	Indicateur CLI	Description
at	--at	Horodatage ponctuel (ISO 8601 ou relatif comme 20m)
every	--every	Intervalle fixe
cron	--cron	Expression cron à 5 ou 6 champs avec --tz facultatif

Les horodatages sans fuseau horaire sont traités comme UTC. Ajoutez --tz America/New_York pour une planification locale basée sur l’horloge murale.

Les expressions récurrentes en début d’heure sont automatiquement échelonnées jusqu’à 5 minutes pour réduire les pics de charge. Utilisez --exact pour forcer un timing précis ou --stagger 30s pour une fenêtre explicite.

Jour du mois et jour de la semaine utilisent une logique OU

Les expressions cron sont analysées par croner. Lorsque les champs jour-du-mois et jour-de-la-semaine sont tous deux non génériques, croner correspond lorsque l’un ou l’autre des champs correspond — et non les deux. Il s’agit du comportement standard de 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

Cela se déclenche environ 5 à 6 fois par mois au lieu de 0 à 1 fois par mois. OpenClaw utilise ici le comportement OR par défaut de Croner. Pour exiger les deux conditions, utilisez le modificateur jour-de-la-semaine + de Croner (0 9 15 * +1) ou planifiez sur un champ et gardez l’autre dans le prompt ou la commande de votre travail.

Styles d’exécution

Style	valeur --session	S’exécute dans	Idéal pour
Session principale	main	Voie de réveil cron dédiée	Rappels, événements système
Isolé	isolated	cron:<jobId> dédié	Rapports, tâches en arrière-plan
Session actuelle	current	Lié au moment de la création	Travail récurrent contextuel
Session personnalisée	session:custom-id	Session nommée persistante	Workflows basés sur l’historique

Session principale vs isolée vs personnalisée

Les tâches de session principale mettent en file un événement système dans une voie d’exécution appartenant à cron et réveillent facultativement le heartbeat (--wake now ou --wake next-heartbeat). Elles peuvent utiliser le contexte de la dernière livraison de la session principale cible pour les réponses, mais elles n’ajoutent pas de tours cron de routine à la voie de discussion humaine et n’étendent pas la fraîcheur de réinitialisation journalière/inactivité pour la session cible. Les tâches isolées exécutent un tour d’agent dédié avec une session fraîche. Les sessions personnalisées (session:xxx) conservent le contexte entre les exécutions, permettant des flux de travail tels que les stand-ups quotidiens qui s’appuient sur des résumés précédents.

Les événements cron de session principale sont des rappels d’événements système autonomes. Ils n’incluent pas automatiquement l’instruction « Lire HEARTBEAT.md » du prompt heartbeat par défaut. Si un rappel récurrent doit consulter HEARTBEAT.md, indiquez-le explicitement dans le texte de l’événement cron ou dans les instructions propres de l’agent.

Ce que signifie « session fraîche » pour les tâches isolées

Pour les tâches isolées, « session fraîche » signifie un nouvel identifiant de transcription/session pour chaque exécution. OpenClaw peut transporter des préférences sécurisées telles que les paramètres de réflexion/rapide/verbeux, les étiquettes et les substitutions de modèle/authentification explicitement sélectionnées par l’utilisateur, mais il n’hérite pas du contexte de conversation ambiant d’une ligne cron plus ancienne : le routage channel/groupe, la politique d’envoi ou de file d’attente, l’élévation, l’origine ou la liaison d’exécution ACP. Utilisez current ou `session:

` lorsqu’une tâche récurrente doit délibérément s’appuyer sur le même contexte de conversation.

Nettoyage de l'exécution

Pour les tâches isolées, le démontage de l’exécution inclut désormais un nettoyage du navigateur de meilleure volonté pour cette session cron. Les échecs de nettoyage sont ignorés afin que le résultat réel du cron prime toujours.

Les exécutions cron isolées suppriment également toutes les instances d’exécution MCP groupées créées pour la tâche via le chemin de nettoyage de l’exécution partagé. Cela correspond à la manière dont les clients MCP de session principale et de session personnalisée sont démontés, de sorte que les tâches cron isolées ne fuient pas les processus enfants stdio ou les connexions MCP durables entre les exécutions.

DiscordSubagent et livraison Discord

Lorsque les tâches cron isolées orchestrent des sous-agents, la livraison privilégie également la sortie finale du descendant par rapport au texte intermédiaire parent périmé. Si les descendants sont toujours en cours d’exécution, OpenClaw supprime cette mise à jour parentielle partielle au lieu de l’annoncer.

Pour les cibles d’annonce Discord texte uniquement, OpenClaw envoie le texte final canonique de l’assistant une seule fois au lieu de relayer à la fois les charges utiles de texte diffusé/intermédiaire et la réponse finale. Les médias et les charges utiles structurées Discord sont toujours livrés sous forme de charges utiles distinctes afin que les pièces jointes et les composants ne soient pas perdus.

Options de charge utile pour les tâches isolées

Texte du prompt (requis pour isolated). Remplacement du model ; utilise le model autorisé sélectionné pour la tâche. Remplacement du niveau de réflexion. Ignorer l'injection du fichier d'amorçage de l'espace de travail. Limiter les outils que la tâche peut utiliser, par exemple `--tools exec,read`.

--model utilise le model autorisé sélectionné comme model principal de cette tâche. Ce n’est pas la même chose qu’un remplacement /model de session de chat : les chaînes de repli configurées s’appliquent toujours lorsque le model principal de la tâche échoue. Si le model demandé n’est pas autorisé ou ne peut pas être résolu, cron échoue l’exécution avec une erreur de validation explicite au lieu de revenir silencieusement au choix du model par défaut de l’agent/de la tâche.

Les tâches cron peuvent également porter des fallbacks au niveau du payload. Lorsqu’elle est présente, cette liste remplace la chaîne de repli configurée pour la tâche. Utilisez fallbacks: [] dans le payload/API de la tâche lorsque vous souhaitez une exécution cron stricte qui n’essaie que le model sélectionné. Si une tâche a --model mais ni payload ni replis configurés, OpenClaw transmet un remplacement de repli vide explicite afin que le principal de l’agent ne soit pas ajouté comme cible de retry supplémentaire cachée.

Les vérifications préliminaires du fournisseur local parcourent les replis configurés avant de marquer une exécution cron comme skipped ; fallbacks: [] maintient ce chemin préliminaire strict.

La priorité de sélection du modèle pour les tâches isolées est :

1. Substitution du modèle pour le hook Gmail (lorsque l’exécution provient de Gmail et que cette substitution est autorisée)
2. model du payload par tâche
3. Substitution du modèle de session cron stocké sélectionné par l’utilisateur
4. Sélection du modèle agent/défaut

Le mode rapide suit également la sélection en direct résolue. Si la configuration du model sélectionné contient params.fastMode, le cron isolé l’utilise par défaut. Un remplacement fastMode de session stockée prime toujours sur la configuration dans les deux sens.

Si une exécution isolée rencontre un transfert de changement de modèle en direct, le cron réessaie avec le fournisseur/modèle commuté et rend persistante cette sélection en direct pour l’exécution active avant de réessayer. Lorsque le transfert comprend également un nouveau profil d’authentification, le cron rend également persistante cette substitution de profil d’authentification pour l’exécution active. Les tentatives sont limitées : après la tentative initiale plus 2 tentatives de transfert, le cron abandonne au lieu de boucler indéfiniment.

Avant qu’une exécution cron isolée n’entre dans le runner de l’agent, OpenClaw vérifie les points de terminaison de fournisseurs locaux accessibles pour les fournisseurs OpenClawapi: "ollama" et api: "openai-completions" configurés dont le baseUrl est bouclage (loopback), réseau privé ou .local. Si ce point de terminaison est en panne, l’exécution est enregistrée comme skippedOllama avec une erreur claire de fournisseur/modèle au lieu de lancer un appel au modèle. Le résultat du point de terminaison est mis en cache pendant 5 minutes, de sorte que de nombreuses tâches en attente utilisant le même serveur local Ollama, vLLM, SGLang ou LM Studio mort partagent une petite sonde unique au lieu de créer une tempête de requêtes. Les exécutions avec prévol de fournisseur ignorées (skipped) n’incrémentent pas le délai d’attente pour erreur d’exécution ; activez failureAlert.includeSkipped lorsque vous souhaitez des notifications répétées d’ignor.

Livraison et sortie

Mode	Ce qui se passe
announce	Livraison de secours du texte final vers la cible si l’agent ne l’a pas envoyé
webhook	POST de la charge utile de l’événement terminé vers une URL
none	Aucune livraison de secours de l’exécuteur

Utilisez --announce --channel telegram --to "-1001234567890"Telegram pour la livraison vers un canal. Pour les sujets de forum Telegram, utilisez -1001234567890:topic:123OpenClawTelegram ; OpenClaw accepte également l’abréviation -1001234567890:123RPC propriétaire de Telegram. Les appelants directs RPC/config peuvent passer delivery.threadIdSlackDiscordMattermost sous forme de chaîne ou de nombre. Les cibles Slack/Discord/Mattermost doivent utiliser des préfixes explicites (channel:<id>, user:<id>Matrix). Les ID de salle Matrix sont sensibles à la casse ; utilisez l’ID de salle exact ou le formulaire room:!room:serverMatrix provenant de Matrix.

Lorsque la livraison d’annonce utilise channel: "last" ou omet channel, une cible avec un préfixe de fournisseur telle que telegram:123 peut sélectionner le canal avant que cron ne revienne à l’historique de session ou à un canal configuré unique. Seuls les préfixes annoncés par le plugin chargé sont des sélecteurs de fournisseur. Si delivery.channel est explicite, le préfixe de cible doit nommer le même fournisseur ; par exemple, channel: "whatsapp" avec to: "telegram:123" est rejeté au lieu de laisser WhatsApp interpréter l’ID Telegram comme un numéro de téléphone. Les préfixes de type de cible et de service tels que channel:<id>, user:<id>, imessage:<handle> et sms:<number> restent une syntaxe de cible détenue par le canal, et non des sélecteurs de fournisseur.

Pour les tâches isolées, la livraison de chat est partagée. Si un itinéraire de chat est disponible, l’agent peut utiliser l’outil message même lorsque la tâche utilise --no-deliver. Si l’agent envoie à la cible configurée/actuelle, OpenClaw ignore l’annonce de repli. Sinon, announce, webhook et none ne contrôlent que ce que le runner fait avec la réponse finale après le tour de l’agent.

Lorsqu’un agent crée un rappel isolé à partir d’un chat actif, OpenClaw stocke la cible de livraison live préservée pour la route d’annonce de secours. Les clés de session internes peuvent être en minuscules ; les cibles de livraison par fournisseur ne sont pas reconstruites à partir de ces clés lorsque le contexte de chat actuel est disponible.

La livraison d’annonce implicite utilise les listes d’autorisation de canaux configurées pour valider et réacheminer les cibles obsolètes. Les approbations de magasin d’appariement DM ne sont pas des destinataires d’automatisation de repli ; définissez delivery.to ou configurez l’entrée allowFrom du canal lorsqu’une tâche planifiée doit envoyer de manière proactive à un DM.

Langue de sortie

Les tâches cron n’infèrent pas de langue de réponse à partir du canal, des paramètres régionaux ou des messages précédents. Placez la règle de langue dans le message planifié ou le modèle :

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

Pour les fichiers de modèle, conservez l’instruction de langue dans l’invite rendue et vérifiez que les espaces réservés tels que {{language}} sont remplis avant l’exécution de la tâche. Si la sortie mélange les langues, rendez la règle explicite, par exemple : « Utiliser le chinois pour le texte narratif et garder les termes techniques en anglais ».

Les notifications d’échec suivent un chemin de destination séparé :

• cron.failureDestination définit une valeur par défaut globale pour les notifications d’échec.
• job.delivery.failureDestination remplace cela pour chaque tâche.
• Si aucun des deux n’est défini et que la tâche délivre déjà via announce, les notifications d’échec reviennent désormais à cette cible d’annonce principale.
• delivery.failureDestination n’est pris en charge que sur les tâches sessionTarget="isolated", sauf si le mode de livraison principal est webhook.
• failureAlert.includeSkipped: true active pour une tâche ou une stratégie d’alerte cron globale des alertes répétées pour les exécutions ignorées. Les exécutions ignorées conservent un compteur consécutif distinct, elles n’affectent donc pas l’attente après erreur d’exécution.

Exemples CLI

Rappel ponctuelTâche isolée récurrenteModèle et remplacement de la réflexionSortie webhook

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

bash openclaw cron create "0 7 * * *" \ "Summarize overnight updates." \ --name "Morning brief" \ --tz "America/Los_Angeles" \ --session isolated \ --announce \ --channel slack \ --to "channel:C1234567890"

bash 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

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

Webhooks

Le Gateway peut exposer des points de terminaison HTTP webhook pour des déclencheurs externes. Activer dans la configuration :

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

Authentification

Chaque requête doit inclure le jeton du hook via l’en-tête :

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

Les jetons de chaîne de requête sont rejetés.

POST /hooks/wake

Mettre en file d’attente un événement système pour la session principale :

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

Description de l’événement.

now ou next-heartbeat.

POST /hooks/agent

Exécuter un tour d’agent isolé :

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

Champs : message (requis), name, agentId, wakeMode, deliver, channel, to, model, fallbacks, thinking, timeoutSeconds.

Mapped hooks (POST /hooks/<name>)

Les noms de hooks personnalisés sont résolus via hooks.mappings dans la configuration. Les mappages peuvent transformer des charges utiles arbitraires en actions wake ou agent à l’aide de modèles ou de transformations de code.

Warning

Maintenez les points de terminaison des hooks derrière une boucle locale (loopback), un tailnet ou un proxy inverse de confiance.

• Utilisez un jeton de hook dédié ; ne réutilisez pas les jetons d’authentification de la Gateway.
• Gardez hooks.path sur un sous-chemin dédié ; / est rejeté.
• Définissez hooks.allowedAgentIds pour limiter l’agent effectif qu’un hook peut cibler, y compris l’agent par défaut lorsque agentId est omis.
• Conservez hooks.allowRequestSessionKey=false sauf si vous nécessitez des sessions sélectionnées par l’appelant.
• Si vous activez hooks.allowRequestSessionKey, définissez également hooks.allowedSessionKeyPrefixes pour contraindre les formes de clés de session autorisées.
• Les charges utiles des hooks sont enveloppées avec des limites de sécurité par défaut.

Intégration Gmail PubSub

Connectez les déclencheurs de boîte de réception Gmail à OpenClaw via Google PubSub.

Note

Prérequis :

gcloud

CLI CLI,

gog

OpenClawTailscale (gogcli), hooks OpenClaw activés, Tailscale pour le point de terminaison HTTPS public.

Configuration via l’assistant (recommandé)

openclaw webhooks gmail setup --account [email protected]

Cela écrit la configuration hooks.gmailTailscale, active le préréglage Gmail et utilise Tailscale Funnel pour le point de terminaison push.

Démarrage automatique de la Gateway

Lorsque hooks.enabled=true et hooks.gmail.accountGateway sont définis, la Gateway démarre gog gmail watch serve au démarrage et renouvelle automatiquement la surveillance. Définissez OPENCLAW_SKIP_GMAIL_WATCHER=1 pour désactiver.

Configuration manuelle unique

1. GCPSélectionnez le projet GCP

   Sélectionnez le projet GCP qui possède le client OAuth utilisé par gog :

   gcloud auth login
   gcloud config set project

   gcloud services enable gmail.googleapis.com pubsub.googleapis.com

2. Créer le sujet et accorder l'accès push Gmail

   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

3. Démarrer la surveillance

   gog gmail watch start \
     --account [email protected] \
     --label INBOX \
     --topic projects/

   /topics/gog-gmail-watch ```

Remplacement du modèle Gmail

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

Gestion des tâches

# List all jobs
openclaw cron list

# Get one stored job as JSON
openclaw cron get <jobId>

# 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>

# Force run a job now and wait for its terminal status
openclaw cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s

# Run only if due
openclaw cron run <jobId> --due

# View run history
openclaw cron runs --id <jobId> --limit 50

# View one exact run
openclaw cron runs --id <jobId> --run-id <runId>

# Delete a job
openclaw cron remove <jobId>

# Agent selection (multi-agent setups)
openclaw cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
openclaw cron edit <jobId> --clear-agent

openclaw cron run <jobId> renvoie après avoir mis en file d’attente l’exécution manuelle. Utilisez --wait pour les hooks d’arrêt, les scripts de maintenance ou d’autres automatisations qui doivent bloquer jusqu’à ce que l’exécution en file d’attente soit terminée. Le mode d’attente interroge le runId exact renvoyé ; il quitte avec 0 pour le statut ok et une valeur non nulle pour error, skipped, ou un délai d’attente dépassé.

openclaw cron create est un alias pour openclaw cron add, et les nouvelles tâches peuvent utiliser un planning positionnel ("0 9 * * 1", "every 1h", "20m", ou un horodatage ISO) suivi d’un invite d’agent positionnel. Utilisez --webhook <url> sur cron add|create ou cron edit pour envoyer (POST) la charge utile de l’exécution terminée à un point de terminaison HTTP. La livraison par webhook ne peut pas être combinée avec les drapeaux de livraison par chat tels que --announce, --channel, --to, --thread-id, ou --account.

Note

Remarque sur la substitution de modèle :

• openclaw cron add|edit --model ... modifie le modèle sélectionné pour la tâche.
• Si le modèle est autorisé, ce fournisseur/modèle exact atteint l’exécution de l’agent isolé.
• S’il n’est pas autorisé ou ne peut pas être résolu, cron fait échouer l’exécution avec une erreur de validation explicite.
• Les chaînes de repli configurées s’appliquent toujours car cron --model est un primaire de tâche, et non une substitution de session /model.
• La charge utile fallbacks remplace les replis configurés pour cette tâche ; fallbacks: [] désactive le repli et rend l’exécution stricte.
• Un --model simple sans liste de repli explicite ou configurée ne revient pas au primaire de l’agent comme cible de réessai supplémentaire silencieux.

Configuration

{
  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 limite à la fois l’expédition cron planifiée et l’exécution du tour d’agent isolé, et est par défaut de 8. Les tours d’agent cron isolés utilisent en interne la file d’exécution dédiée cron-nested de la file d’attente, donc augmenter cette valeur permet aux exécutions cron LLM indépendantes de progresser en parallèle au lieu de simplement démarrer leurs wrappers cron externes. La voie partagée non-cron nested n’est pas élargie par ce paramètre.

cron.store est une clé de stockage logique et un chemin d’importation hérité du docteur. Exécutez openclaw doctor --fix pour importer les magasins JSON existants dans SQLite et les archiver ; les futures modifications cron doivent passer par le CLI ou l’Gateway du API.

Désactiver le cron : cron.enabled: false ou OPENCLAW_SKIP_CRON=1.

Comportement de nouvelle tentative

Nouvelle tentative ponctuelle : les erreurs transitoires (limite de débit, surcharge, réseau, erreur serveur) sont réessayées jusqu’à 3 fois avec un décalage exponentiel. Les erreurs permanentes désactivent immédiatement.

Nouvelle tentative récurrente : décalage exponentiel (30s à 60m) entre les tentatives. Le décalage est réinitialisé après la prochaine exécution réussie.

Maintenance

cron.sessionRetention (par défaut 24h) nettoie les entrées de session d’exécution isolées. cron.runLog.keepLines limite les lignes d’historique d’exécution SQLite conservées par tâche ; maxBytes est conservé pour la compatibilité de configuration avec les anciens journaux d’exécution basés sur des fichiers.

Dépannage

Échelle de commande

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

Cron not firing

• Vérifiez les env var cron.enabled et OPENCLAW_SKIP_CRON.
• Confirmez que le Gateway fonctionne en continu.
• Pour les planifications cron, vérifiez le fuseau horaire (--tz) par rapport au fuseau horaire de l’hôte.
• reason: not-due dans la sortie d’exécution signifie qu’une exécution manuelle a été vérifiée avec `openclaw cron run

—due` et que la tâche n’était pas encore due.

Cron fired but no delivery

• Le mode de livraison none signifie qu’aucun envoi de secours par le runner n’est attendu. L’agent peut toujours envoyer directement avec l’outil message lorsqu’une route de chat est disponible.
• La cible de livraison manquante/invalid (channel/to) signifie que l’envoi sortant a été ignoré.
• Pour Matrix, les tâches copiées ou héritées avec des ID de salle delivery.to en minuscules peuvent échouer car les ID de salle Matrix sont sensibles à la casse. Modifiez la tâche avec la valeur exacte !room:server ou room:!room:server de Matrix.
• Les erreurs d’auth de channel (unauthorized, Forbidden) signifient que la livraison a été bloquée par les informations d’identification.
• Si l’exécution isolée ne renvoie que le jeton silencieux (NO_REPLY / no_reply), OpenClaw supprime la livraison sortante directe et supprime également le chemin de résumé mis en file d’attente de secours, donc rien n’est renvoyé au chat.
• Si l’agent doit envoyer un message à l’utilisateur lui-même, vérifiez que la tâche a une route utilisable (channel: "last" avec un chat précédent, ou un channel/cible explicite).

Cron or heartbeat appears to prevent /new-style rollover

• La fraîcheur de la réinitialisation quotidienne et inactive n’est pas basée sur updatedAt ; voir Session management.
• Les réveils Cron, les exécutions de heartbeat, les notifications d’exécution et la tenue de livre de la passerelle peuvent mettre à jour la ligne de session pour le routage/le statut, mais ils n’étendent pas sessionStartedAt ou lastInteractionAt.
• Pour les lignes héritées créées avant l’existence de ces champs, OpenClaw peut récupérer sessionStartedAt à partir de l’en-tête de session JSONL de la transcription lorsque le fichier est toujours disponible. Les lignes inactives héritées sans lastInteractionAt utilisent cette heure de début récupérée comme ligne de base inactive.

Pièges de fuseau horaire

• Cron sans --tz utilise le fuseau horaire de l’hôte de la passerelle.
• Les planifications at sans fuseau horaire sont traitées comme UTC.
• Le activeHours de Heartbeat utilise la résolution de fuseau horaire configurée.

Connexes

• Automatisation — tous les mécanismes d’automatisation en un coup d’œil
• Tâches d’arrière-plan — registre des tâches pour les exécutions cron
• Heartbeat — tours de session principale périodiques
• Fuseau horaire — configuration du fuseau horaire