Resume a Gateway Session with OpenClaw CLI

openclaw resume

Connect the terminal interface to a Gateway session that already exists. The session remains on the Gateway; resume picks it and launches the current TUI.

openclaw resume
openclaw resume <query>
openclaw resume --handoff <payload>

Without a query, OpenClaw lists up to 50 sessions that were active during the last seven days. When a query is supplied, an exact session key takes priority; otherwise, OpenClaw demands a unique substring or fuzzy match across session keys, display names, and labels.

The picker skips bare global rows since they don't point to an owning agent. To attach, supply a fully qualified key like openclaw resume agent:main:global.

An ambiguous query makes OpenClaw show the matching candidates and exit with status 1. If no recent session matches, it recommends the picker and openclaw sessions, then exits with status 1.

Options

--handoff can't be paired with a positional query or --url because it authoritatively provides both. It can be paired with --token, --password, and --tls-fingerprint; those explicit authentication values keep their usual highest priority.

resume never launches a Gateway on its own. If the configured Gateway is unreachable, start or fix it and run the command again.

resume resolves configured Gateway auth SecretRefs for token/password auth when possible (env/file/exec/store providers).

When --handoff is present, it supplies the target Gateway URL. Otherwise, Gateway target precedence is explicit --url, then OPENCLAW_GATEWAY_URL, then gateway.remote.url when gateway.mode is remote, then the local loopback Gateway. For that local Gateway, OPENCLAW_GATEWAY_PORT takes precedence over the active port recorded by a running Gateway, which takes precedence over the configured or default gateway.port.

An explicit target usually requires an explicit --token or --password; OpenClaw does not borrow credentials or a TLS pin from a different configured target. resume has one narrow exception for a handoff copied from the Control UI: when its Gateway URL byte-for-byte matches a canonical target of the current profile, it may reuse that profile's configured interactive auth, SecretRef, and stored exact-origin device auth. In local mode, the eligible targets are the current local target with gateway.controlUi.basePath and gateway.publicOrigin converted to WebSocket form with that base path. In remote mode, only the exact gateway.remote.url is eligible. TLS pin ownership is narrower: an exact direct-local target may reuse the local Gateway certificate fingerprint, and an exact configured remote target may reuse gateway.remote.tlsFingerprint; a public-origin target never inherits the local listener's pin. Pass --tls-fingerprint explicitly when that public origin needs a pin. A host, port, path, profile, query, or fragment mismatch fails closed under the normal explicit-target policy. OpenClaw never scans other profiles for a match. Handoff connections also ignore ambient OPENCLAW_GATEWAY_TOKEN and OPENCLAW_GATEWAY_PASSWORD fallback, so shell credentials for another Gateway cannot cross into the selected target. Explicit flags and credentials owned by an exact configured target remain eligible.

Continue from the Control UI

Open the selected session's header menu and pick Continue in terminal…. The dialog shows one copyable openclaw resume --handoff <payload> command. The opaque payload is versioned, bounded, and encoded with an unpadded URL-safe base64 alphabet, so the command needs no quoting and is safe to paste in common POSIX shells, PowerShell, and cmd.exe. The encoded argument is limited to 4096 characters; inside it, the agent-qualified session key is limited to 512 user-perceived characters and the Gateway URL to 2048 characters. It contains only the exact qualified session key and selected Gateway WebSocket URL, including any Control UI base path. It contains no token, password, device credential, or bootstrap credential, and the browser does not execute it.

The Control UI does not offer this command when the selected Gateway URL uses a query string. Gateway authentication and stored device scope are origin-based, not query-aware, so OpenClaw never strips or copies that query into a credential-free handoff. Use a manually authenticated CLI target with explicit --token or --password, or configure a queryless Gateway URL.

Run the command in an already configured OpenClaw terminal. The terminal authenticates independently. Before opening the TUI, resume asks that Gateway to resolve the qualified key and uses the returned canonical key. A deleted or stale session stops with guidance to copy a fresh command; it never starts a new session. The Gateway's session access controls remain authoritative. This flow continues an existing session; it does not delegate first-use authentication from the browser.

If OpenClaw reports an invalid --handoff payload, return to the session's Control UI menu and copy a fresh command. Do not edit or reuse a truncated payload.

Examples

# Choose from recent sessions
openclaw resume

# Exact key
openclaw resume agent:main:bugfix

# Unique display-name or label fragment
openclaw resume bugfix

# Remote Gateway override
openclaw resume bugfix --url wss://gateway.example.com --token <token>

# Opaque command copied from the Control UI
openclaw resume --handoff <payload>

Related

• TUI
• Sessions
• TUI guide