Sessions & Multi-Agent Routing

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

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

Channel-Based Routing

Route different channels to different agents:

{
  "agents": {
    "whatsapp-agent": {
      "workspace": "~/clawd-whatsapp",
      "channels": ["whatsapp"]
    },
    "telegram-agent": {
      "workspace": "~/clawd-telegram",
      "channels": ["telegram"]
    }
  }
}

Peer-Based Routing

Route specific contacts to dedicated agents:

{
  "agents": {
    "work-agent": {
      "workspace": "~/clawd-work",
      "peers": ["+1234567890", "+0987654321"]
    }
  }
}

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 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

Moltbot 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.

Configure session behavior in your ~/.clawdbot/moltbot.json (file name maintained for backward compatibility):

{
  "agents": {
    "defaults": {
      "session": {
        "activation": "mention",
        "queue": "sequential",
        "sandbox": {
          "mode": "non-main"
        }
      }
    }
  }
}

Sessions automatically compact context to manage token usage:

• Automatic Pruning - Old context removed when limits reached
• Memory Summarization - Important information summarized
• Token Management - Stays within model context limits

This ensures sessions remain efficient while maintaining important context.