docs/cli/cron.md

---
summary: "CLI reference for `openclaw cron` (schedule and run background jobs)"
read_when:
  - You want scheduled jobs and wakeups
  - You’re debugging cron execution and logs
title: "cron"
---

# `openclaw cron`

Manage cron jobs for the Gateway scheduler.

Related:

- Cron jobs: [Cron jobs](/automation/cron-jobs)

Tip: run `openclaw cron --help` for the full command surface.

Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
output internal. `--deliver` remains as a deprecated alias for `--announce`.

Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.

Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.

## Common edits

Update delivery settings without changing the message:

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

Disable delivery for an isolated job:

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

Announce to a specific channel:

```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
+								---
-												refactor: rename to openclaw

											
										
										
											2026-01-30 03:15:10 +01:00
+								summary: "CLI reference for `openclaw cron` (schedule and run background jobs)"
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
+								read_when:
 								  - You want scheduled jobs and wakeups
 								  - You’re debugging cron execution and logs
-												Docs: add nav titles across docs (#5689)


											
										
										
											2026-01-31 16:04:03 -05:00
+								title: "cron"
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
+								---
-												refactor: rename to openclaw

											
										
										
											2026-01-30 03:15:10 +01:00
+								# `openclaw cron`
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
 								Manage cron jobs for the Gateway scheduler.
 								Related:
-												chore: Run `pnpm format:fix`.

											
										
										
											2026-01-31 21:13:13 +09:00
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
+								- Cron jobs: [Cron jobs](/automation/cron-jobs)
-												refactor: rename to openclaw

											
										
										
											2026-01-30 03:15:10 +01:00
+								Tip: run `openclaw cron --help` for the full command surface.
-												docs(cli): add per-command CLI pages

											
										
										
											2026-01-15 06:12:54 +00:00
-												feat(cron): enhance delivery modes and job configuration

- Updated isolated cron jobs to support new delivery modes: `announce` and `none`, improving output management.
- Refactored job configuration to remove legacy fields and streamline delivery settings.
- Enhanced the `CronJobEditor` UI to reflect changes in delivery options, including a new segmented control for delivery mode selection.
- Updated documentation to clarify the new delivery configurations and their implications for job execution.
- Improved tests to validate the new delivery behavior and ensure backward compatibility with legacy settings.

This update provides users with greater flexibility in managing how isolated jobs deliver their outputs, enhancing overall usability and clarity in job configurations.

											
										
										
											2026-02-03 16:53:46 -08:00
+								Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
 								output internal. `--deliver` remains as a deprecated alias for `--announce`.
-												feat(cron): default isolated jobs to announce delivery and enhance scheduling options

- Updated isolated cron jobs to default to `announce` delivery mode, improving user experience.
- Enhanced scheduling options to accept ISO 8601 timestamps for `schedule.at`, while still supporting epoch milliseconds.
- Refined documentation to clarify delivery modes and scheduling formats.
- Adjusted related CLI commands and UI components to reflect these changes, ensuring consistency across the platform.
- Improved handling of legacy delivery fields for backward compatibility.

This update streamlines the configuration of isolated jobs, making it easier for users to manage job outputs and schedules.

											
										
										
											2026-02-03 14:21:38 -08:00
-												feat(cron): enhance one-shot job behavior and CLI options

- Default one-shot jobs to delete after success, improving job management.
- Introduced `--keep-after-run` CLI option to allow users to retain one-shot jobs post-execution.
- Updated documentation to clarify default behaviors and new options for one-shot jobs.
- Adjusted cron job creation logic to ensure consistent handling of delete options.
- Enhanced tests to validate new behaviors and ensure reliability.

This update streamlines the handling of one-shot jobs, providing users with more control over job persistence and execution outcomes.

											
										
										
											2026-02-03 15:00:03 -08:00
+								Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
-												fix(cron): share isolated announce flow + harden cron scheduling/delivery (#11641)

* fix(cron): comprehensive cron scheduling and delivery fixes

- Fix delivery target resolution for isolated agent cron jobs
- Improve schedule parsing and validation
- Add job retry logic and error handling
- Enhance cron ops with better state management
- Add timer improvements for more reliable cron execution
- Add cron event type to protocol schema
- Support cron events in heartbeat runner (skip empty-heartbeat check,
  use dedicated CRON_EVENT_PROMPT for relay)

* fix: remove cron debug test and add changelog/docs notes (#11641) (thanks @tyler6204)
											
										
										
											2026-02-07 19:46:01 -08:00
+								Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
-												fix: refactor cron edit payload patches

Co-authored-by: Felix Krause <869950+KrauseFx@users.noreply.github.com>

											
										
										
											2026-01-21 01:12:43 +00:00
+								## Common edits
 								Update delivery settings without changing the message:
 								```bash
-												feat(cron): introduce delivery modes for isolated jobs

- Added support for new delivery modes in cron jobs: `announce`, `deliver`, and `none`.
- Updated documentation to reflect changes in delivery options and usage examples.
- Enhanced the cron job schema to include delivery configuration.
- Refactored related CLI commands and UI components to accommodate the new delivery settings.
- Improved handling of legacy delivery fields for backward compatibility.

This update allows users to choose how output from isolated jobs is delivered, enhancing flexibility in job management.

											
										
										
											2026-02-03 13:44:29 -08:00
+								openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
-												fix: refactor cron edit payload patches

Co-authored-by: Felix Krause <869950+KrauseFx@users.noreply.github.com>

											
										
										
											2026-01-21 01:12:43 +00:00
+								```
 								Disable delivery for an isolated job:
 								```bash
-												refactor: rename to openclaw

											
										
										
											2026-01-30 03:15:10 +01:00
+								openclaw cron edit <job-id> --no-deliver
-												fix: refactor cron edit payload patches

Co-authored-by: Felix Krause <869950+KrauseFx@users.noreply.github.com>

											
										
										
											2026-01-21 01:12:43 +00:00
+								```
-												feat(cron): introduce delivery modes for isolated jobs

- Added support for new delivery modes in cron jobs: `announce`, `deliver`, and `none`.
- Updated documentation to reflect changes in delivery options and usage examples.
- Enhanced the cron job schema to include delivery configuration.
- Refactored related CLI commands and UI components to accommodate the new delivery settings.
- Improved handling of legacy delivery fields for backward compatibility.

This update allows users to choose how output from isolated jobs is delivered, enhancing flexibility in job management.

											
										
										
											2026-02-03 13:44:29 -08:00
-												feat(cron): enhance delivery modes and job configuration

- Updated isolated cron jobs to support new delivery modes: `announce` and `none`, improving output management.
- Refactored job configuration to remove legacy fields and streamline delivery settings.
- Enhanced the `CronJobEditor` UI to reflect changes in delivery options, including a new segmented control for delivery mode selection.
- Updated documentation to clarify the new delivery configurations and their implications for job execution.
- Improved tests to validate the new delivery behavior and ensure backward compatibility with legacy settings.

This update provides users with greater flexibility in managing how isolated jobs deliver their outputs, enhancing overall usability and clarity in job configurations.

											
										
										
											2026-02-03 16:53:46 -08:00
+								Announce to a specific channel:
-												feat(cron): introduce delivery modes for isolated jobs

- Added support for new delivery modes in cron jobs: `announce`, `deliver`, and `none`.
- Updated documentation to reflect changes in delivery options and usage examples.
- Enhanced the cron job schema to include delivery configuration.
- Refactored related CLI commands and UI components to accommodate the new delivery settings.
- Improved handling of legacy delivery fields for backward compatibility.

This update allows users to choose how output from isolated jobs is delivered, enhancing flexibility in job management.

											
										
										
											2026-02-03 13:44:29 -08:00
 								```bash
-												feat(cron): enhance delivery modes and job configuration

- Updated isolated cron jobs to support new delivery modes: `announce` and `none`, improving output management.
- Refactored job configuration to remove legacy fields and streamline delivery settings.
- Enhanced the `CronJobEditor` UI to reflect changes in delivery options, including a new segmented control for delivery mode selection.
- Updated documentation to clarify the new delivery configurations and their implications for job execution.
- Improved tests to validate the new delivery behavior and ensure backward compatibility with legacy settings.

This update provides users with greater flexibility in managing how isolated jobs deliver their outputs, enhancing overall usability and clarity in job configurations.

											
										
										
											2026-02-03 16:53:46 -08:00
+								openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
-												feat(cron): introduce delivery modes for isolated jobs

- Added support for new delivery modes in cron jobs: `announce`, `deliver`, and `none`.
- Updated documentation to reflect changes in delivery options and usage examples.
- Enhanced the cron job schema to include delivery configuration.
- Refactored related CLI commands and UI components to accommodate the new delivery settings.
- Improved handling of legacy delivery fields for backward compatibility.

This update allows users to choose how output from isolated jobs is delivered, enhancing flexibility in job management.

											
										
										
											2026-02-03 13:44:29 -08:00
+								```