Connect a Machine to an OpenClaw Gateway with One Command

openclaw connect

As a headless node, link the machine you are on to an OpenClaw Gateway. A short-lived bootstrap credential gets redeemed by the command, the Gateway endpoint is written into the node-host state that already exists, and the identical runtime to openclaw node run gets executed.

Create a join command

With admin credentials on the Gateway host, generate a join URL meant for one-time use:

openclaw devices join-code

Both the URL and a command that can be pasted are shown by the command:

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

Entropy of 128 bits is packed into the shortcode, which lapses along with the setup credential in roughly 10 minutes, and only a single fetch is permitted. If it lapses or was already redeemed, produce another code.

Connect in the foreground

On the machine to be connected, paste the printed command:

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

During enrollment, assign the device name when it helps:

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

Until you halt it, the node runs in the foreground.

Explicit local consent is needed for that foreground process to host full worker sessions, provided via --session-host:

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

Only that specific process is affected by foreground consent. openclaw.json remains unchanged, so the following standard node-host launch continues without hosting.

Environment-managed cloud nodes

For disposable cloud machines, worker providers rely on --ephemeral:

npx openclaw connect <setup-code> --ephemeral

Even when worker hosting is disabled in the machine's persistent node config, this process still hosts worker sessions. No service gets installed, and pairing with --service or --session-host is not possible. Ownership of the setup identity and the paired-node lifetime rests with the Gateway: after the one-time setup credential is spent, provider replay resumes the stored device token, and when the cloud lease is released, environment teardown strips the node role.

For provider-managed state directories on throwaway machines, --ephemeral is the intended fit, not a shortcut to enroll a personal device.

Install as a service

Hand over --service to redeem the bootstrap credential and set up the node host as the platform user service:

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

Before the service is installed, OpenClaw finishes the first authenticated connection. Neither the service command nor the node-host configuration ever stores the short-lived bootstrap token; subsequent launches rely on the durable paired-device token. Use openclaw node status to look at the installed service.

By default, worker sessions are not hosted by the service. To agree to full worker-session hosting, include --session-host:

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

Without advertising worker hosting, the one-shot bootstrap connection authenticates and stores the durable device identity. Only once that connection succeeds does OpenClaw write nodeHost.workerRuns.enabled=true, keeping the rest of the config intact, and install the service. Service installation stays dormant if the config write fails. On startup, the installed service advertises worker hosting and exact capacity based on this durable consent.

Accepted targets

Accepted by openclaw connect <target> are:

• a join URL of the https://<gateway>/j/<shortcode> kind;
• a URL in the oc-pair://<setup-code> form;
• a setup code that is bare base64url.

From a private file, --target-file <path> pulls the target and deletes that file after reading it. Through this handoff, the dormant installer wrapper keeps the single-use target out of child-process arguments.

HTTPS is mandatory for join URLs. Only loopback Gateway URLs such as http://127.0.0.1/j/<shortcode> accept plain HTTP. A Gateway TLS certificate fingerprint can ride along in direct setup codes, letting the node host pin a self-signed Gateway certificate once the payload is decoded.

What gets saved, including host, port, TLS mode, WebSocket context path, and ordered fallback endpoints, is dictated by the payload. No openclaw.json keys are added by normal and foreground connections; the worker hosting consent described above is explicitly persisted by --service --session-host.

Revocation behavior

Separate lifecycles govern a join code and a paired device:

• A join code that is burned or expired blocks any further enrollment with it.
• A node that already redeemed it stays connected and intact.
• To revoke a normally enrolled machine, delete its paired device with openclaw devices remove <deviceId>.
• When the owning cloud environment is destroyed, environment-managed --ephemeral nodes are removed on their own.

Troubleshooting

If the join URL indicates it is missing or expired, mint a fresh one with openclaw devices join-code. A code that was already used deliberately returns the same result as one that is unknown.

When an HTTPS join URL presents a certificate the local machine does not trust, go with the direct oc-pair:// or bare setup-code form that carries the TLS pin.

For service management, explicit connection flags, node state, and exec approval behavior, see Node.