Dreaming: Background Processing

Most AI agent interactions follow a simple pattern: you ask something, the agent responds, and the conversation moves forward. But what happens when you need the agent to work on something that takes hours? Researching a topic, analyzing a large dataset, or running a complex simulation? This is where Dreaming comes in.

Dreaming is OpenClaw's experimental background processing feature. It allows your agent to continue working on tasks after you have moved on, notifying you when results are ready. Think of it as giving your agent the ability to "sleep on it" and wake up with answers.

What is Dreaming?

Dreaming enables asynchronous task execution in OpenClaw. When you assign a task that supports background processing, the agent can continue working on it independently of the main conversation thread. You can start new conversations, work on other things, and the dreaming task continues in the background.

Key capabilities

• Background execution: Tasks continue running even when you are not actively chatting
• Non-blocking: Your main conversation remains responsive while work continues
• Progress updates: Optional status reports on long-running tasks
• Result notification: Get notified when background tasks complete
• Resource management: Configurable limits on concurrent dreaming tasks

How it works

When a dreaming task is initiated:

1. The agent forks a background process with its own context
2. The main conversation continues normally
3. The background process executes the assigned task
4. Upon completion, results are stored or delivered based on configuration
5. You receive a notification (if configured) or see results in your next interaction

When to use Dreaming

Dreaming is ideal for specific types of tasks. Understanding when to use it helps you build more efficient agent workflows.

Good use cases

• Research tasks: Gathering information from multiple sources over time
• Data analysis: Processing large datasets that take significant time
• Content generation: Writing long-form content, reports, or documentation
• Code review: Analyzing large codebases for patterns or issues
• Monitoring: Watching for specific events or changes over time
• Simulations: Running models or calculations that need time to complete

When NOT to use Dreaming

• Quick tasks: Anything that completes in under a minute wastes overhead
• Interactive work: Tasks requiring frequent clarification or decisions
• High-priority items: Time-sensitive tasks that need immediate attention
• Simple lookups: Basic information retrieval is faster synchronously

Configuration

Dreaming requires specific setup in your OpenClaw configuration. Here is how to enable and configure it.

Enabling Dreaming

Add dreaming configuration to your gateway or agent configuration:

// In your OpenClaw config or gateway settings
{
  "dreaming": {
    "enabled": true,
    "maxConcurrentTasks": 3,
    "defaultTimeout": "2h",
    "notifyOnComplete": true,
    "storeResultsInMemory": true
  }
}

Configuration options

• enabled: Turn dreaming on or off globally
• maxConcurrentTasks: Maximum number of background tasks running simultaneously
• defaultTimeout: Default maximum duration for dreaming tasks
• notifyOnComplete: Whether to send notifications when tasks finish
• storeResultsInMemory: Save results to MEMORY.md for persistence

Per-task overrides

You can override defaults for individual tasks:

// Example: Starting a dreaming task with custom settings
Research the history of machine learning from 1950 to 2020.
Use dreaming mode with 4-hour timeout and notify me when done.

Using Dreaming in practice

Here is how to effectively use Dreaming in your daily workflows.

Starting a dreaming task

Simply ask the agent to work on something in the background:

// User request
Can you analyze our last 6 months of sales data and identify trends?
Please run this as a background task since it might take a while.

// Agent response
I'll start analyzing your sales data in dreaming mode.
This may take 30-60 minutes depending on data size.
I'll notify you when the analysis is complete.

[Dreaming task started: sales-trend-analysis-2024]

Checking task status

You can check on running dreaming tasks:

// User request
What is the status of my dreaming tasks?

// Agent response
You have 2 dreaming tasks running:

1. sales-trend-analysis-2024
   Status: 65% complete
   Started: 20 minutes ago
   ETA: ~15 minutes

2. competitor-research-project
   Status: Processing
   Started: 5 minutes ago
   ETA: ~45 minutes

Receiving results

When a task completes, you will receive results based on your configuration:

// Notification (if enabled)
Dreaming task complete: sales-trend-analysis-2024

Key findings:
- Revenue increased 23% over 6 months
- Q4 showed strongest growth (34%)
- Top performing product: Enterprise Plan
- Recommended action: Increase marketing spend

Full report saved to MEMORY.md

Limitations and considerations

Dreaming is powerful but has important limitations to understand.

Resource constraints

Each dreaming task consumes:

• Memory for maintaining task context
• API quota for ongoing processing
• Potentially disk space for intermediate results

Monitor your resource usage. Running too many concurrent dreaming tasks can impact overall system performance.

Context isolation

Dreaming tasks run with the context available at the time of creation. They do not automatically see new information from subsequent conversations. If the task needs updated context, you may need to restart it.

Error handling

Background tasks can fail silently if not configured properly. Always:

• Set reasonable timeouts
• Enable notifications for failures
• Check task status periodically for long-running work
• Store important results to persistent files

Cost implications

Background tasks consume API tokens just like foreground tasks. Long-running dreaming processes can accumulate significant costs. Set budgets and monitor usage, especially when experimenting.

Best practices

Follow these practices to get the most from Dreaming.

Start small

Begin with short, well-defined tasks to understand how Dreaming behaves in your setup. Gradually increase complexity as you become comfortable.

Define clear outputs

Always specify what you want the dreaming task to produce:

// Good: Clear output specification
Analyze customer feedback from last quarter.
Create a summary with:
- Top 5 complaints
- Top 5 compliments
- 3 actionable recommendations
Save results to MEMORY.md under #customer-feedback-q4

// Less effective: Vague request
Look at customer feedback and tell me what you find.

Use with subagents

Combine Dreaming with subagents for powerful workflows. A dreaming task can spawn subagents for parallel processing, then compile results when all complete.

Document your tasks

Keep track of what you have running in the background. Consider maintaining a dreaming task log in MEMORY.md:

// In MEMORY.md
# Active Dreaming Tasks

- sales-trend-analysis-2024 (started: 2024-01-15, ETA: 30min)
- competitor-research-project (started: 2024-01-15, ETA: 1hr)

# Completed Dreaming Tasks

- website-seo-audit (completed: 2024-01-14, results: #seo-audit-results)

Troubleshooting

Common issues and their solutions.

Task not starting

• Verify Dreaming is enabled in configuration
• Check if you have reached maxConcurrentTasks limit
• Ensure the task type supports background execution
• Review gateway logs for errors

Task appears stuck

• Check if the task is actually still running or has failed
• Verify API connectivity and quota availability
• Review timeout settings - the task may be waiting for resources
• Consider canceling and restarting with clearer instructions

Missing results

• Check if storeResultsInMemory is enabled
• Verify notification settings
• Look in the agent's workspace for output files
• Ask the agent to list recent dreaming task results

Summary

Dreaming extends OpenClaw's capabilities by enabling true asynchronous processing. It is ideal for research, analysis, and any task that benefits from running independently while you focus on other work.

Start with simple tasks, monitor resource usage, and gradually build more complex background workflows. Combined with subagents and proper memory management, Dreaming helps you build AI systems that work around the clock.