Session Management

Clawdbot organizes conversations through a Session system that maps different communication channels to isolated or shared conversation contexts.

Core Concepts

Session Keys and Routing

Sessions are identified by unique keys:

DMs: Follow dmScope setting (default shares main session)
Group chats: Use independent session keys in format agent:<agentId>:<channel>:group:<id>

Gateway Authority

All session state is owned by the gateway:

"All session state is owned by the gateway."

UI clients query the gateway for session lists and token counts rather than reading local files.

Session Configuration

dmScope Setting

Control DM message session grouping:

{
  dmScope: "main"        // All DMs share main session (default)
  // or
  dmScope: "per-peer"    // Independent session per contact
  // or
  dmScope: "per-channel-peer"  // Independent session per contact per channel
}

Reset Policies

Configure automatic session resets:

{
  session: {
    // Daily reset time (default 4 AM)
    resetTime: "04:00",
 
    // Idle timeout reset (seconds)
    idleTimeout: 3600,
 
    // Configure by type
    resetByType: {
      dm: { idleTimeout: 7200 },
      group: { idleTimeout: 1800 }
    },
 
    // Configure by channel
    resetByChannel: {
      telegram: { resetTime: "00:00" }
    }
  }
}

Identity Links

Map cross-platform identities to the same session:

{
  identityLinks: [
    {
      // Same person's accounts across platforms
      ids: [
        "telegram:123456789",
        "whatsapp:+15551234567",
        "discord:987654321"
      ],
      // Share session
      sharedSession: true
    }
  ]
}

Session Commands

User Commands

Users can use these commands in chat:

/new          # Start new session
/reset        # Reset current session
/new claude   # Start new session with specific model

CLI Commands

# List all sessions
clawdbot sessions list
 
# View session details
clawdbot sessions show <session-id>
 
# Delete session
clawdbot sessions delete <session-id>
 
# Export session history
clawdbot sessions export <session-id> --format json

Session Lifecycle

Create → Active → Idle → Reset/Expire
  │                      │
  └──── Manual Reset ────┘

Creation Triggers

First message received
User uses /new command
After automatic reset

Reset Triggers

Daily reset time reached
Idle timeout
Manual user reset
Admin operation

Advanced Configuration

Send Policy

Block message sending for specific session types:

{
  sendPolicy: {
    // Block sending to groups
    blocked: ["group"]
  }
}

History Limits

Control session history size:

{
  session: {
    // Maximum messages
    maxMessages: 100,
 
    // Maximum tokens
    maxTokens: 50000,
 
    // Compaction strategy
    compaction: "summarize"
  }
}

Memory Management

{
  memory: {
    // Enable long-term memory
    enabled: true,
 
    // Memory store
    store: "local",
 
    // Memory retrieval count
    retrieveCount: 5
  }
}

Debugging Sessions

View Session State

# Via dashboard
http://127.0.0.1:18789/
 
# Or CLI
clawdbot sessions show <session-id> --verbose

Session Logs

clawdbot logs --session <session-id> --follow

Next Steps

Streaming - Understand message streaming
Configuration - Complete configuration reference

Multi-Agent Routing Streaming