7.7 KiB
summary, read_when, title
| summary | read_when | title | |||
|---|---|---|---|---|---|
| Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow |
|
Automation and tasks |
OpenClaw runs work in the background through tasks, scheduled jobs, inferred commitments, event hooks, and standing instructions. This page helps you choose the right mechanism and understand how they fit together.
Quick decision guide
flowchart TD
START([What do you need?]) --> Q1{Schedule work?}
START --> Q2{Track detached work?}
START --> Q3{Orchestrate multi-step flows?}
START --> Q4{React to lifecycle events?}
START --> Q5{Give the agent persistent instructions?}
START --> Q6{Remember a natural follow-up?}
Q1 -->|Yes| Q1a{Exact timing or flexible?}
Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
Q1a -->|Flexible| HEARTBEAT[Heartbeat]
Q2 -->|Yes| TASKS[Background Tasks]
Q3 -->|Yes| FLOW[Task Flow]
Q4 -->|Yes| HOOKS[Hooks]
Q5 -->|Yes| SO[Standing Orders]
Q6 -->|Yes| COMMITMENTS[Inferred Commitments]
| Use case | Recommended | Why |
|---|---|---|
| Send daily report at 9 AM sharp | Scheduled Tasks (Cron) | Exact timing, isolated execution |
| Remind me in 20 minutes | Scheduled Tasks (Cron) | One-shot with precise timing (--at) |
| Run weekly deep analysis | Scheduled Tasks (Cron) | Standalone task, can use different model |
| Check inbox every 30 min | Heartbeat | Batches with other checks, context-aware |
| Monitor calendar for upcoming events | Heartbeat | Natural fit for periodic awareness |
| Check in after a mentioned interview | Inferred Commitments | Memory-like follow-up, no exact reminder request |
| Gentle care check-in after user context | Inferred Commitments | Scoped to the same agent and channel |
| Inspect status of a subagent or ACP run | Background Tasks | Tasks ledger tracks all detached work |
| Audit what ran and when | Background Tasks | openclaw tasks list and openclaw tasks audit |
| Multi-step research then summarize | Task Flow | Durable orchestration with revision tracking |
| Run a script on session reset | Hooks | Event-driven, fires on lifecycle events |
| Execute code on every tool call | Plugin hooks | In-process hooks can intercept tool calls |
| Always check compliance before replying | Standing Orders | Injected into every session automatically |
Scheduled Tasks (Cron) vs Heartbeat
| Dimension | Scheduled Tasks (Cron) | Heartbeat |
|---|---|---|
| Timing | Exact (cron expressions, one-shot) | Approximate (default every 30 min) |
| Session context | Fresh (isolated) or shared | Full main-session context |
| Task records | Always created | Never created |
| Delivery | Channel, webhook, or silent | Inline in main session |
| Best for | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
Core concepts
Scheduled tasks (cron)
Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
See Scheduled Tasks.
Tasks
The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use openclaw tasks list and openclaw tasks audit to inspect them.
See Background Tasks.
Inferred commitments
Commitments are opt-in, short-lived follow-up memories. OpenClaw infers them from normal conversations, scopes them to the same agent and channel, and delivers due check-ins through heartbeat. Exact user-requested reminders still belong to cron.
See Inferred Commitments.
Task Flow
Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and openclaw tasks flow list|show|cancel for inspection.
See Task Flow.
Standing orders
Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically AGENTS.md) and are injected into every session. Combine with cron for time-based enforcement.
See Standing Orders.
Hooks
Internal hooks are event-driven scripts triggered by agent lifecycle events
(/new, /reset, /stop), session compaction, gateway startup, and message
flow. They are automatically discovered from directories and can be managed
with openclaw hooks. For in-process tool-call interception, use
Plugin hooks.
See Hooks.
Heartbeat
Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Use HEARTBEAT.md for a small checklist, or a tasks: block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as empty-heartbeat-file; due-only task mode skips as no-tasks-due. Heartbeats defer while cron work is active or queued, and heartbeat.skipWhenBusy can also defer them while subagent or nested lanes are busy.
See Heartbeat.
How they work together
- Cron handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
- Heartbeat handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
- Hooks react to specific events (session resets, compaction, message flow) with custom scripts. Plugin hooks cover tool calls.
- Standing orders give the agent persistent context and authority boundaries.
- Task Flow coordinates multi-step flows above individual tasks.
- Tasks automatically track all detached work so you can inspect and audit it.
Related
- Scheduled Tasks — precise scheduling and one-shot reminders
- Inferred Commitments — memory-like follow-up check-ins
- Background Tasks — task ledger for all detached work
- Task Flow — durable multi-step flow orchestration
- Hooks — event-driven lifecycle scripts
- Plugin hooks — in-process tool, prompt, message, and lifecycle hooks
- Standing Orders — persistent agent instructions
- Heartbeat — periodic main-session turns
- Configuration Reference — all config keys