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.
This commit is contained in:
Tyler Yust
committed by
Peter Steinberger
Peter Steinberger
parent
511c656cbc
commit
0bb0dfc9bc
@@ -23,7 +23,7 @@ cron is the mechanism.
|
||||
- Jobs persist under `~/.openclaw/cron/` so restarts don’t lose schedules.
|
||||
- Two execution styles:
|
||||
- **Main session**: enqueue a system event, then run on the next heartbeat.
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with a delivery mode (legacy summary, announce, full output, or none).
|
||||
- **Isolated**: run a dedicated agent turn in `cron:<jobId>`, with delivery (announce by default, full output or none; legacy main summary still supported).
|
||||
- Wakeups are first-class: a job can request “wake now” vs “next heartbeat”.
|
||||
|
||||
## Quick start (actionable)
|
||||
@@ -108,7 +108,7 @@ Jobs can optionally auto-delete after a successful one-shot run via `deleteAfter
|
||||
|
||||
Cron supports three schedule kinds:
|
||||
|
||||
- `at`: one-shot timestamp (ms since epoch). Gateway accepts ISO 8601 and coerces to UTC.
|
||||
- `at`: one-shot timestamp. Prefer ISO 8601 via `schedule.at`; `atMs` (epoch ms) is also accepted.
|
||||
- `every`: fixed interval (ms).
|
||||
- `cron`: 5-field cron expression with optional IANA timezone.
|
||||
|
||||
@@ -136,12 +136,13 @@ Key behaviors:
|
||||
|
||||
- Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
|
||||
- Each run starts a **fresh session id** (no prior conversation carry-over).
|
||||
- Legacy behavior (no `delivery` field): a summary is posted to the main session (prefix `Cron`, configurable).
|
||||
- Default behavior: if `delivery` is omitted, isolated jobs announce a summary immediately (`delivery.mode = "announce"`), unless legacy isolation settings or legacy payload delivery fields are provided.
|
||||
- Legacy behavior: jobs with legacy isolation settings, legacy payload delivery fields, or older stored jobs without `delivery` post a summary to the main session (prefix `Cron`, configurable).
|
||||
- `delivery.mode` (isolated-only) chooses what happens instead of the legacy summary:
|
||||
- `announce`: subagent-style summary delivered immediately to a chat.
|
||||
- `deliver`: full agent output delivered immediately to a chat.
|
||||
- `none`: internal only (no main summary, no delivery).
|
||||
- `wakeMode: "now"` triggers an immediate heartbeat after posting the **legacy** summary.
|
||||
- `wakeMode: "now"` only triggers an immediate heartbeat when using the legacy main-summary path.
|
||||
|
||||
Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
|
||||
your main chat history.
|
||||
@@ -166,6 +167,9 @@ Delivery config (isolated jobs only):
|
||||
- `delivery.to`: channel-specific target (phone/chat/channel id).
|
||||
- `delivery.bestEffort`: avoid failing the job if delivery fails (deliver mode).
|
||||
|
||||
If `delivery` is omitted for isolated jobs, OpenClaw defaults to `announce` unless legacy isolation
|
||||
settings are present.
|
||||
|
||||
Legacy delivery fields (still accepted when `delivery` is omitted):
|
||||
|
||||
- `payload.deliver`: `true` to send output to a channel target.
|
||||
@@ -179,7 +183,7 @@ Isolation options (only for `session=isolated`):
|
||||
- `postToMainMode`: `summary` (default) or `full`.
|
||||
- `postToMainMaxChars`: max chars when `postToMainMode=full` (default 8000).
|
||||
|
||||
Note: isolation post-to-main settings apply to legacy jobs (no `delivery` field). If `delivery` is set, the legacy summary is skipped.
|
||||
Note: setting isolation post-to-main options opts into the legacy main-summary path (no `delivery` field). If `delivery` is set, the legacy summary is skipped.
|
||||
|
||||
### Model and thinking overrides
|
||||
|
||||
@@ -211,7 +215,7 @@ Delivery config is only valid for isolated jobs (`sessionTarget: "isolated"`).
|
||||
If `delivery.channel` or `delivery.to` is omitted, cron can fall back to the main session’s
|
||||
“last route” (the last place the agent replied).
|
||||
|
||||
Legacy behavior (no `delivery` field):
|
||||
Legacy behavior (no `delivery` field with legacy isolation settings or older jobs):
|
||||
|
||||
- If `payload.to` is set, cron auto-delivers the agent’s final output even if `payload.deliver` is omitted.
|
||||
- Use `payload.deliver: true` when you want last-route delivery without an explicit `to`.
|
||||
@@ -240,8 +244,8 @@ Prefixed targets like `telegram:...` / `telegram:group:...` are also accepted:
|
||||
## JSON schema for tool calls
|
||||
|
||||
Use these shapes when calling Gateway `cron.*` tools directly (agent tool calls or RPC).
|
||||
CLI flags accept human durations like `20m`, but tool calls use epoch milliseconds for
|
||||
`atMs` and `everyMs` (ISO timestamps are accepted for `at` times).
|
||||
CLI flags accept human durations like `20m`, but tool calls should use an ISO 8601 string
|
||||
for `schedule.at` (preferred) or epoch milliseconds for `atMs` and `everyMs`.
|
||||
|
||||
### cron.add params
|
||||
|
||||
@@ -250,7 +254,7 @@ One-shot, main session job (system event):
|
||||
```json
|
||||
{
|
||||
"name": "Reminder",
|
||||
"schedule": { "kind": "at", "atMs": 1738262400000 },
|
||||
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
|
||||
"sessionTarget": "main",
|
||||
"wakeMode": "now",
|
||||
"payload": { "kind": "systemEvent", "text": "Reminder text" },
|
||||
@@ -281,7 +285,8 @@ Recurring, isolated job with delivery:
|
||||
|
||||
Notes:
|
||||
|
||||
- `schedule.kind`: `at` (`atMs`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `schedule.kind`: `at` (`at` or `atMs`), `every` (`everyMs`), or `cron` (`expr`, optional `tz`).
|
||||
- `schedule.at` accepts ISO 8601 (timezone optional; treated as UTC when omitted).
|
||||
- `atMs` and `everyMs` are epoch milliseconds.
|
||||
- `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
|
||||
- Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun`, `delivery`, `isolation`.
|
||||
|
||||
@@ -90,7 +90,7 @@ Cron jobs run at **exact times** and can run in isolated sessions without affect
|
||||
- **Exact timing**: 5-field cron expressions with timezone support.
|
||||
- **Session isolation**: Runs in `cron:<jobId>` without polluting main history.
|
||||
- **Model overrides**: Use a cheaper or more powerful model per job.
|
||||
- **Delivery control**: Choose `announce` (summary), `deliver` (full output), or `none`. Legacy jobs still post a summary to main by default.
|
||||
- **Delivery control**: Isolated jobs default to `announce` (summary); choose `deliver` (full output) or `none` as needed. Legacy jobs still post a summary to main.
|
||||
- **Immediate delivery**: Announce/deliver modes post directly without waiting for heartbeat.
|
||||
- **No agent context needed**: Runs even if main session is idle or compacted.
|
||||
- **One-shot support**: `--at` for precise future timestamps.
|
||||
@@ -215,13 +215,13 @@ See [Lobster](/tools/lobster) for full usage and examples.
|
||||
|
||||
Both heartbeat and cron can interact with the main session, but differently:
|
||||
|
||||
| | Heartbeat | Cron (main) | Cron (isolated) |
|
||||
| ------- | ------------------------------- | ------------------------ | ---------------------- |
|
||||
| Session | Main | Main (via system event) | `cron:<jobId>` |
|
||||
| History | Shared | Shared | Fresh each run |
|
||||
| Context | Full | Full | None (starts clean) |
|
||||
| Model | Main session model | Main session model | Can override |
|
||||
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Summary posted to main |
|
||||
| | Heartbeat | Cron (main) | Cron (isolated) |
|
||||
| ------- | ------------------------------- | ------------------------ | -------------------------- |
|
||||
| Session | Main | Main (via system event) | `cron:<jobId>` |
|
||||
| History | Shared | Shared | Fresh each run |
|
||||
| Context | Full | Full | None (starts clean) |
|
||||
| Model | Main session model | Main session model | Can override |
|
||||
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default) |
|
||||
|
||||
### When to use main session cron
|
||||
|
||||
|
||||
@@ -16,6 +16,10 @@ Related:
|
||||
|
||||
Tip: run `openclaw cron --help` for the full command surface.
|
||||
|
||||
Note: isolated `cron add` jobs default to `--announce` delivery. Use `--deliver` for full output
|
||||
or `--no-deliver` to keep output internal. To opt into the legacy main-summary path, pass
|
||||
`--post-prefix` (or other `--post-*` options) without delivery flags.
|
||||
|
||||
## Common edits
|
||||
|
||||
Update delivery settings without changing the message:
|
||||
|
||||
@@ -81,7 +81,7 @@ you revoke it with `openclaw devices revoke --device <id> --role <role>`. See
|
||||
|
||||
Cron jobs panel notes:
|
||||
|
||||
- For isolated jobs, choose a delivery mode: legacy main summary, announce summary, deliver full output, or none.
|
||||
- For isolated jobs, delivery defaults to announce summary. You can switch to legacy main summary, deliver full output, or none.
|
||||
- Channel/target fields appear when announce or deliver is selected.
|
||||
|
||||
## Chat behavior
|
||||
|
||||
Reference in New Issue
Block a user