Session continuity across two CLI clients and a Gateway restart

Session continuity across two CLI clients and a Gateway restart

What this guide verifies, and what it doesn’t. The experiment below reproduces session continuation between two same-machine CLI clients with independent state and across a Gateway restart, using synthetic markers. It explains the session model that multi-device use relies on, but it does not verify cross-device networking, mobile clients, channel pairing, or model inference — treat those as unverified boundaries, not as results.

This is an original guide. Facts come from the local Remote access, Sandbox, tool policy, and elevated, Automation payloads, Exec approvals, and Gateway CLI pages (checked against the fixed official snapshot, 2026-11-06); no new external claims are introduced. Connection and pairing examples remain illustrative; the session-continuation semantics in section 2 were verified against a live Gateway on 2026-11-15 (see the note at the end of that section).

Running an OpenClaw Gateway at home while using your phone on the couch, your laptop in the study, and a tablet on the go comes down to one key insight: sessions and message history live on the Gateway; every device is just a client. Clients are not empty shells, though — each keeps its own local state directory and caches paired-device credentials (see layer 2 below). Once that split clicks, “who can see what on which device”, “how do I pick up on another device”, and “what if a device is lost” all have answers you can check.

1. Two kinds of clients

Devices connecting to the Gateway fall into two classes with very different capabilities and trust:

KindWhat it isWhat it can do
Operator clientThe macOS app, CLI, or web UI you use yourselfFull operation: chat, manage config, approve executions, manage jobs
NodeA node client on iOS/Android and similar devicesA peripheral: exposes local capabilities (e.g. node tool calls) to the Gateway; owns no sessions and runs no Gateway service

Nodes do not run the Gateway and store no sessions; they register their capabilities with the Gateway, and the Gateway’s agent decides whether to call them (e.g. “take a photo with the phone” node tools). The macOS app’s “node mode” is essentially a node client over the WebSocket connection.

2. How sessions continue across devices

Because the Gateway owns sessions, “switching devices” is an attachment problem, not a sync problem:

  • Clients connecting with the same credentials read back the same session and history — that is what the live check below verifies. What different operators can see is governed by Gateway authentication and method authorization (layer 2–3 below), not by the fact that a connection succeeded; this guide’s experiment did not test multiple operator identities;
  • Remote clients can continue a Gateway-owned session by URL or short reference — a thread started on the phone picks up on the laptop by entering the same session reference;
  • Messages go to sessions, not devices: messaging a job’s cron:<jobId> session addresses its latest run regardless of which device you are on;
  • A device going offline interrupts nothing — the Gateway stays up and sessions live with it.

Corollary: there is no “sync chat history between devices” step to worry about; what you back up is the Gateway’s state (see the backup section of the home-server guide, Chinese version: 家庭服务器运行 OpenClaw).

Verified against a live Gateway (2026-11-15): two independent CLI client processes (the second one using its own separate local state directory) connected to the same isolated loopback Gateway (OpenClaw 2026.11.3 (847611d), Node 24.18.0, macOS 12.7.6). A synthetic marker was written into the shared session via chat.inject — no model inference involved — and read back with chat.history: both client processes saw the same session ID and the same marker. After a normal Gateway stop (SIGTERM) and restart as a new process, both clients still read back the identical session ID and marker: the session demonstrably lives on the Gateway, not on any client. A deliberately wrong session key returned an empty result (session ID null, zero messages), confirming continuation is keyed addressing, not content matching.

Reproduce this verification (steps transcribed from the site’s live run, 2026-11-15; same environment as above):

  1. Start an isolated loopback Gateway: a scratch OPENCLAW_STATE_DIR, then openclaw gateway run --port <port> --bind loopback with token auth.
  2. Create a named session and write a marker into it:
openclaw gateway call sessions.create --params '{"key":"agent:main:repro-demo"}'
openclaw gateway call chat.inject   --params '{"sessionKey":"agent:main:repro-demo","message":"REPRO-MARKER"}'
  1. Read it back as two independent clients — the second CLI invocation with a different OPENCLAW_STATE_DIR (client B): openclaw gateway call chat.history --params '{"sessionKey":"agent:main:repro-demo","limit":10}'. Both must return the same sessionId and the marker.
  2. Stop the Gateway with SIGTERM, start a new process on the same port, repeat step 3 from both clients: session ID and marker are unchanged.
  3. Negative control: read with a wrong key (agent:main:repro-wrong) — expect sessionId: null and zero messages, proving history is addressed by key, not matched by content.

How the Gateway makes this work — the connect/event/call control plane behind these commands — is explained in 02: Control plane (WS connect/events/calls).

Not covered by that live run (still per official docs): model inference during continuation, real cross-device networking (LAN / tailnet / public exposure), mobile clients, pairing / node registration — and multi-operator or multi-agent isolation (what different credentials may read from one Gateway was not measured; see the calibration in section 3).

Failure triage — where to look first, in the order the layers above fail:

SymptomCheck firstThen
Cannot connect at allReachability: the URL, port, and bind you are dialing — curl http://<address>:18789 checks HTTP reachability of that port only; it says nothing about the WebSocket handshake or credentialsWalk layers 1→2 below; see the remote-access guide for LAN/tailnet/SSH choices
Connects, but a method call is rejectedThat you are dialing the same URL/port with the same credentials as the working call, and the actual error the rejected method returns. A successful openclaw gateway status --url … --token … only shows that this one probe was accepted — not that every method on that connection is authorizedMatch the error to its own layer per the official Gateway CLI / protocol docs: an authorization failure points at effective operator scopes, configured role ceilings, and session access checks (see layer 3 and the pinned operator-scopes docs); other call errors still need their own parameter, method-name, or version diagnosis. Only a tool blocked while executing points at the session permission mode, tools.* policy, and sandbox — don’t retune execution policy for an RPC rejection
chat.history empty or inconsistentThe exact sessionKey string (a wrong-but-well-formed key returns sessionId: null, zero messages — key addressing, not an error), and that every client dials the same Gateway and portRe-read with the exact key, then look at the Gateway’s persisted state/store and the errors or logs it returned — history lives Gateway-side, and its store is where a mismatch shows up. The experiment above ruled out one thing only: this run’s single client state directory was not the source of the shared history; it does not speak to every client-side caching implementation
History reads back, but no live events arriveThe current connection and the event path — history is persisted storage; live events belong to the connected streamSeparate “was my call ACKed” from “did the expected events arrive” (02: Control plane, section 2). History reading back does not show that events missed while disconnected will be replayed — what a reconnecting client receives is a property of the event mechanism; check your connection/subscription state and the streaming docs for your version before assuming either way

3. Four permission layers, each governing something different

“Who can do what” in a multi-device setup is the sum of four layers (the layering is this guide’s organization; each layer’s semantics come from the official docs):

  1. Network reachability: whether a device can connect at all — loopback / LAN / tailnet / public exposure choices, see Secure remote access (Chinese). Reachability grants no permissions by itself.
  2. Gateway authentication: token / password / Tailscale identity headers (Control UI and WebSocket only; HTTP APIs use normal auth). Each operator client connects with credentials; clients cache paired-device credentials per SSH target, scoped to that target plus the remote Gateway port, independent of the local port number.
  3. Method & session permissions vs. tool execution checks: RPC authorization checks the connection’s effective operator scopes, configured role ceilings, and applicable session access rules. Tool execution has separate checks, including the session permission mode, tool policy, and sandbox configuration. For an authorization error, inspect the required scope and session access for that method; other call errors still need their own parameter, method-name, or version diagnosis. For a denial during tool execution, inspect the execution policy and sandbox. (Scope semantics per the pinned operator-scopes docs, revision bf26a4c — a documentation mechanism statement, not something this site’s 847611d live run measured.)
  4. Approvals: exec approvals before host execution (allowlist/ask/standing grants); approval cards are delivered to connected approval surfaces, and any operator device can respond.

Multi-user or multi-purpose separation: different family members or purposes can use different agents (agents.entries.*) — each with its own tool allowlist, sandbox, and config; automations additionally carry their own account bindings and tool caps. That is a configuration separation (what each agent may do), backed by the official docs — this site’s experiment ran a single agent under one set of credentials and did not measure isolation between agents or operators. Treat “which credential can read which session” as an authorization question to verify in your own config, not something routing guarantees by itself.

4. Device onboarding paths (by device type)

Laptop/desktop (operator):

  • On LAN: direct ws://<gateway-ip>:18789 (requires Gateway bind + auth);
  • Remote: SSH tunnel or Tailscale (recommended — see the remote-access guide, Chinese); the macOS app’s remote mode manages the transport automatically (including the LaunchAgent persistent tunnel, see the Remote access reference page).

Phone/tablet (node or light client):

  • As a node: connect to the Gateway address in the app and complete pairing — pairing registers the device as a node of this Gateway;
  • As an operator (mobile browser / app remote mode): the same authentication chain as the laptop.

Check order (illustrative): ① can the device reach the Gateway (curl http://<address>:18789) → ② does auth pass (openclaw gateway status --url … --token …) → ③ does the session list appear → ④ did node capabilities register (openclaw nodes status).

5. Lost or replaced devices

  • Revoke device access: remove/reset the device’s pairing and cached device credentials (paired credentials are scoped per SSH target and port — replacing a device does not invalidate old credentials, so clean up deliberately);
  • Rotate the Gateway token/password: rotate everything on suspected credential leakage; all devices reconnect with new credentials;
  • Audit: openclaw logs and run history let you review what happened under that device’s credentials;
  • Node side: removing the node registration cuts off its capability exposure; a lost node device’s risk surface is its paired identity, since nodes hold no session data.

Relationship to other pages