Session Management

Sessions are the fundamental unit of message context in OpenClaw. Every conversation takes place within a session, and sessions determine the AI's memory scope, tool permissions, and behavioral configuration.

Session Model

Session Types

Type	Description	Tool Permissions
main	1:1 direct message session	Execute tools directly on the host machine
group	Group/channel session	Optional Docker sandbox isolation
channel	Per-channel isolation	Inherits channel configuration

Session Key

Source: src/gateway/session-utils.ts

Each session is uniquely identified by a sessionKey, derived from the channel type and account ID:

// src/config/sessions.ts (simplified)
function deriveSessionKey(channel: string, accountId: string): string {
  return `${channel}:${normalizeAccountId(accountId)}`;
}

function normalizeAccountId(accountId: string): string {
  // Normalize E164 phone numbers, WhatsApp JIDs, etc.
}

Session Storage

Source: src/config/sessions.ts

Session state is persisted to the file system:

// src/config/sessions.ts (simplified)
function resolveStorePath(sessionKey: string): string {
  // ~/.openclaw/sessions/{sessionKey}/
}

function loadSessionStore(sessionKey: string): SessionStore {
  // Load from file system
}

function saveSessionStore(sessionKey: string, store: SessionStore): void {
  // Persist to file system
}

Storage location: ~/.openclaw/sessions/{sessionKey}/

Session Patching

Source: src/gateway/sessions-patch.ts

Session configuration can be dynamically modified through the sessions.patch method:

Patchable properties include:

Property	Type	Description
model	string	AI model selection
thinkingLevel	string	Thinking level (on/off/stream)
sandboxMode	boolean	Sandbox mode
queueMode	string	Message queue mode
activationMode	string	Activation method (mention/always)

Session Resolution

Source: src/gateway/sessions-resolve.ts

When a message arrives, the Gateway needs to resolve the target session:

// src/gateway/sessions-resolve.ts (simplified)
function resolveSession(
  channel: string,
  chatType: "direct" | "group" | "channel",
  accountId: string
): ResolvedSession {
  // 1. Derive session key
  const sessionKey = deriveSessionKey(channel, accountId);

  // 2. Check if session exists
  // 3. Apply channel defaults
  // 4. Merge per-session overrides

  return { sessionKey, config };
}

Activation Modes

Whether the AI responds to a message depends on the activation mode:

Mode	Description	Typical Use Case
always	Respond to all messages	1:1 direct messages
mention	Respond only when @mentioned	Group chats
command	Respond only to commands	Channels

File System Session Utilities

Source: src/gateway/session-utils.fs.ts

Session file system operations include transcript management and mirrored persistence:

// src/gateway/session-utils.fs.ts (simplified)
// Session transcript persistence
// Mirrored transcript management
// Session cleanup and maintenance

Session Type Definitions

Source: src/gateway/session-utils.types.ts

// src/gateway/session-utils.types.ts (simplified)
interface SessionConfig {
  model?: string;
  thinkingLevel?: "on" | "off" | "stream";
  sandboxMode?: boolean;
  queueMode?: "fifo" | "fanout";
  activationMode?: "always" | "mention" | "command";
  // ...
}

Summary

• Sessions are uniquely identified by sessionKey, derived from channel + account ID
• Three session types: main (1:1), group (group-based), channel (channel-level)
• Session state is persisted to the ~/.openclaw/sessions/ directory
• sessions.patch enables dynamic configuration updates (model, thinking level, sandbox, etc.)
• Activation mode controls AI responsiveness: always / mention / command

Next: Configuration System