Skip to content

Session management

A session is a conversation context owned by your deployment's OpenClaw gateway — not by the ClusterClaw control plane. Each session stores chat history, routing state, and (when applicable) an active agent run. Sessions are keyed per agent, channel, and sender (for example agent:main:telegram:direct:123456).

On hosted OpenClaw, you manage your own sessions through the gateway runtime (Control UI, CLI, or gateway WebSocket RPC). ClusterClaw provisions and meters the deployment; session lifecycle stays on the gateway, the same as self-hosted OpenClaw.

Official OpenClaw reference

Session semantics, RPC methods, and CLI commands are defined by OpenClaw upstream. Start with the OpenClaw docs and the links in OpenClaw session operations below.

What a session is on hosted OpenClaw

Concept Hosted behavior
Owner Your deployment's gateway process (Cloud Run or GKE Autopilot)
Storage On the deployment's persistent volume under the agent session store
Scope One gateway per deployment; multi-agent setups use isolated stores per agentId
Control plane ClusterClaw tracks deployment health, billing, and credentials — not individual chat sessions

When a user messages your bot on Slack, Telegram, Discord, or another channel, the gateway opens or continues a session for that sender (and agent binding). An active run is an in-flight agent turn; aborting a run stops generation but does not necessarily delete stored history.

See OpenClaw: Session and Multi-agent routing for how keys, agents, and channels relate.

How you manage sessions

You need gateway access (public ingress enabled, deployment HEALTHY) and a gateway token (ccgw_*), not your account API key (cc_*).

  1. Open your deployment in the dashboard.
  2. Ensure Public access is on and status is Healthy.
  3. Click Open gateway — this SSOs you into the OpenClaw Control UI with a one-time gateway token.
  4. Use the Control UI to browse sessions, chat, and stop runs (equivalent to in-chat /stop on many channels).

Gateway tokens are sensitive. Prefer Open gateway over copying tokens into shared documents. See Authentication → Runtime tokens.

CLI — against your hosted gateway

Install the OpenClaw CLI locally (npm install -g openclaw@latest). Point it at your deployment hostname and gateway token:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
export OPENCLAW_GATEWAY_TOKEN='ccgw_...'   # from Open gateway / GetDeploymentGatewayCredentials

# List sessions (same store the gateway uses)
openclaw sessions --json

# Active in the last 120 minutes
openclaw sessions --active 120 --json

# Low-level RPC via the running gateway
openclaw gateway call sessions.list --url "wss://my-bot.clusterclaw.ai" --token "$OPENCLAW_GATEWAY_TOKEN" --params '{}'

# Abort active work on a session key
openclaw gateway call sessions.abort --url "wss://my-bot.clusterclaw.ai" --token "$OPENCLAW_GATEWAY_TOKEN" --params '{"key":"agent:main:..."}'

Replace my-bot.clusterclaw.ai with your deployment hostname. Full CLI reference: openclaw sessions and openclaw gateway.

In-chat commands

Many channels support OpenClaw chat commands without leaving the thread:

Command Effect
/stop Abort the current run, clear queued follow-ups for that session
/status Reachability, context usage, and session-oriented status
/compact Compact session context to free window space

Exact behavior is channel- and config-dependent. See OpenClaw: Session.

ClusterClaw API

The customer Connect API manages deployments (create, start, stop, logs, gateway credentials). It does not expose sessions.list or sessions.abort. Use gateway credentials from GetDeploymentGatewayCredentials and call the gateway directly (CLI or WebSocket RPC).

OpenClaw session operations

Use these official OpenClaw documentation pages for commands and RPC details:

Topic OpenClaw docs
Session concepts docs.openclaw.ai/concepts/session
Multi-agent & session keys docs.openclaw.ai/concepts/multi-agent
CLI: list & cleanup docs.openclaw.ai/cli/sessions
CLI: gateway & gateway call docs.openclaw.ai/cli/gateway
Gateway runbook docs.openclaw.ai/gateway
Gateway protocol (sessions.list, sessions.abort, …) docs.openclaw.ai/gateway/protocol

Common gateway RPC methods (WebSocket req after connect):

  • sessions.list — list sessions with optional activeMinutes, search, limit
  • sessions.abort — stop active work for a key (optional runId)
  • sessions.reset, sessions.delete, sessions.compact — maintenance (see protocol doc)

Authenticate with Authorization: Bearer <ccgw_*> or the token passed in the connect frame, matching self-hosted gateway auth.

Platform differences

ClusterClaw's default runtime is OpenClaw. Session management for that path follows OpenClaw docs above. Other agent runtimes use different session models; the control plane does not unify them.

Runtime Session model Where to look
OpenClaw (default on ClusterClaw) Gateway-owned sessions, sessions.list / sessions.abort, CLI + Control UI OpenClaw docs — links in this guide
jcode Different multi-agent execution model; not OpenClaw-compatible No jcode runtime is documented in ClusterClaw today — session APIs will differ if/when offered
Other OSS multi-agent platforms Varies by upstream (CrewAI, AutoGen, custom harnesses, etc.) Consult that project's docs; ClusterClaw does not expose a shared session API across runtimes

If you run OpenClaw on ClusterClaw, treat session operations exactly as you would on a self-hosted gateway — only the hostname and token delivery differ.

Hosted vs self-hosted

Self-hosted OpenClaw ClusterClaw hosted
Session store location Your machine / your K8s PVC Deployment PVC (Cloud Run volume or GKE)
Gateway URL localhost or your domain *.clusterclaw.ai or your BYO CNAME
Token source Your openclaw.json / env ccgw_* via dashboard SSO or GetDeploymentGatewayCredentials
Stop/start deployment You operate the process StopDeployment / StartDeployment RPC — stops all gateway sessions
Session list/abort CLI, Control UI, gateway RPC Same tools, aimed at your deployment hostname

Stopping a deployment from the dashboard or API shuts down the gateway container; in-memory runs end and channels disconnect until you start again. That is separate from aborting a single session while the gateway stays up.

Troubleshooting

Symptom What to check
Cannot open Control UI Public ingress enabled, status HEALTHY, DNS/TLS complete — see Deployments
unauthorized on gateway RPC Use ccgw_* gateway token, not cc_* API key
Empty session list Wrong agent scope (--agent, --all-agents); or no recent traffic on that deployment
Run won't stop Try /stop in-channel, then sessions.abort via CLI; check Gateway troubleshooting