Isolated vs Main-Session Cron

+15 Mana ✨
OpenClaw Cron Sessions(DOCUMENTATION)

Introduction

When a cron job fires in OpenClaw, it can run in one of two modes: isolated session or main session. This choice fundamentally changes how the job interacts with your agent's ongoing conversations and memory. Understanding the tradeoffs between these modes is essential for designing reliable automation workflows.

Key Concepts

  • Isolated Session: The cron job runs in its own separate context with no access to the main conversation history
  • Main Session: The cron job executes within the agent's primary session, adding its output to the next heartbeat turn
  • Context Bleed: The risk of cron job context polluting the main conversation when running in main session mode
  • Model Override: Specifying a different model for cron execution, independent of the agent's primary model
  • Thinking Override: Adjusting the thinking/reasoning budget for cron-specific tasks

Real World Context

An agency manages a coding agent that handles both interactive pair programming sessions and scheduled nightly code reviews. If the nightly review runs in the main session, its lengthy analysis output gets mixed into the next morning's conversation context, confusing the agent when the developer starts chatting. By running the review in an isolated session, the results are kept separate and the main conversation stays clean.

Deep Dive

Isolated Session Mode

Isolated mode is the default for cron jobs. Each execution gets its own fresh context:

json
{
  "cron": {
    "jobs": [
      {
        "id": "nightly-review",
        "schedule": "0 2 * * *",
        "isolated": true,
        "message": "Review all PRs merged today and generate a summary report",
        "model": "anthropic:claude-sonnet-4-20250514",
        "thinking": {
          "budget": 8000
        }
      }
    ]
  }
}

This job runs at 2 AM daily in its own isolated session. It uses Claude Sonnet with an 8000-token thinking budget specifically for this task. The results never appear in the main conversation context.

Main Session Mode

When you want the cron job to contribute to the agent's ongoing context, set isolated: false:

json
{
  "cron": {
    "jobs": [
      {
        "id": "context-updater",
        "schedule": "*/30 * * * *",
        "isolated": false,
        "systemEvent": "Refresh the project status from the issue tracker"
      }
    ]
  }
}

This job runs every 30 minutes and adds its output to the next heartbeat turn in the main session. This is useful when the cron job updates context that the agent needs for interactive conversations.

Model and Thinking Overrides

Each cron job can specify its own model and thinking budget:

json
{
  "cron": {
    "jobs": [
      {
        "id": "quick-check",
        "every": "1h",
        "model": "anthropic:claude-haiku-3",
        "thinking": { "budget": 0 },
        "systemEvent": "Ping the health endpoint and log the response code"
      },
      {
        "id": "deep-analysis",
        "schedule": "0 6 * * 1",
        "model": "anthropic:claude-sonnet-4-20250514",
        "thinking": { "budget": 16000 },
        "message": "Analyze last week's error logs and suggest improvements"
      }
    ]
  }
}

The quick-check job uses Haiku with zero thinking budget for a simple health ping. The deep-analysis job uses Sonnet with a large thinking budget for complex log analysis. This lets you match model capability and cost to the complexity of each task.

Common Pitfalls

  • Running complex analysis in main session mode: Long outputs from cron jobs bloat the main session context, increasing token costs for subsequent interactive turns.
  • Using a frontier model for simple checks: A health endpoint ping does not need Sonnet or Opus. Use Haiku and set thinking budget to 0.
  • Forgetting that isolated sessions do not share memory: An isolated cron job cannot reference information from the main conversation.

Best Practices

  • Default to isolated mode for most cron jobs to keep the main session context clean.
  • Use main session mode only when the cron job updates shared context that subsequent interactions depend on.
  • Match the model and thinking budget to task complexity to optimize cost without sacrificing quality.

Summary

  • Isolated session mode (default) runs cron jobs in their own context, preventing context bleed
  • Main session mode adds cron output to the next heartbeat turn for shared context updates
  • Model overrides let you use cheaper models for simple tasks and powerful models for complex analysis
  • Thinking budget overrides control reasoning depth per job
  • Default to isolated mode and only use main session when context sharing is explicitly needed
✓ Completed