Session Synchronization and Attachment Across Clients

OpenClaw stores shared session state on the Gateway. Instead of maintaining separate session copies, the Control UI, mobile clients, ACP, openclaw tui <target>, and openclaw attach <target> project that Gateway-owned state. As a result, you can have one session open across multiple clients without exporting or duplicating its transcript.

For continuing the conversation in a terminal, reach for openclaw tui. When you need a coding harness alongside the session with a temporary, session-scoped MCP grant, use openclaw attach.

Embedded local mode works differently: openclaw tui --local, openclaw chat, and openclaw terminal rely on the local agent runtime and cannot take a session target. Local-mode behavior is covered in the TUI CLI reference.

One Gateway, many clients

Session rows, transcript history, routing metadata, and active runs all live on the Gateway. Through the Gateway protocol, clients pick a session key and read or update that shared state. A mobile node acts as a peripheral attached to the Gateway, never as a second session owner.

Agent session keys generally follow this pattern:

agent:<agentId>:<rest>

The <rest> part can be a plain name, several colon-delimited routing segments, or a value that ends in a UUID. When the Gateway is set to global session scope, the canonical global session is used instead. If an agent-only URL hits a global-scope Gateway, the CLI asks that Gateway for its session scope and maps the URL to the canonical global session.

Routing, isolation, lifecycle, and storage details appear in Session management.

Session URLs and short links

Control UI chat and dashboard links all follow this route grammar:

/{chat|dashboard}/<agentId>
/{chat|dashboard}/<agentId>/<slug>-<shortId>
/{chat|dashboard}/<agentId>/<literal-rest-segments...>

These routes are prefixed by a configured Control UI base path. The agent-only form opens the main projection for that agent. Literal forms encode the colon-delimited session key after agent:<agentId>: as path segments.

When a key's rest ends in a UUID, the shareable short form takes 8 to 32 lowercase hexadecimal characters from the start of that UUID, minus the dashes. The short ID carries authority. The display-name slug is purely decorative unless two sessions share the same prefix, in which case a single exact slug match settles the tie. For CLI short-link targets, the agent segment is likewise decorative: the Gateway resolves the short ID without restricting it to that URL agent.

Exact keys, raw session IDs, labels, and short IDs are all resolved by the Gateway method sessions.resolve. Discovery selectors get filtered by the calling client's session visibility. When short-ID ambiguity arises, results cap at ten recent candidates, so clients can request a longer prefix from you rather than guessing. The full literal encoding and stability contract live in Control UI URLs.

Current and older Gateways

Short references are resolved by current Gateways at the session store owner. Afterward, the Control UI and CLI use the returned canonical key.

An older Gateway might reject the additive shortId selector. In that case the Control UI can fall back to its older bounded list search, scanning at most five pages. The CLI does not replicate that paging policy: it instructs you to copy the full session key from that Gateway's Control UI or to upgrade the Gateway.

Choose how to continue

Three target syntaxes are accepted by the CLI:

• A full Control UI URL, for example https://claw.example.com/dashboard/main/deploy-monitor-6db92d48.
• Gateway shorthand, for example claw.example.com/main/deploy-monitor-6db92d48.
• A bare short reference or full key, for example deploy-monitor-6db92d48 or agent:main:telegram:12345. Bare references go through the configured or default Gateway.

Credentials must never appear in session URLs. When first pairing with a Gateway origin, pass --token or --password separately.

Continue in the terminal

In the Control UI, open the session header menu and pick Continue in terminal…. The dialog copies a credential-free openclaw resume command that carries one opaque, versioned handoff argument. That argument encodes only the exact agent-qualified session key and the selected Gateway WebSocket URL. The key is limited to 512 user-perceived characters. Its URL-safe alphabet requires no shell quoting, so the command pastes safely into common POSIX shells, PowerShell, and cmd.exe. Run it in an OpenClaw CLI profile already configured for that Gateway; the terminal authenticates on its own. Before the TUI attaches, the Gateway canonicalizes the key, and a missing session triggers recovery guidance rather than creating a new one. The session ACL still applies.

Query-routed Gateway URLs cannot yield this credential-free command because Gateway authentication and stored device scope are not query-aware. The Control UI neither strips nor copies the query. Use a manually authenticated CLI target with explicit --token or --password, or set up a queryless Gateway URL.

A recent session can also be chosen or queried directly:

openclaw resume
openclaw resume agent:main:deploy-monitor

To continue from a URL or short reference via the Gateway, hand the target to openclaw tui:

openclaw tui https://claw.example.com/dashboard/main/deploy-monitor-6db92d48
openclaw tui deploy-monitor-6db92d48

A complete session URL can also be pasted straight at the CLI root:

openclaw https://claw.example.com/dashboard/main/deploy-monitor-6db92d48

This launches the TUI on the canonical session key returned by the Gateway. The transcript is not cloned and no new session is created. Target conflicts, supported bare-URL options, and examples are documented in TUI.

Attach a coding harness

Give the same URL or reference to openclaw attach:

openclaw attach https://claw.example.com/dashboard/main/deploy-monitor-6db92d48
openclaw attach deploy-monitor-6db92d48

The Gateway resolves the session first, then mints a temporary grant scoped to that session and starts the coding harness with a strict MCP configuration. The bearer token goes into the child environment rather than argv. In a normal launch the grant is revoked when the harness exits; --print-config keeps it live until its TTL runs out. Grant lifetime and launch options are covered in Attach CLI.

Pair once per Gateway origin

A URL or gateway shorthand authoritatively picks one normalized Gateway origin. OpenClaw never reuses configured credentials or a stored device token from another origin for that target. The credential-free command copied by Continue in terminal… follows a narrower rule: openclaw resume may reuse the current CLI profile only when its explicit WebSocket URL matches byte-for-byte that profile's mode: local and public-origin targets are eligible only in local mode, while remote mode allows only gateway.remote.url. Other profiles are never searched, and any host, port, or path mismatch falls back to the normal explicit-credential requirement. Exact direct-local targets may reuse the local listener's certificate fingerprint, and exact configured remote targets may reuse the configured remote pin. A public-origin target does not inherit the local listener's pin; pass --tls-fingerprint explicitly if that proxy origin needs one. The payload holds no credentials; explicit --token, --password, or --tls-fingerprint values supplied beside the handoff still take priority. Handoff resolution suppresses ambient OPENCLAW_GATEWAY_TOKEN and OPENCLAW_GATEWAY_PASSWORD fallback while keeping those explicit values and exact-target configured credentials eligible.

On first contact:

1. Run the TUI or attach command with --token or --password once.
2. Open Settings > Devices in that Gateway's Control UI and approve the pending request. On the Gateway host, you can instead preview the newest request with openclaw devices approve --latest, verify it, and run the printed openclaw devices approve <requestId> command.
3. Retry the original command. OpenClaw stores the issued operator device token in SQLite under that exact normalized Gateway origin.
4. Later connections to the same origin can use the stored device token. An explicit --token or --password always wins for the entire connection.

The Control UI continuation command skips these first-contact steps and carries none of their credentials. Configure or pair the terminal independently before using it. If the CLI rejects an invalid or truncated handoff, copy a fresh command from the Control UI instead of editing the opaque argument. If the session was deleted after the command was copied, return to the Control UI and copy a command from an available session.

Revoke or remove the device from the same Gateway's Devices page when that client should no longer connect. Tokens do not cross origins. Read-only probes through an SSH tunnel also suppress stored device auth because the loopback transport does not identify the remote origin; explicit credentials still work.

For guidance on approval, rotation, revocation, and networking, consult Devices, Remote access, and Gateway security.

Failure taxonomy

Gateway connection failures rely on a single structured-first classifier. Older Gateways remain compatible through a constrained text fallback, so the TUI, health, and status all present the same category and recovery steps.

Related pages

• Session management
• Control UI URLs
• TUI
• Attach CLI
• Devices
• Remote access
• Gateway security