Automation & Scheduled Tasks: Heartbeat & Cron 🟡

OpenClaw isn't just a passive Q&A bot — it can proactively execute tasks. This chapter covers two automation mechanisms: Heartbeat and Cron.

I. Heartbeat: Proactive AI

What Is Heartbeat?

Heartbeat makes the AI periodically check for tasks and take action autonomously, triggering every 30 minutes by default.

Each heartbeat, the AI:

Reads HEARTBEAT.md (if it exists)
Executes tasks per the file's instructions
If nothing needs attention, replies HEARTBEAT_OK and silences (no push to user)

HEARTBEAT.md Example

<!-- HEARTBEAT.md -->

# Assistant Task List

## Continuous Monitoring
- [ ] Check /logs/app.log for ERROR level logs
  - If found: summarize and notify user
- [ ] Check ~/Downloads for new files
  - If found: organize into appropriate directories

## Morning Tasks (first heartbeat after 9:00 AM on weekdays)
- [ ] Pull latest git changes
- [ ] Generate yesterday's work summary

## Pending
- [ ] Review PR #42 code

Heartbeat Configuration

agents:
  list:
    - id: main
      heartbeat:
        enabled: true
        every: "30m"
        prompt: |
          Check HEARTBEAT.md and complete pending tasks.
          Be concise when reporting.

Default HEARTBEAT_PROMPT:

Read HEARTBEAT.md if it exists. Follow it strictly.
Do not infer or repeat old tasks from prior chats.
If nothing needs attention, reply HEARTBEAT_OK.

II. Cron: Precise Scheduling

Three Schedule Types

// 'at': one-time execution at specific time
{ kind: 'at', at: '2024-03-15T09:00:00Z' }

// 'every': fixed interval repeat
{ kind: 'every', everyMs: 3600000 }  // every hour

// 'cron': cron expression (most flexible)
{ kind: 'cron', expr: '0 9 * * 1-5' }  // weekdays at 9:00

Payload Types

Payload Type	Description	Use Case
`agentTurn`	Trigger agent reasoning as new user message	Make AI complete a task
`systemEvent`	Inject system event (no AI reasoning)	Trigger hooks or internal logic

Delivery Strategies

Mode	Description
`none`	Silent execution, no user notification
`announce`	Push result to associated session on completion
`webhook`	Push result to specified webhook URL

cron:
  jobs:
    - name: daily-report
      schedule:
        kind: cron
        expr: "0 9 * * *"    # daily at 9:00
      payload:
        kind: agentTurn
        message: "Generate today's work plan summary"
      delivery:
        mode: announce

III. Managing Cron via Agent Tool

Agents can manage cron jobs through conversation:

User: Check system memory every hour, alert me if over 80%

Agent calls cron tool:
cron({
  action: 'add',
  name: 'memory-check',
  schedule: { kind: 'every', everyMs: 3600000 },
  payload: {
    kind: 'agentTurn',
    message: 'Check memory usage, warn if over 80%'
  },
  delivery: { mode: 'announce' }
})

Cron tool actions: status, list, add, update, remove, run, runs, wake

Key Source Files

File	Size	Role
`src/auto-reply/heartbeat.ts`	172 lines	Heartbeat logic
`src/agents/tools/cron-tool.ts`	739 lines	Cron agent tool
`src/tasks/task-registry.ts`	57KB	Task state machine
`src/tasks/task-executor.ts`	18KB	Task executor

Summary

Heartbeat = proactive checking: reads HEARTBEAT.md, executes tasks, silences if nothing to do.
HEARTBEAT_OK mechanism: AI returns special token when idle, framework filters it out silently.
Cron supports 3 schedules: at (time point), every (interval), cron (expression).
Two payload types: agentTurn (AI reasoning) and systemEvent (system trigger).
Agent manages cron via conversation: no config file editing needed.

← Agent Scope & Context | → Write a Channel Plugin