openclaw - 💡(How to fix) Fix [Feature]: Support external unified session storage for stateless session mode [1 participants]

Summary

Introduce a pluggable session storage backend (Redis, MongoDB, etc.) to enable stateless session sharing across multiple Openclaw instances, eliminating session stickiness and improving horizontal scalability.

Problem to solve

Currently Openclaw stores sessions only in the local filesystem. In multi‑instance deployments (e.g., Kubernetes, load‑balanced servers), each instance has its own session files, causing:

• Session stickiness – user requests must always be routed to the same instance; otherwise session data is lost.
• Limited scalability – adding more instances does not help session handling capacity.
• Poor reliability – an instance crash permanently loses its local sessions.

This makes Openclaw unsuitable for cloud‑native, distributed environments where stateless, horizontally scalable services are required.

Proposed solution

Design a unified session storage abstraction with pluggable backends, allowing sessions to be read from/written to an external storage system. The solution includes:

1. Storage interface – defines core operations (get, set, delete, exists) as an abstract base class.
2. File system storage (default) – keeps the current behavior for backward compatibility.
3. External storage implementations – initially Redis (recommended) and MongoDB, with more to be added.
4. Factory & manager – creates the appropriate storage instance based on configuration.
5. Configuration extension – new session_storage section in the config file, e.g.:

   session_storage:
     backend: redis
     redis_host: localhost
     redis_port: 6379
     default_ttl: 604800

All session management code uses the storage interface, so the rest of the application remains unchanged. This enables any instance to access any session, achieving true stateless operation.

Alternatives considered

Sticky sessions via load balancer – does not solve the underlying issue; session loss still occurs on instance failure, and scaling is not flexible.

Client‑side sessions (e.g., JWT) – limited by payload size and security concerns, not suitable for large or sensitive session data.

Hard‑coded Redis support only – lacks extensibility and maintainability; forces a single backend without a clean abstraction.

The proposed interface‑based approach is the most maintainable, flexible, and future‑proof.

Impact

1、Affected users/systems/channels All Openclaw users deploying more than one instance (e.g., in Kubernetes, cloud auto‑scaling groups). Both single‑tenant and multi‑tenant setups benefit.

2、Severity For single‑instance deployments – low (no change). For multi‑instance deployments – high (currently blocks stateless scaling; workarounds are complex and fragile).

3、Frequency Always occurs in multi‑instance setups. As more users adopt container orchestration, this pain point becomes increasingly common.

4、Consequence Without this feature, users must either force session stickiness (which limits elasticity and fault tolerance) or accept random session failures. This leads to operational overhead, poor user experience, and increased manual intervention (e.g., clearing stale sessions, debugging routing issues).

5、Practical consequences

Delays in feature rollout for horizontally scaled deployments.

Extra manual work to manage session affinity rules and monitor instance health.

Risk of data loss when an instance crashes.

Inability to use Openclaw in serverless or ephemeral compute environments.

This enhancement is a prerequisite for production‑ready, cloud‑native Openclaw deployments.

Evidence/examples

1. Log example showing session loss with current file‑system storage in a multi‑instance deployment Two instances (A and B). A user request hits instance A first (session created), then a subsequent request is routed to instance B: Instance A log (session creation) 2025-03-20 10:15:32 INFO [session] Created session session_abc123, saved to ./data/sessions/abc123.json 2025-03-20 10:15:33 INFO [request] User request handled by instance A, session_id=abc123

Instance B log (next request from same user) 2025-03-20 10:15:45 WARN [session] Session session_abc123 not found in local storage (./data/sessions/) 2025-03-20 10:15:45 ERROR [middleware] Failed to load session, starting new empty session

Consequence: Conversation context is lost; the agent cannot continue the previous dialogue.

Additional information

Security considerations 1、Connection credentials (passwords, URIs) for external storage must be read from environment variables or a secret manager, not hard‑coded in configuration files. 2、Sensitive session fields (e.g., user tokens) could be encrypted before storage (AES‑256‑GCM). This can be a follow‑up enhancement.