From 63b13c7e2fe5bacb17a6a19979c1952be48bd200 Mon Sep 17 00:00:00 2001 From: baccula Date: Sun, 1 Feb 2026 08:03:55 -0800 Subject: [PATCH] docs: add device pairing section to Control UI docs (#5003) * docs: add device pairing section to Control UI docs Explains that new browser connections require one-time pairing approval, what error message users will see, and how to approve devices using the CLI. This was a gap in the documentation that caused confusion for users connecting via Tailscale Serve. * docs: clarify Control UI pairing error * docs: clarify device revoke flags --------- Co-authored-by: Lucifer (via OpenClaw) Co-authored-by: Sebastian --- docs/web/control-ui.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 4972b84f443..2a68921c29a 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -30,6 +30,35 @@ Auth is supplied during the WebSocket handshake via: The dashboard settings panel lets you store a token; passwords are not persisted. The onboarding wizard generates a gateway token by default, so paste it here on first connect. +## Device pairing (first connection) + +When you connect to the Control UI from a new browser or device, the Gateway +requires a **one-time pairing approval** — even if you're on the same Tailnet +with `gateway.auth.allowTailscale: true`. This is a security measure to prevent +unauthorized access. + +**What you'll see:** "disconnected (1008): pairing required" + +**To approve the device:** + +```bash +# List pending requests +openclaw devices list + +# Approve by request ID +openclaw devices approve +``` + +Once approved, the device is remembered and won't require re-approval unless +you revoke it with `openclaw devices revoke --device --role `. See +[Devices CLI](/cli/devices) for token rotation and revocation. + +**Notes:** +- Local connections (`127.0.0.1`) are auto-approved. +- Remote connections (LAN, Tailnet, etc.) require explicit approval. +- Each browser profile generates a unique device ID, so switching browsers or + clearing browser data will require re-pairing. + ## What it can do (today) - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)