Can I run background tasks on a schedule?

Yes. You can combine background tasks with the scheduled tasks feature. The scheduled trigger submits a task to the background queue, which processes it according to the queue's concurrency and priority settings.

What happens if the agent restarts during a background task?

The task queue is persistent. If the agent restarts, pending and in-progress tasks are recovered. In-progress tasks restart from the beginning unless you have intermediate checkpointing enabled, in which case they resume from the last checkpoint.

Can background tasks use different models?

Yes. You can specify a model override for background tasks that differs from the agent's default model. This is useful when background tasks require a more capable model for complex analysis while the chat interface uses a faster model.

Advanced

Long-Running Tasks: Background Processing

Set up background processing so your OpenClaw agent handles time-intensive tasks without blocking the conversation.

Deploy OpenClaw See How It Works

What You Will Get

By the end of this guide, your OpenClaw agent will offload long-running tasks to a background queue and notify users when results are ready. Tasks like large data analysis, document generation, or batch processing will run asynchronously while the agent remains responsive to other messages.

Long-running tasks are a common challenge in conversational AI. If a task takes more than a few seconds, users expect feedback rather than a frozen interface. Background processing solves this by decoupling task execution from the conversation flow.

You will configure a task queue, set up progress reporting, handle task cancellation, and deliver results through the user's preferred channel. The result is an agent that handles both quick questions and lengthy operations seamlessly.

Step-by-Step Setup

Follow these steps to enable background task processing.

Enable the Task Queue

Open your agent's settings in the RunTheAgent dashboard and navigate to the Background Tasks section. Enable the task queue and choose a concurrency level. A concurrency of 3 means the agent can process up to three background tasks simultaneously.

Define Task Triggers

In the agent's system prompt, specify which requests should become background tasks. For example, 'If the user asks for a report covering more than 7 days of data, run it as a background task.' Clear triggers prevent the agent from unnecessarily queuing short tasks.

Configure Progress Reporting

Set up periodic progress updates so users know their task is running. The agent can send a message like 'Your report is 40% complete, estimated 2 minutes remaining.' Configure the update interval based on the typical task duration.

Set Task Timeouts

Define a maximum execution time for background tasks. If a task exceeds this limit, the system cancels it and notifies the user with an explanation. This prevents runaway tasks from consuming resources indefinitely. A typical timeout is 10 minutes, but adjust for your use case.

Implement Cancellation Support

Allow users to cancel a running background task by sending a cancel command. The agent acknowledges the cancellation, stops the task, and cleans up any partial results. This gives users control over tasks that are no longer needed.

Configure Result Delivery

Choose how the agent delivers completed results. Options include sending the result directly in the chat, posting it to a connected channel, saving it to the agent's memory for later retrieval, or delivering it via a webhook. Users can also check the status of their task at any time by asking.

Test with a Simulated Long Task

Create a test task that takes at least one minute to complete. Verify that the task is queued correctly, progress updates are sent on schedule, the result is delivered properly, and cancellation works as expected. Check the task history log for accurate timing data.

Tips and Best Practices

Prioritize Tasks by Urgency

If your queue receives more tasks than it can process concurrently, implement priority levels. High-priority tasks like user-facing reports should be processed before low-priority tasks like background data syncs.

Store Intermediate Results

For tasks that take several minutes, save intermediate results periodically. If the task fails or is cancelled, you can offer the user the partial result instead of starting over from scratch.

Limit Queue Depth

Set a maximum number of pending tasks per user to prevent queue flooding. If a user submits too many tasks, the agent should inform them that their queue is full and suggest waiting for current tasks to complete.

Log Task Metrics

Track metrics like average completion time, failure rate, and queue wait time. Use these metrics to right-size your concurrency settings and identify tasks that consistently take longer than expected.

Frequently Asked Questions

Scheduled Tasks Sub-Agent Spawning Performance Optimization

Ready to get started?

Deploy your own OpenClaw instance in under 60 seconds. No VPS, no Docker, no SSH. Just your personal AI assistant, ready to work.

Deploy OpenClaw View Pricing

Starting at $24.50/mo. Everything included. 3-day money-back guarantee.