mirror of https://github.com/openclaw/openclaw.git synced 2026-08-19 09:01:39 -06:00

Files

T

Peter Steinberger 45e6784338 feat(gateway): run disposable cloud workers through node transport (#125288 )

* feat(gateway): converge cloud workers onto nodes

* fix(gateway): honor public URL for cloud enrollment

* fix(crabbox): execute cloud bootstrap package binary

* fix(gateway): bind cloud nodes in pairing transaction

* fix(crabbox): prefer exact installed cloud bootstrap

* fix(gateway): complete cloud node bootstrap

* fix(gateway): enforce cloud worker capability boundaries

* fix(gateway): complete cloud node migration

* fix(gateway): preserve paired node roles on teardown

2026-08-17 11:49:06 -07:00

4.1 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Connect a machine to an OpenClaw Gateway with one pasted command

Pairing a new headless node with a Gateway

Installing a node host from a join URL or setup code

Connect

`openclaw 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:

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

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

Paste the printed command on the machine you want to connect:

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.

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. 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. Use openclaw node status to inspect the installed service.

Accepted targets

openclaw connect <target> accepts:

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

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. No additional openclaw.json keys are created.

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 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.

4.1 KiB Raw Blame History

openclaw connect