OpenClaw Session Management Explained

OpenClaw sessions are the unit of execution for everything your AI agent does. Understanding how sessions work — how they start, what state they carry, how they nest, and when they end — is essential for building reliable agent workflows. This guide covers the session model from first principles.

If you're new to DenchClaw, start with what DenchClaw is and the setup guide.

What Is a Session?#

A session is a single conversation between you (or a trigger) and the OpenClaw agent. It has:

• A session ID — a unique identifier like agent:main:abc123
• A message history — the conversation so far, including tool calls and results
• A context — the system prompt, loaded skills, and any files in context
• A state — active, completed, or errored

Sessions are stateful within their lifetime. When you send a message, the agent sees everything that happened in the session before it. When the session ends, that context is gone — the next session starts fresh.

This is not a bug. It's the design. DenchClaw's persistence layer (DuckDB, the workspace filesystem) is where long-term state lives. Sessions are for reasoning, not storage.

Session Types#

OpenClaw has several session types, identified by their ID prefix:

Main session (agent:main)#

The primary interactive session — the one you're talking to in the web UI at localhost:3100. There's typically one active main session. This is where you interact with DenchClaw day-to-day.

Subagent sessions (agent:main:subagent:<id>)#

Child sessions spawned by the main session (or another subagent) to handle specific tasks. They run concurrently, report results back to their parent, and then terminate. You can see active subagents in the sidebar.

Webhook-triggered sessions#

Sessions started by incoming webhook events rather than a human message. These handle external triggers automatically — see the webhook handling guide.

Cron sessions#

Scheduled sessions that run on a timer. Useful for daily reports, scheduled syncs, and periodic health checks.

The Session Lifecycle#

Created → System prompt loaded → First message received
    → Agent responds / calls tools → More messages
    → Task complete → Session ends (or continues)

Sessions don't automatically end when a task is done. They continue until:

• You close the browser tab
• The session times out (configurable)
• The agent or user explicitly closes the session
• A subagent completes its assigned task

Session state in detail#

At any point, a session carries:

1. System prompt — The base instructions that define agent behavior
2. Loaded skills — Markdown files injected into context
3. Message history — Every human message, tool call, and tool result
4. Active tool calls — Any in-flight tool executions
5. Metadata — Session ID, timestamps, model configuration

The message history is the expensive part. Each turn adds to it, and everything in the history is sent to the LLM on every subsequent call.

Managing Session State#

When to start a new session#

Start a fresh session when:

• You're switching to a completely different task
• The current session has grown long (20+ turns) and performance is degrading
• You want a clean context without accumulated assumptions from prior conversation
• A previous task had errors that might confuse the agent

Fresh sessions are cheap to create. Don't hesitate to use them.

Saving state before ending a session#

Before closing a long session, save important context to persistent storage:

Summarize what we accomplished in this session, 
any decisions made, and what should happen next.
Save this to ~/.openclaw-dench/workspace/docs/session-handoffs/YYYY-MM-DD-task-name.md

The next session can start by reading this file:

Read the session handoff from docs/session-handoffs/2026-03-26-customer-onboarding.md
and pick up where we left off.

Session handoffs in DuckDB#

For structured state, write to DuckDB instead of markdown:

CREATE TABLE IF NOT EXISTS session_handoffs (
  id INTEGER PRIMARY KEY,
  session_id VARCHAR,
  task_name VARCHAR,
  status VARCHAR,
  summary TEXT,
  next_actions TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Subagent Architecture#

Subagents are where OpenClaw's orchestration model gets interesting. They enable parallelism and task isolation.

How subagents work#

When the main agent encounters a task that benefits from parallel execution or isolation, it spawns subagents:

1. Main agent receives a complex request
2. Main agent decomposes it into subtasks
3. Main agent spawns N subagents, one per subtask
4. Subagents run concurrently
5. Each subagent reports results back to main
6. Main agent synthesizes results

This is how DenchClaw handles tasks like "research 3 competitors simultaneously" or "process 50 leads in parallel" — the work gets distributed across concurrent subagents rather than executed sequentially.

Subagent isolation#

Each subagent has its own context. It doesn't share the main session's conversation history. This is a feature:

• Subagents don't get confused by the main session's accumulated context
• Subagents can make mistakes without polluting the main session
• Subagents can run as a different model (e.g., a faster model for simple tasks)

The isolation means subagents need all the context they need in their initial prompt. The main agent is responsible for providing that context explicitly.

Subagent depth limits#

By default, subagents can spawn their own subagents (up to a configurable depth). This enables complex multi-level orchestration. However, deep nesting multiplies token usage. Most tasks don't need more than 2 levels.

Session Configuration#

Configure session behavior in your workspace config:

{
  "session": {
    "timeout_minutes": 60,
    "max_turns": 100,
    "auto_summarize_after_turns": 50,
    "model": "claude-sonnet-4",
    "subagent": {
      "max_depth": 2,
      "max_concurrent": 5,
      "default_model": "claude-haiku-3-5"
    }
  }
}

Key settings:

• timeout_minutes — how long a session stays alive without activity
• max_turns — hard limit on conversation length
• auto_summarize_after_turns — automatically compress history when it gets long
• subagent.default_model — use a cheaper model for subagents by default

Session IDs and Debugging#

Session IDs follow a hierarchical structure:

agent:main                              # Main session
agent:main:subagent:abc123             # Subagent of main
agent:main:subagent:abc123:subagent:xyz # Nested subagent

This hierarchy lets you trace any session back to its origin. In the audit logs:

# Find all sessions from today
ls ~/.openclaw-dench/workspace/.openclaw/logs/ | grep $(date +%Y-%m-%d)
 
# Find subagents of a specific parent
ls ~/.openclaw-dench/workspace/.openclaw/logs/ | grep "agent:main:subagent"
 
# Get the full timeline for a session
cat ~/.openclaw-dench/workspace/.openclaw/logs/agent-main-abc123.jsonl \
  | jq '{ts, tool, status, durationMs}'

See the audit logs guide for the full logging reference.

Cron Sessions#

For tasks that should run on a schedule, configure cron sessions:

{
  "cron": [
    {
      "schedule": "0 9 * * 1",
      "task": "Generate a weekly CRM summary and save to docs/reports/",
      "label": "weekly-report",
      "model": "claude-haiku-3-5"
    },
    {
      "schedule": "0 * * * *",
      "task": "Check for unprocessed webhook events and process them",
      "label": "webhook-processor"
    }
  ]
}

Cron sessions:

• Start fresh each run (no accumulated history)
• Run in the background (you don't see them in the main UI unless you check)
• Write results to DuckDB or the workspace filesystem for persistence
• Use the label to find them in logs

Channel Sessions#

DenchClaw connects to messaging channels (Telegram, Discord, Slack, etc.) via the channel plugin system. Each channel interaction is a session:

channel:telegram:user_id      # Telegram user session
channel:discord:channel_id    # Discord channel session
channel:slack:workspace_id    # Slack session

Channel sessions behave like main sessions but receive messages from external platforms. They don't share context with your main session — so things you've told your main agent aren't automatically known to your Telegram bot, and vice versa.

For channel-specific persistence, write to DuckDB and read from it. DuckDB is the shared memory layer across all session types.

Common Session Patterns#

Pattern 1: Task-per-session#

New task → new session → write results to DuckDB → close session. This keeps sessions short and contexts clean.

# Start session
"Import the 50 leads from leads.csv into the CRM. 
When done, save a summary to docs/imports/2026-03-26.md"

# Session completes, write results
# Close session

Pattern 2: Persistent workspace session#

Keep one main session open all day. Use it for interactive work, questions, and quick tasks. Fresh subagents for heavy lifting.

Pattern 3: Event-driven sessions#

Webhook arrives → new session spawned → processes event → writes to DuckDB → closes. Fully automated, zero-maintenance.

Pattern 4: Scheduled analysis sessions#

Cron job triggers daily → session reads all new data → generates report → writes to docs → closes. Run every morning before you start work.

Session Best Practices#

Don't store critical state only in session context. Write it to DuckDB or the filesystem. Sessions end; files don't.

Keep subagent prompts complete and self-contained. Subagents have no access to the parent's conversation history. Everything they need must be in their initial prompt.

Use session labels. Label important subagents so you can find them in logs. An unlabeled session is hard to debug.

Don't chain too many turns for simple tasks. If a task requires 20+ tool calls, it's probably better as a structured batch script than an agent conversation.

Monitor session count. Too many concurrent subagents competes for LLM quota. Keep concurrent sessions under 5-10 for typical workloads.

FAQ#

Q: Can two sessions share context in real time? A: Not directly — sessions are isolated. Use DuckDB as the shared state layer. One session writes, another reads.

Q: What happens to a subagent if the main session closes? A: The subagent continues running and completes its task. Results are announced back to the requester when done.

Q: How do I see all currently active sessions? A: The sidebar in the DenchClaw UI at localhost:3100 shows active sessions. You can also check the logs directory for recent log files.

Q: Can I manually kill a session that's stuck? A: Yes. In the UI, close the session from the sidebar. Or from the command line, kill the associated process using the session ID from the logs.

Q: Does session history get stored permanently? A: Session logs (tool calls and outputs) are stored in the JSONL log files indefinitely. The conversation text is part of the session context but is not separately archived. Write any conversation summaries you want to keep to the workspace filesystem.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →