Session

Understanding conversation sessions.

What is a Session?

A session represents a conversation context:

• Message history
• User identity
• Active channel
• Conversation state

Session Lifecycle

┌─────────┐   ┌─────────┐   ┌─────────┐
│ Created │ → │ Active  │ → │ Expired │
└─────────┘   └─────────┘   └─────────┘

1. Created: New conversation starts
2. Active: Ongoing conversation
3. Expired: Session times out or is cleared

Session Storage

Sessions store:

Data	Description
Messages	Conversation history
Metadata	Channel, user info
Context	Active tools, state
Timestamps	Created, updated

Session Management

# List sessions
openclaw sessions list

# View session
openclaw sessions show <id>

# Clear old sessions
openclaw sessions clear --older-than 7d

Configuration

{
  sessions: {
    maxAge: "7d",           // Session expiration
    maxMessages: 100,       // Messages per session
    compaction: {
      enabled: true,
      threshold: 50
    }
  }
}

Context Window

The context window limits how much history is sent to the model:

{
  sessions: {
    contextWindow: 20,      // Messages to include
    contextTokens: 4000     // Token limit
  }
}

Session Isolation

Each channel/user combination gets a unique session:

• WhatsApp: Per phone number
• Telegram: Per chat ID
• Discord: Per channel or DM

See Also

• Memory
• Compaction
• CLI: sessions