Connect

Connect the current machine to an OpenClaw Gateway as a headless node. The command redeems a short-lived bootstrap credential, saves the Gateway endpoint in the existing node-host state, and runs the same runtime as openclaw node run.

Create a join command

On the Gateway host, use admin credentials to mint a single-use join URL:

openclaw devices join-code

The command prints the URL and a pasteable command that installs a background node service and enables it to run agent sessions:

npx -y openclaw@<gateway-version> connect https://gateway.example/j/<shortcode> --service --session-host

Only use session hosting on a machine you trust as shared Gateway infrastructure. The printed command makes that consent explicit with --session-host; the node runtime's default remains non-hosting. See Session hosting. For a command-only node, omit --session-host and keep --service. The -y flag skips npm's package-install confirmation, not OpenClaw pairing or session-hosting consent.

The Gateway chooses its own published npm version, even when you run devices join-code from a different CLI version. Source checkouts and unpublished builds use a resolvable matching release-channel tag when available, otherwise unpinned openclaw, with a note to use a matching Gateway build. Registry checks are bounded to two seconds; an unavailable registry also shows the matching-build note.

Already have OpenClaw installed? Run: openclaw connect <join-url> --service --session-host. This uses your installed build instead of npx; make sure it matches the Gateway.

The shortcode has 128 bits of entropy, expires with the setup credential after about 10 minutes, and can be fetched exactly once. Mint another code if it expires or has already been used.

Connect in the foreground

To connect without installing a service, omit --service and --session-host:

npx openclaw connect https://gateway.example/j/<shortcode>

Set the device name during enrollment when useful:

npx openclaw connect https://gateway.example/j/<shortcode> --display-name "Build Node"

The node stays in the foreground until you stop it.

To expose only selected commands, pass a comma-separated list of exact command IDs. For a Session Share node:

openclaw connect <join-url> \
  --commands openclaw.sessions.list.v1,openclaw.sessions.read.v1

The flag is repeatable. The allowlist is durable node state and also applies after --service installation; omitting it preserves a saved list. It filters available commands and their required capabilities, and disables computer use, skills, plugin-tool publication, MCP servers, and worker hosting. Startup fails when no requested command is available. The Gateway pairing approval shows the resulting declared commands.

To restore the full default surface, use openclaw node run --all-commands for a foreground node or openclaw node install --force --all-commands for an installed service. When enrolling again, use openclaw connect <join-url> --all-commands (add --service for a service). This forgets the saved allowlist; --all-commands cannot be combined with --commands.

To let that foreground process host full worker sessions, give explicit local consent with --session-host:

npx openclaw connect https://gateway.example/j/<shortcode> --session-host

Foreground consent applies only to that process. It does not change openclaw.json, so the next normal node-host start remains non-hosting.

Reconnect a paired node

Join URLs and setup codes are single-use, so rerunning the original openclaw connect <join-url> command after the node stops reports that the join code was not found or has expired. The node keeps its paired device token and Gateway endpoint in node-host state. Reconnect with openclaw node run, repeating any process-scoped flags:

openclaw node run --session-host

Running openclaw connect without a target does not connect. When node-host state has a saved Gateway endpoint and a node device token, it exits with an error that prints the matching openclaw node run command for the flags you passed, to use if that pairing is still current, and the openclaw connect command to use with a new join URL otherwise. With --service, it prints openclaw node install --force instead, preceded by openclaw config set nodeHost.workerRuns.enabled true when you also passed --session-host. If the first enrollment never completed, it only points to a new join URL. The device token is not tied to one endpoint: after a failed enrollment with a different Gateway, the reconnect command can fail, so enroll again instead. To enroll the machine again, mint a new join URL with openclaw devices join-code.

Environment-managed cloud nodes

Worker providers use --ephemeral for disposable cloud machines:

npx openclaw connect <setup-code> --ephemeral

This process hosts worker sessions even when the machine's durable node config has worker hosting disabled. It does not install a service and cannot be combined with --service or --session-host. The Gateway owns the setup identity and paired-node lifetime: provider replay resumes the persisted device token after the one-shot setup credential is consumed, and environment teardown removes the node role after releasing the cloud lease.

--ephemeral is intended for provider-managed state directories on throwaway machines, not as a shortcut for enrolling a personal device.

Install as a service

Pass --service to redeem the bootstrap credential and install the node host as the platform user service:

npx openclaw connect https://gateway.example/j/<shortcode> --service

OpenClaw completes the first authenticated connection before installing the service. The short-lived bootstrap token is never stored in the service command or node-host configuration; later starts use the durable paired-device token. When restarting against that saved endpoint, ambient Gateway credentials from the environment or a co-located Gateway's config do not override the pairing. For an intentional shared-credential override, use openclaw node run --auth-from-env or openclaw node install --auth-from-env --force; see node-host authentication. Use openclaw node status to inspect the installed service.

When run through npx, service installation first installs the selected OpenClaw release into npm under the node's state directory. The service uses that durable installation, not npm's temporary _npx cache. The installation output shows the package version, chosen runtime, service command, and a node update command:

npx -y openclaw@latest node install --force

Run it on the node machine with the same profile and state-directory settings. It promotes the selected release into the same prefix and rewrites the service, without redeeming another join URL. Use openclaw@beta or an exact version in place of openclaw@latest when needed. Reinstalling the same version also repairs missing package files. This targets the node even when a separate Gateway is installed on the machine.

The service does not host worker sessions by default. To consent to full worker-session hosting, add --session-host:

npx openclaw connect https://gateway.example/j/<shortcode> --service --session-host

The one-shot bootstrap connection authenticates and saves the durable device identity without advertising worker hosting. Only after that connection succeeds does OpenClaw persist nodeHost.workerRuns.enabled=true, preserving the rest of the config, and install the service. If the config write fails, service installation does not start. The installed service advertises worker hosting and exact capacity from this durable consent when it starts.

Accepted targets

openclaw connect <target> accepts:

• an https://<gateway>/j/<shortcode> join URL;
• an oc-pair://<setup-code> URL;
• a bare base64url setup code.

--target-file <path> accepts a regular file up to 64 KiB. It removes the path only after reading a non-empty target. If the file is empty, too large, unreadable, or not a regular file, OpenClaw leaves it in place. A symlink is allowed; OpenClaw reads its target, removes the symlink after a successful read, and keeps the backing file. The dormant installer wrapper uses this handoff to keep the single-use target out of child-process arguments.

Join URLs must use HTTPS. Plain HTTP is accepted only for loopback Gateway URLs such as http://127.0.0.1/j/<shortcode>. Direct setup codes can carry the Gateway TLS certificate fingerprint, which lets the node host pin a self-signed Gateway certificate after decoding the payload.

The payload determines the saved host, port, TLS mode, WebSocket context path, and ordered fallback endpoints. Normal and foreground connections do not add openclaw.json keys; --service --session-host explicitly persists the worker hosting consent described above.

Revocation behavior

A join code and a paired device have separate lifecycles:

• Burning or expiring a join code prevents another enrollment with that code.
• It does not disconnect or remove a node that already redeemed it.
• To revoke a normal enrolled machine, remove its paired device with openclaw devices remove <deviceId>.
• Environment-managed --ephemeral nodes are removed automatically when their owning cloud environment is destroyed.

Troubleshooting

If the join URL reports that it is missing or expired, mint a new one with openclaw devices join-code. A used code intentionally returns the same result as an unknown code. If this machine already redeemed it, reconnect with the saved pairing instead; see Reconnect a paired node.

If an HTTPS join URL uses a certificate the local machine does not trust, use the direct oc-pair:// or bare setup-code form that includes the TLS pin.

See Node for service management, explicit connection flags, node state, and exec approval behavior.