Why OpenClaw Uses sessionKey as Partition Key and How Its Dual‑Queue Design Guarantees Order and Throughput

Using sessionKey as a partition key

In OpenClaw the sessionKey acts like a Kafka partition key. All messages that share the same sessionKey are processed sequentially, while different keys can be processed in parallel. The key also identifies the persisted session record (JSONL) and its index.

In‑order per key : a single active run per session.

Parallel across keys : multiple sessions run concurrently under a global lane limit.

State locateability : session files can be retrieved by key.

Direct messages (DM) are mapped to session.dmScope. Group chats, channels and other sources (cron, webhook, node) use distinct prefixes, making ordering guarantees explicit.

DM continuity and multi‑source isolation

By default OpenClaw folds DM into the main session ( dmScope: main) for a seamless single‑user experience. When several users or shared inboxes feed the agent, the scope must be redefined: per-channel-peer – isolate by channel + sender. per-account-channel-peer – further isolate by account. session.identityLinks – map the same person across channels when needed.

System properties (ordering, isolation) take precedence over user‑experience continuity.

Dual‑layer queue architecture

OpenClaw implements a two‑layer queue:

Enqueue by session key: session:<key> guarantees at most one active run per session.

Schedule the run onto a global lane (default main, optional subagent, etc.) which limits overall parallelism.

This provides two back‑pressure points: per‑session serialization and global lane throttling.

Queue modes as explicit rules

OpenClaw defines three queue behaviours that decide how new messages are inserted into the current run: collect – merge queued messages into a single subsequent round (micro‑batch). followup – start the next round only after the current run finishes (strict FIFO). steer – inject a message into the ongoing run; if the run is not in a streaming stage it falls back to followup.

These correspond to three back‑pressure strategies: followup: simple FIFO, may accumulate backlog. collect: micro‑batching, suitable for rapid bursts or group chats. steer: interactive correction, suited for control‑type messages.

Explainable micro‑batching knobs

Three configurable parameters control the micro‑batch window and backlog handling: debounceMs (default 1000 ms) – time window to merge rapid consecutive inputs. cap (default 20) – maximum number of messages that can be queued before back‑pressure is applied. drop (default summarize) – strategy when the cap is exceeded; a concise summary is injected so the context chain remains coherent.

The goal is explainability: the behaviour can be described by the three knobs without needing performance tuning.

Separate inbound debounce layer

OpenClaw adds an inbound debounce ( messages.inbound.debounceMs) that only applies to pure‑text bursts from the same sender. Media, attachments and control commands bypass this layer.

The system can be conceptually split into two layers:

Input hygiene layer : inbound debounce and deduplication.

Concurrency governance layer : session key, queue mode, and the dual‑layer queue.

Built‑in queue observability

OpenClaw emits structured log events that make queue state visible: queue.lane.enqueue and queue.lane.dequeue events with timestamps and waiting‑time metrics.

If a queue wait exceeds roughly 2 seconds (with detailed logging enabled), a warning is logged.

When a message is enqueued, an early typing indicator is sent to the user (if the channel supports it), exposing the “waiting” state.

These hooks eliminate the need for ad‑hoc instrumentation.