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 (e.g. spawning subagents for background tasks while you keep chatting)

See Multi-Agent Team and Example Setups & Model Routing for patterns.

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

You can run multiple OpenClaw agents as a team: one Gateway, many sessions. Each session is one “agent” with its own identity, memory, and (optionally) role. Builders use this for “agent squads”—a coordinator plus specialists (researcher, writer, analyst) that wake on a schedule, share a task list, and hand off work. For a full walkthrough, see Multi-Agent Team use case.

OpenClaw 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

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.

Sub-agents are short-lived sessions created by your main agent (via sessions_spawn) to run a single task and report back. You can also send messages to an existing session from the CLI with openclaw agent --message "..." --to <sessionKey>. For a step-by-step setup—spawning, sending, Discord thread-bound subagents, and troubleshooting—see Set up a sub-agent.

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.