PR #58550: feat(sessions): SQLite-backed two-tier session store — fixes 140%+ CPU at scale

• Repository: openclaw/openclaw
• Author: alexdeg92
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/58550

Description (problem / solution / changelog)

SQLite-backed Session Store

Problem

The flat sessions.json file causes severe performance issues at scale:

• File grows to 42MB+ with 1000+ sessions
• Every session operation requires reading/writing the entire file
• Results in 140%+ CPU usage and 6+ second response times
• JSON parsing/serialization becomes the bottleneck

Related issues: #58534 (perf), #57497 (Postgres request)

Solution: Two-tier Architecture

Hot Index (SQLite)

A lightweight SQLite database replaces sessions.json for metadata:

~/.openclaw/state/agents/{agentId}/sessions/sessions.sqlite

Schema columns:

• session_key (PRIMARY KEY) - session identifier
• session_id - UUID
• updated_at, created_at - timestamps (indexed)
• channel, last_channel, last_to, last_account_id, last_thread_id - routing
• label, display_name, status - display info
• model, model_provider, total_tokens, input_tokens, output_tokens - model state
• message_count, archived - metadata
• entry_json - full SessionEntry blob for complex fields

Benefits:

• O(1) session lookups instead of O(n) JSON parsing
• Incremental updates (no full file rewrites)
• Proper indexing for common query patterns
• WAL mode for concurrent read/write
• ~10x faster at 1000+ sessions

Cold Storage (unchanged)

Existing .jsonl transcript files stay as-is:

• Per-session files, already efficient
• Only loaded on explicit sessions_history calls
• Never in the hot path

Configuration

Add to openclaw.json:

{
  "session": {
    "storeType": "sqlite"  // "json" (default) or "sqlite"
  }
}

Migration

Automatic (on first access)

When storeType: "sqlite" is set, existing sessions.json is automatically migrated to SQLite on first load.

Manual (CLI)

# Preview migration
openclaw sessions migrate --dry-run

# Migrate default agent
openclaw sessions migrate

# Migrate all agents
openclaw sessions migrate --all-agents

# Check store info
openclaw sessions store-info

Fallback Behavior

• If SQLite unavailable (Node < 22.5), falls back to JSON automatically
• If SQLite operations fail, falls back to JSON for that operation
• sessions.json is preserved during migration (not deleted)

Files Changed

New Files

• src/config/sessions/store-sqlite.ts - SQLite storage implementation
• src/config/sessions/store-facade.ts - Backend abstraction layer
• src/commands/sessions-migrate.ts - Migration command

Modified Files

• src/config/types.base.ts - Added SessionStoreType and storeType config
• src/config/sessions/store.ts - Integrated facade for load/save
• src/cli/program/register.status-health-sessions.ts - CLI commands

Performance Expectations

Testing

# Run session store tests
pnpm test -- src/config/sessions/

# Type check
pnpm tsgo

# Lint
pnpm check

Backward Compatibility

• Default is storeType: "json" for backward compatibility
• Existing sessions.json files continue to work
• Migration is opt-in via config or CLI command
• SQLite requires Node 22.5+ (built-in node:sqlite)

Closes #58534 Related #57497

Changed files

• PR_DESCRIPTION.md (added, +123/-0)
• src/cli/program/register.status-health-sessions.ts (modified, +73/-0)
• src/commands/sessions-migrate.ts (added, +256/-0)
• src/config/schema.base.generated.ts (modified, +17/-0)
• src/config/schema.help.ts (modified, +2/-0)
• src/config/schema.labels.ts (modified, +1/-0)
• src/config/sessions/store-facade.ts (added, +200/-0)
• src/config/sessions/store-sqlite.test.ts (added, +288/-0)
• src/config/sessions/store-sqlite.ts (added, +614/-0)
• src/config/sessions/store.ts (modified, +70/-44)
• src/config/types.base.ts (modified, +11/-0)
• src/config/zod-schema.session.ts (modified, +1/-0)

PR #59436: perf(gateway): apply limit before building session rows and index child lookups

• Repository: openclaw/openclaw
• Author: coderredlab
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59436

Description (problem / solution / changelog)

Summary

Three complementary optimisations for listSessionsFromStore() to reduce sessions.list latency, especially on resource-constrained hosts (Android/proot):

• Early limit application: Pre-sort entries by entry.updatedAt and apply limit + activeMinutes filters before calling buildGatewaySessionRow(), avoiding expensive per-row disk I/O (transcript reads, file stats) for sessions that would be discarded.
• Child session index: Replace the O(N²) resolveChildSessionKeys() store scan with a one-time buildChildSessionIndex() reverse map — O(N) build + O(1) per-row lookup.
• Search pre-filtering: When text search is active, derive all five search-target fields (key, sessionId, label, subject, displayName) from the store entry alone — no disk I/O — and discard non-matching entries before building rows. This allows the limit to be applied early in all code paths.

Before / After

With 447 sessions and limit=10 (typical dashboard call):

Motivation

On resource-constrained hosts (Android/proot where every syscall goes through ptrace) the per-row disk I/O in buildGatewaySessionRow — transcript reads, realpathSync, existsSync, fstatSync — dominates sessions.list latency. With ~450 accumulated sessions the dashboard becomes unresponsive (6.5 s+, CPU 100%).

Refs: #57715, #58534

Test plan

• pnpm exec vitest run src/gateway/session-utils.test.ts — 79 tests pass
• pnpm exec vitest run src/gateway/sessions-resolve.test.ts — 2 tests pass
• Pre-commit hooks (tsgo, lint, conflict markers) pass

Changed files

• src/gateway/session-utils.ts (modified, +115/-42)

PR #59464: perf(gateway): start channels without blocking sidecar init

• Repository: openclaw/openclaw
• Author: coderredlab
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59464

Description (problem / solution / changelog)

Summary

• Fire startChannels() without await in startGatewaySidecars() so channel plugin loading no longer blocks the event loop.

Problem

Channel plugins — particularly WhatsApp (@whiskeysockets/baileys 9.1 MB + jimp 3.9 MB) — pull in large dependency trees. Their dynamic import() chains monopolise the Node.js event loop during module resolution:

[hooks] loaded 5 internal hook handlers      ← event loop blocked from here
                                              ← 95 seconds of silence
[whatsapp] [default] starting provider       ← event loop released

During this window the gateway cannot serve HTTP or WebSocket requests, so the dashboard UI is completely unresponsive even though the server is already listening.

On constrained hosts (Android/proot where every stat/read syscall goes through ptrace) this takes ~95 seconds. Even on macOS it can take 5-8 seconds.

Fix

Wrap the prewarmConfiguredPrimaryModel + startChannels sequence in a void IIFE so it runs in the background. The gateway can start serving requests (dashboard, health checks, pairing) immediately after hooks are loaded. Errors are still caught and logged.

Nothing downstream in startGatewaySidecars depends on channel startup completing — pluginServices, hooks, ACP reconciliation, and memory backend all proceed independently.

Refs: #58534

Test plan

• pnpm exec vitest run src/gateway/server-startup.test.ts — 2 tests pass
• Pre-commit hooks (tsgo, lint, conflict markers) pass

Changed files

• src/gateway/server-close.test.ts (modified, +1/-1)
• src/gateway/server-close.ts (modified, +11/-3)
• src/gateway/server-startup.ts (modified, +43/-19)
• src/gateway/server.impl.ts (modified, +9/-4)