openclaw-sessions

OpenClaw Sessions

Guide the user through session management: scoping, resets, compaction, thread bindings, identity links, and session tools.

Session Concept

A session is a conversation context identified by a sessionKey. Sessions store:

• Chat history (transcript) at ~/.openclaw/agents/<agentId>/sessions/*.jsonl
• Context state (model, tools, compaction state)

The sessionKey is computed from dmScope + channel + peer + account. It is a routing key, not an authorization token.

DM Scope

session.dmScope controls how DM sessions are isolated:

Value	Behavior	Use Case
main	All DMs share one session	Single-user continuity (default)
per-peer	One session per sender	Multi-user, channel-agnostic
per-channel-peer	One session per channel+sender	Multi-user, channel-isolated
per-account-channel-peer	One per account+channel+sender	Multi-account channels

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
  },
}

main is the canonical direct-chat key. Group/channel sessions use their own keys (they always count as non-main).

Session Reset

Control when session history is cleared:

{
  session: {
    reset: {
      mode: "daily",        // "daily" | "idle"
      atHour: 4,            // hour (0-23) for daily reset
      idleMinutes: 120,     // minutes of inactivity for idle reset
    },
  },
}

• daily — resets at atHour every day
• idle — resets after idleMinutes of no activity

Thread Bindings (Discord)

Thread bindings route messages in Discord threads to specific sessions:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,       // auto-unbind after idle
      maxAgeHours: 0,      // max thread age (0 = no limit)
    },
  },
}

Discord Commands

• /focus — bind current thread to a session
• /unfocus — unbind thread
• /agents — list available agents for thread binding
• /session idle <hours> — set idle timeout for current thread
• /session max-age <hours> — set max age for current thread