Background Daemon

The daemon runs agents as persistent background processes, automatically executing queued tasks and scheduled jobs.

How It Works

The daemon combines three systems:

  1. Scheduler — Checks cron-based schedules every 60 seconds and enqueues tasks when due
  2. Queue Processor — Polls the task queue every 30 seconds and executes pending tasks through the assigned agent runtime
  3. Heartbeat + Orchestrator Service — Wakes opted-in agents on recurring intervals for heartbeat or orchestrator ticks

When a scheduled task fires, it creates a task entry in the queue. The queue processor picks it up, spins up the assigned agent, and runs it to completion.

API

Get Status

GET /api/daemon

Returns:

{
  "running": true,
  "schedulerActive": true,
  "queueLength": 2,
  "lastProcessed": "2026-02-19T10:30:00Z",
  "nextScheduled": "2026-02-19T11:00:00Z"
}

Start / Stop

POST /api/daemon
Content-Type: application/json

{ "action": "start" }

Actions: start, stop

The daemon status is shown in the sidebar as a small indicator. Click it to toggle the daemon on or off.

  • Green pulse — daemon is running
  • Gray — daemon is stopped

Auto-Start

On first load, if there are queued tasks waiting, the daemon starts automatically. You can disable this in Settings.

Task Lifecycle

  1. Scheduled — Cron expression matches, task is created with status queued
  2. Queued — Daemon picks up the task, sets status to running
  3. Running — Agent processes the task, using its configured tools
  4. Completed — Agent finishes, result is saved, status set to completed
  5. Failed — If the agent errors out, status is set to failed with the error message

Health Monitor

The daemon also runs recurring health checks for long-running chats.

  • Detects stale heartbeat chats
  • Can auto-disable heartbeats for chats that remain stale for extended periods
  • Wakes orchestrator-enabled agents on their configured interval when they are eligible and inside the active window
  • Can emit in-app/system notifications for degraded runtime state

OpenClaw Gateway Health Checks

When OpenClaw agents are configured, the daemon proactively monitors gateway reachability:

  • Probes each OpenClaw gateway endpoint every health check cycle (2 minutes)
  • Treats websocket gateway reachability as the primary health signal and records HTTP /v1 compatibility warnings separately when exposed
  • On failure, automatically runs openclaw doctor --fix (up to 3 attempts)
  • After 3 failed repair attempts, enters a 5-minute cooldown before retrying
  • Emits notifications on gateway down/recovered events
  • Recovery notifications clear the error state automatically

OpenClaw Doctor API

Run openclaw doctor diagnostics via the API:

GET /api/openclaw/doctor          # read-only check
POST /api/openclaw/doctor         # { "fix": true } for auto-repair

Returns { ok, output, fixed }.

Memory Consolidation

Daemon runtime includes periodic memory maintenance and consolidation:

  • Generates rolling summaries for long-running context
  • Runs dedupe/prune cleanup cycles on a schedule
  • Helps keep agent memory useful without unbounded growth