mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-19 17:11:42 -06:00
Peter Steinberger
45e6784338
* 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
114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
---
|
|
summary: "Connect a machine to an OpenClaw Gateway with one pasted command"
|
|
read_when:
|
|
- Pairing a new headless node with a Gateway
|
|
- Installing a node host from a join URL or setup code
|
|
title: "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`](/cli/node).
|
|
|
|
## Create a join command
|
|
|
|
On the Gateway host, use admin credentials to mint a single-use join URL:
|
|
|
|
```bash
|
|
openclaw devices join-code
|
|
```
|
|
|
|
The command prints the URL and a pasteable command:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npx openclaw connect https://gateway.example/j/<shortcode>
|
|
```
|
|
|
|
Set the device name during enrollment when useful:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](/cli/node#service-background) 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>`](/cli/devices#openclaw-devices-remove-%3Cdeviceid%3E).
|
|
- 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](/cli/node) for service management, explicit connection flags, node
|
|
state, and exec approval behavior.
|