> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices join-code ``` The command prints the URL and a pasteable command: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ ``` 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ ``` Set the device name during enrollment when useful: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ --display-name "Build Node" ``` The node stays in the foreground until you stop it. To let that foreground process host full worker sessions, give explicit local consent with `--session-host`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ --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. ## Environment-managed cloud nodes Worker providers use `--ephemeral` for disposable cloud machines: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect --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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ --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. The service does not host worker sessions by default. To consent to full worker-session hosting, add `--session-host`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npx openclaw connect https://gateway.example/j/ --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 ` accepts: * an `https:///j/` join URL; * an `oc-pair://` URL; * a bare base64url setup code. `--target-file ` 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/`. 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 `](/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.