Session synchronization and attachment

OpenClaw keeps shared session state on the Gateway. The Control UI, mobile clients, ACP, openclaw tui <target>, and openclaw attach <target> project that Gateway-owned state instead of keeping independent session copies. This lets you open one session in several clients without exporting or copying its transcript.

Use openclaw tui when you want to continue the conversation in a terminal. Use openclaw attach when you want a coding harness beside the session with a temporary, session-scoped MCP grant.

Embedded local mode is separate: openclaw tui --local, openclaw chat, and openclaw terminal use the local agent runtime and cannot accept a session target. See the TUI CLI reference for local-mode behavior.

One Gateway, many clients

The Gateway owns session rows, transcript history, routing metadata, and active runs. Clients select a session key and read or update that same state through the Gateway protocol. A mobile node remains a peripheral connected to the Gateway; it does not become a second session owner.

Most agent session keys use this shape:

agent:<agentId>:<rest>

The <rest> portion may be a simple name, several colon-delimited routing segments, or a value ending in a UUID. A Gateway configured with global session scope uses the canonical global session instead. When an agent-only URL is opened against a global-scope Gateway, the CLI asks the Gateway for its session scope and resolves the URL to that canonical global session.

See Session management for routing, isolation, lifecycle, and storage details.

Session URLs and short links

Control UI chat and dashboard links share this route grammar:

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

A configured Control UI base path prefixes these routes. The agent-only form opens that agent's main projection. Literal forms encode the colon-delimited session key after agent:<agentId>: as path segments.

For a key whose rest ends in a UUID, the shareable short form uses 8 to 32 lowercase hexadecimal characters from the start of that UUID, with UUID dashes removed. The short ID is authoritative. The display-name slug is decorative unless two sessions share the same prefix, in which case one exact slug match breaks the tie. For CLI short-link targets, the agent segment is also decorative: the Gateway resolves the short ID without constraining it to that URL agent.

The Gateway method sessions.resolve owns resolution for exact keys, raw session IDs, labels, and short IDs. Discovery selectors are filtered by the calling client's session visibility. Short-ID ambiguity results contain at most ten recent candidates, so clients can ask you for a longer prefix without guessing. See Control UI URLs for the complete literal encoding and stability contract.

Current and older Gateways

Current Gateways resolve short references at the session store owner. The Control UI and CLI then use the returned canonical key.

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

Choose how to continue

The CLI accepts three target syntaxes:

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

Session URLs must not contain credentials. Pass --token or --password separately when first pairing with a Gateway origin.

Continue in the terminal

For Gateway-backed continuation, pass the URL or reference to openclaw tui:

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

You can also paste a complete session URL directly at the CLI root:

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

This opens the TUI on the canonical session key returned by the Gateway. It does not clone the transcript or create a new session. See TUI for target conflicts, supported bare-URL options, and examples.

Attach a coding harness

Pass the same URL or reference to openclaw attach:

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

The Gateway resolves the session first, then mints a temporary grant scoped to that session and launches the coding harness with a strict MCP configuration. The bearer token travels in the child environment instead of argv. A normal launch revokes the grant when the harness exits; --print-config leaves it live until its TTL expires. See Attach CLI for grant lifetime and launch options.

Pair once per Gateway origin

A URL or gateway shorthand authoritatively selects one normalized Gateway origin. OpenClaw never reuses configured credentials or a stored device token from another origin for that target.

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.

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.

See Devices, Remote access, and Gateway security for approval, rotation, revocation, and network guidance.

Failure taxonomy

Gateway connection failures use one structured-first classifier. Older Gateways still work through a bounded text fallback, so health, status, and the TUI give the same category and recovery guidance.

Related pages

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