Documentation
Practical Guides
Using OpenClaw from Multiple Devices: Session Sync and Permission Layers

Using OpenClaw from Multiple Devices: Session Sync and Permission Layers

This is an original guide. Facts come from the local Remote access, Sandbox, tool policy, and elevated, Automation payloads, and Exec approvals pages (checked against the fixed official snapshot, 2026-11-06); no new external claims are introduced. Examples are illustrative and have not been run.

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, credentials, channels, and state all live on the Gateway; every device is just a client. Once that 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 clear answers.

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:

  • Any authenticated operator client that connects sees the same session list and history;
  • 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).

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. Session and tool policy: what tools can be called and whether sandboxing applies after connecting — tools.* tool policy, agents.*.sandbox, session permission modes, and operator roles (including required sandboxes that elevated execution cannot bypass).
  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 isolation: 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. One Gateway can host both “the family assistant” and “your work agent” without crossing boundaries.

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