vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-02 12:51:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(tasks): clarify heartbeat, cron, and background runs

Browse Source
This commit is contained in:
Vincent Koc
2026-03-30 14:35:06 +09:00
parent 0a014ca63a
commit e624fdcf0a
3 changed files with 34 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/automation/cron-jobs.md
View File

@@ -14,6 +14,11 @@ title: "Cron Jobs"
Cron is the Gateway’s built-in scheduler. It persists jobs, wakes the agent at
the right time, and can optionally deliver output back to a chat.
Cron does **not** mean every scheduled event becomes a background task:
- `sessionTarget: "main"` schedules a system event for the main session and heartbeat flow.
- `sessionTarget: "isolated"` or `sessionTarget: "session:..."` runs detached work that shows up in `openclaw tasks`.
If you want _“run this every morning”_ or _“poke the agent in 20 minutes”_,
cron is the mechanism.
@@ -155,6 +160,8 @@ They must use `payload.kind = "systemEvent"`.
This is the best fit when you want the normal heartbeat prompt + main-session context.
See [Heartbeat](/gateway/heartbeat).
Main-session cron jobs do **not** create background task records.
#### Isolated jobs (dedicated cron sessions)
Isolated jobs run a dedicated agent turn in session `cron:<jobId>` or a custom session.
@@ -176,6 +183,8 @@ Key behaviors:
Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
your main chat history.
These detached runs appear in `openclaw tasks` and inherit task audit and maintenance behavior.
### Payload shapes (what runs)
Two payload kinds are supported:

25
docs/automation/cron-vs-heartbeat.md
View File

@@ -11,6 +11,14 @@ title: "Cron vs Heartbeat"
Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your use case.
One important distinction:
- **Heartbeat** is a scheduled **main-session turn**.
- **Cron (main)** is a scheduled **system event into the main session**.
- **Cron (isolated)** is a scheduled **background run**.
Only detached background runs show up in `openclaw tasks`. Normal heartbeat runs and main-session cron reminders do not.
## Quick Decision Guide
| Use Case | Recommended | Why |
@@ -40,6 +48,7 @@ Heartbeats run in the **main session** at a regular interval (default: 30 min).
- **Context-aware**: The agent knows what you've been working on and can prioritize accordingly.
- **Smart suppression**: If nothing needs attention, the agent replies `HEARTBEAT_OK` and no message is delivered.
- **Natural timing**: Drifts slightly based on queue load, which is fine for most monitoring.
- **No background task ledger**: heartbeat turns stay in main-session history instead of creating a separate task run.
### Heartbeat example: HEARTBEAT.md checklist
@@ -98,6 +107,7 @@ per-job offset in a 0-5 minute window.
- **Immediate delivery**: Announce mode posts 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.
- **Task visibility for detached runs**: isolated jobs show up in `openclaw tasks`, `openclaw tasks audit`, and maintenance surfaces.
### Cron example: Daily morning briefing
@@ -219,13 +229,14 @@ 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>` or custom session |
| History | Shared | Shared | Fresh each run (isolated) / Persistent (custom) |
| Context | Full | Full | None (isolated) / Cumulative (custom) |
| Model | Main session model | Main session model | Can override |
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default) |
| | Heartbeat | Cron (main) | Cron (isolated) |
| -------- | ------------------------------- | ------------------------ | ----------------------------------------------- |
| Session | Main | Main (via system event) | `cron:<jobId>` or custom session |
| History | Shared | Shared | Fresh each run (isolated) / Persistent (custom) |
| Context | Full | Full | None (isolated) / Cumulative (custom) |
| Model | Main session model | Main session model | Can override |
| Output | Delivered if not `HEARTBEAT_OK` | Heartbeat prompt + event | Announce summary (default) |
| Tasks UI | No task run | No task run | Visible in `openclaw tasks` |
### When to use main session cron

7
docs/gateway/heartbeat.md
View File

@@ -13,6 +13,10 @@ title: "Heartbeat"
Heartbeat runs **periodic agent turns** in the main session so the model can
surface anything that needs attention without spamming you.
Heartbeat is not the background task executor. It is a scheduled main-session turn.
Background task records are for detached work such as ACP runs, subagents, background CLI work,
and isolated cron jobs.
Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
## Quick start (beginner)
@@ -65,6 +69,8 @@ The default prompt is intentionally broad:
occasional lightweight “anything you need?” message, but avoids night-time spam
by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).
Heartbeat can react to detached tasks, but a heartbeat run itself does not create a task record.
If you want a heartbeat to do something very specific (e.g. “check Gmail PubSub
stats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` (or
`agents.list[].heartbeat.prompt`) to a custom body (sent verbatim).
@@ -253,6 +259,7 @@ Use `accountId` to target a specific account on multi-account channels like Tele
outbound message is sent.
- Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`
is restored so idle expiry behaves normally.
- Detached work can enqueue a system event and wake heartbeat when the main session should notice something quickly. That wake still does not make the heartbeat run a background task.
## Visibility controls