Background Tasks & Durable Work

OpenClaw gives you several ways to run work outside the current chat turn. That is useful, but it also creates a common beginner mess: people mix up shell execution, background monitoring, and durable tracking as if they were the same thing.

They are not. A helpful mental model is this: exec is the engine starter, process is the dashboard, and tasks are the flight recorder. If you confuse those layers, long-running work gets brittle fast.

According to the current official OpenClaw docs, tasks are records, not schedulers. They track detached work like cron executions, subagent spawns, ACP runs, and CLI operations. Separate docs for background exec explain that exec runs shell commands and process manages live background sessions that stay in memory, not on disk.

What durable work actually means

Durable work is work you can trust to remain understandable after time passes, output scrolls away, or the gateway restarts. That does not always mean the same thing as "the command kept running." Sometimes durability means you still have the record. Sometimes it means the workflow can resume. Sometimes it means the right person gets notified when the job ends.

The clean separation looks like this:

• exec: starts a shell command now
• process: watches or steers that live background session
• tasks: record detached work as an auditable activity ledger
• TaskFlow: coordinates durable multi-step flows above individual tasks

That stack is less like one tool and more like a relay team. One runner starts the race, another keeps eyes on the lane, and another keeps the official result.

exec vs process vs tasks

This is the comparison most people need first.

The official background-process page makes one limitation very explicit: background process sessions are kept in memory and are lost on process restart. That is the kind of detail people skip, then rediscover the hard way.

When to wait, when to poll, and when to announce

Most durable-work mistakes are timing mistakes. People either wait too long in the foreground, poll too aggressively, or build fake reminder loops that should have been cron jobs.

Wait in the foreground

Stay in the foreground when the command is short, the result is needed immediately, and the user is actively waiting. A quick test run or a small file check belongs here.

Use process to poll on demand

Use process when the job already started and you need to inspect logs, recover an interactive session, confirm a quiet success, or intervene in a running command. Polling is for visibility, not scheduling.

Announce through task completion or session wake

The tasks docs describe a push-based model. Detached work can wake the requester session or deliver a completion notification when it finishes. That means the healthy default is usually: start once, then let the runtime surface the outcome. Repeated manual polling is mostly for debugging.

The durability ladder

Here is the practical ladder from least durable to most structured:

1. a foreground command that returns immediately
2. a background exec session you can still inspect with process
3. a detached task record you can list, audit, cancel, and inspect later
4. a TaskFlow run when several tasks must stay coordinated over time

If your only plan is "I hope I remember which terminal output mattered," you are still on rung one.

Common failure modes

Confusing tasks with schedulers

Tasks tell you what happened. They do not decide when something should start. If the work needs exact timing, use cron. If it needs approximate ongoing awareness, use heartbeat. If it needs an audit trail after it starts, tasks matter.

Polling in loops because nothing else feels safe

The official docs are blunt here. Poll on demand. Do not turn polling into a stand-in for real scheduling. If you need work later, use cron. If you need the completion event, rely on the wake or notification path.

Restart blindness

A background shell session can be alive one minute and gone from memory after a restart. If you treat process logs as permanent evidence, you are trusting the wrong layer. Durable tracking lives in tasks, not in a lucky surviving buffer.

Rerunning a command instead of inspecting the existing one

This is a quiet cost leak. Someone starts a build, gets impatient, runs it again, and now there are two long jobs competing for the same resources. Start once. Inspect the session you already have. Do not create confusion just to feel active.

Using sleep loops as fake reminders

If the work should happen later, do not keep a shell process open with a delay loop. That is fragile, noisy, and harder to recover. OpenClaw already has cron for future work.

Example shape: long build with clean follow-up

The official background-process docs show the intended shape clearly: start the long job once, then check it through process if needed.

// start now, auto-background after a short wait
{ "tool": "exec", "command": "npm run build", "yieldMs": 1000 }

// later, inspect completion or new output
{ "tool": "process", "action": "poll", "sessionId": "<id>" }

That pattern is boring in a good way. It avoids duplicate starts, preserves a clear session handle, and keeps the main chat responsive.

Where tasks become the source of truth

If the work is detached enough that you care about history, statuses, or operator inspection, tasks become the better truth layer. The current tasks docs list explicit lifecycle states such as queued, running, succeeded, failed, timed_out, cancelled, and lost.

That matters because durable operations are rarely just about raw output. They are about knowing whether the job finished, who owns it, whether it timed out, and whether recovery should happen automatically or manually.

How to think about durability without overengineering

Not every long task needs TaskFlow. Not every shell command needs a task audit. The trick is to match the mechanism to the risk.

• Need one immediate command? Use exec.
• Need to watch a running shell session? Use process.
• Need an auditable detached run? Lean on tasks.
• Need several dependent background stages? Move up to TaskFlow.

Think of it like packing for weather. You do not wear a winter coat to check the mailbox, but you also do not hike a mountain in a T-shirt just because the driveway was fine yesterday.

Operational habits that keep detached work sane

• Start long work once, not repeatedly
• Use yieldMs or background mode intentionally
• Poll only when you need status, logs, or intervention
• Prefer push-based completion over nervous refresh loops
• Use cron for later work, not delayed shell hacks
• Escalate to TaskFlow when several steps need durable coordination

The practical rule of thumb

If the question is "can I start this command without blocking the chat," think exec. If the question is "how do I check or steer the live background command," think process. If the question is "what ran, what state is it in, and can I audit it later," think tasks.

That division sounds simple because it is. The complexity only appears when people force one layer to impersonate another.