OpenClaw Background Tasks - Tracking What Your AI Agents Do When You're Not Watching

Once your AI agents start doing real work in production, you quickly hit a problem that nobody talks about in the demos. An agent kicks off a background process - maybe it spawns a subagent, triggers an ACP run, or executes as part of a cron schedule. That work runs somewhere, detached from your main conversation. So how do you know what happened? Did it finish? Did it fail? Is it still running?

This is the unglamorous but absolutely necessary side of AI agent operations. OpenClaw's background task system is the answer, and it works differently from what most people expect. Tasks in OpenClaw aren't schedulers. They don't decide when work runs. They're the activity ledger - the record of what happened, when, and whether it worked. The official documentation covers the full API, so I'll focus here on how this fits into a practical agent operations workflow.

Understanding the Split Between Scheduling and Tracking

This distinction tripped us up initially and I've seen it confuse other teams too. In OpenClaw, the mechanisms that decide when work happens are cron jobs and heartbeats. The mechanism that records what happened is the task system. They're separate concerns.

A cron job says "run this agent every morning at 8am." The task system says "the 8am run on Tuesday started at 8:00:03, ran for 47 seconds, and succeeded." A heartbeat says "check in periodically." The task system says nothing about heartbeat turns - they don't create task records at all.

This matters because if you're looking at the task list and wondering why your heartbeat activity isn't showing up, that's expected. Heartbeat turns and normal interactive chat turns are just conversations. They don't produce task records. The task system tracks detached, asynchronous work - the kind of work that runs outside your main conversation session.

What Actually Creates Tasks

Four types of operations create task records, each with its own runtime type.

ACP background runs create tasks with the acp runtime type. When you spawn a child ACP session, the task tracker picks it up and follows it through to completion. These default to a done_only notification policy, which means you get notified when they finish but not about intermediate status changes.

Subagent orchestration works similarly. When your agent spawns a subagent via sessions_spawn, a task record appears with the subagent runtime type. Same done_only default notification.

Cron jobs - every cron execution, whether it runs in the main session or an isolated session, creates a task with the cron runtime type. These default to silent notification, which makes sense because cron jobs that run on schedule every hour don't need to notify you every time. They create records for tracking but stay quiet unless something goes wrong.

CLI operations round out the set. When you run openclaw agent commands through the gateway, those create tasks too. Also silent by default.

Then there's an interesting edge case - session-backed video_generate runs. These create task records but use a slightly different completion mechanism. Instead of notifying a channel directly, they wake the original agent session so the agent can write the follow-up message and attach the finished video itself. The task system also acts as a guard rail here - if a video generation is already running in a session, calling video_generate again returns the active task status instead of starting a duplicate.

The Task Lifecycle

Every task moves through a straightforward state machine. It starts as queued (created, waiting for the agent to pick it up), moves to running (actively executing), and then reaches one of four terminal states.

succeeded is the happy path. failed means something went wrong. timed_out means it exceeded the configured timeout. cancelled means someone ran openclaw tasks cancel. And then there's lost - which is the interesting one.

A task goes to lost when its backing state disappears and doesn't come back within a five-minute grace period. What "backing state" means depends on the runtime type. For ACP tasks, it means the child session metadata is gone. For subagent tasks, the child session has disappeared from the agent store. For cron tasks, the cron runtime no longer tracks the job as active.

The five-minute grace period exists because transient disruptions happen. A gateway restart, a brief network interruption, a process that takes a moment to reconnect. If the backing state reappears within five minutes, the task doesn't transition to lost. If it doesn't, OpenClaw marks it and moves on.

In practice, lost tasks are rare but important to investigate when they occur. They usually point to infrastructure issues - a crashed process, a storage problem, or a deployment that didn't go cleanly. The openclaw tasks audit command specifically surfaces these.

Push-Based Completion - Stop Polling

One of the design decisions I appreciate about OpenClaw's task system is that completion is push-based. When a task finishes, OpenClaw notifies you. You don't need to sit in a loop checking "is it done yet?"

Notifications follow two paths. If the task has a channel target (the requesterOrigin), the completion message goes directly to that channel - Telegram, Discord, Slack, whatever you're using. For subagent completions, OpenClaw even preserves thread and topic routing when available, so the notification appears in the right conversation thread.

If direct delivery fails or there's no origin channel set, the update gets queued as a system event in the requester's session. It surfaces on the next heartbeat. And here's the nice part - task completion triggers an immediate heartbeat wake. You don't have to wait for the next scheduled heartbeat tick. The system pokes the heartbeat as soon as the task finishes.

This means the standard workflow is fire-and-forget. Start the detached work, go about your business, and the result comes to you when it's ready. The only time you should be actively polling task status is when you're debugging something or need to intervene in a running task.

Managing Tasks in Practice

The CLI is your primary interface for task management. Here's what the day-to-day looks like.

openclaw tasks list shows all tasks, newest first. You can filter by runtime type (--runtime acp) or status (--status running) to narrow things down. If you're looking for a specific task, openclaw tasks show takes a task ID, run ID, or session key and gives you the full details.

Cancellation is straightforward - openclaw tasks cancel kills the child session associated with the task. The task transitions to cancelled and you get a notification if your policy allows it.

Notification policies can be changed per-task with openclaw tasks notify. The options are:

• silent - no notifications at all, just records
• done_only - notify only when the task reaches a terminal state
• state_changes - notify on every status transition

For most production workloads, done_only is the right balance. You want to know when things finish (especially when they fail) but you don't need a notification every time a task transitions from queued to running.

openclaw tasks audit is worth running periodically. It checks for tasks that might be stuck, lost, or in an inconsistent state. Think of it as a health check for your detached work.

And openclaw tasks maintenance lets you preview or apply cleanup operations. Terminal task records are kept for seven days and then automatically pruned, but you can run maintenance manually if you want to clean up sooner.

Isolated Cron Delivery and Subagent Draining

There's a subtle behaviour worth knowing about for more complex setups. When an isolated cron run completes and it has spawned descendant subagent work, OpenClaw holds off on delivering the cron task's interim parent replies. It waits for the descendant subagent work to drain first and prefers the final descendant output when that arrives before delivery.

This prevents you from getting stale intermediate results when the real output is still being produced by a downstream subagent. In practice, this means you might notice a slight delay between a cron task transitioning to succeeded and actually receiving its output notification. That delay is the system waiting for descendants to finish and choosing the best output to deliver.

Isolated cron runs and subagent completions also do best-effort cleanup of tracked browser tabs and processes associated with their child sessions before final cleanup. It's a small detail, but it prevents resource leaks from accumulating over time in long-running deployments.

Fitting Tasks Into Your Operations

For teams running production AI agents, background tasks should be part of your monitoring setup. The task list is essentially your audit trail for all asynchronous agent work. When something goes wrong - an agent didn't produce the expected output, a scheduled process seems to have disappeared - the task records tell you what happened.

We recommend setting up a dedicated monitoring channel (in Slack or Discord or whatever your team uses) and configuring ACP and subagent tasks to deliver notifications there. Cron tasks can stay silent unless they fail, which you can detect through the audit command.

For larger deployments with many concurrent agents, the openclaw tasks flow commands become relevant - these tie into OpenClaw's Task Flow orchestration layer for multi-step workflows. But that's a separate topic; we covered it in our OpenClaw Task Flow orchestration guide.

If you're running OpenClaw agents in production and want help setting up proper task monitoring and operations workflows, our AI agent builders team works with organisations across Australia on production agent infrastructure. We also offer managed AI services for teams that want operational oversight of their agent deployments without building the ops capability in-house. And if you're earlier in the journey and still evaluating agent platforms, our agentic automations practice can help you assess whether OpenClaw fits your requirements.