Sessions & Memory

Sessions are the core unit of conversation management in OpenClaw. They maintain context, state, and isolation between different conversations. Understanding sessions is key to configuring multi-agent routing and managing complex workflows.

Main Session

The main session is the default session for direct messages (DMs). By default:

• All direct messages collapse into a shared main session
• Context is shared across all DM conversations
• Tools run on the host with full access (for trusted use)
• Perfect for personal use where you want unified context

Group Sessions

Each group chat gets its own isolated session:

• Context is isolated from other groups and DMs
• Can be configured to run in Docker sandboxes
• Supports mention-based activation
• Each group maintains its own conversation history

Isolated Sessions

You can create isolated sessions for:

• Specific routing needs
• Security isolation
• Testing and development
• Multi-agent setups

Activation Modes

Control when the agent responds in a session:

• always - Agent responds to all messages
• mention - Agent only responds when mentioned (default for groups)
• manual - Agent only responds when explicitly activated

Queue Modes

How the session handles concurrent requests:

• sequential - Process messages one at a time
• parallel - Handle multiple requests simultaneously
• priority - Process based on priority levels

Context Management

Sessions automatically:

• Load relevant context and memories
• Maintain conversation history
• Prune old context when needed
• Update memories based on conversations

OpenClaw supports routing messages to different agents based on various criteria:

Channel-Based Routing

Route different channels to different agents:

{
  "agents": {
    "list": [
      { "id": "whatsapp-agent", "workspace": "~/.openclaw/workspace-whatsapp" },
      { "id": "telegram-agent", "workspace": "~/.openclaw/workspace-telegram" }
    ]
  },
  "bindings": [
    { "match": { "channel": "whatsapp" }, "agentId": "whatsapp-agent" },
    { "match": { "channel": "telegram" }, "agentId": "telegram-agent" }
  ]
}

Peer-Based Routing

Route specific contacts to dedicated agents:

{
  "bindings": [
    { 
      "match": { 
        "channel": "whatsapp",
        "peer": { "kind": "dm", "id": "+1234567890" }
      }, 
      "agentId": "work-agent" 
    }
  ]
}

Group-Based Routing

Each group can have its own agent workspace:

• Isolated context per group
• Different skills and tools per group
• Separate memory and configuration

Session Isolation

Session isolation provides security and context separation:

• Workspace Isolation - Each agent has its own workspace directory
• Memory Isolation - Separate memory files per agent
• Tool Isolation - Different tool policies per session
• Sandbox Isolation - Groups can run in Docker containers

OpenClaw provides tools for session management:

• ''sessions_list'' - List all active sessions
• ''sessions_history'' - View session conversation history
• ''sessions_send'' - Send messages to specific sessions
• ''sessions_spawn'' - Create new isolated sessions

These tools allow agents to manage and communicate with other sessions.

SessionsPage.config.intro

{
  "session": {
    "scope": "per-sender",
    "reset": {
      "mode": "daily",
      "atHour": 4
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

Sessions automatically compact context to manage token usage:

• ✂️
  Automatic PruningOld context removed when limits reached.
• 📝
  Memory SummarizationImportant information summarized.
• ⚖️
  Token ManagementStays within model context limits.

This ensures sessions remain efficient while maintaining important context.