From eb332c2f32ffbb840dc4283398fbcecf70227cea Mon Sep 17 00:00:00 2001
From: Arnav Panicker <117341727+addu2612@users.noreply.github.com>
Date: Wed, 29 Apr 2026 08:42:51 +0530
Subject: [PATCH] docs: encode Control UI gatewayUrl examples

Squashed from PR #60773 after maintainer closeout.\n\nValidation:\n- Testbox tbx_01kqbkfn9nqpspssrveg5t3mrr: pnpm docs:list; OPENCLAW_TESTBOX=1 pnpm check:changed (docs-only)\n- Exact-head CI: https://github.com/openclaw/openclaw/actions/runs/25040057222
---
 docs/web/control-ui.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md
index 5f933476c24..e5bba9bf971 100644
--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@@ -398,13 +398,13 @@ The Control UI is static files; the WebSocket target is configurable and can be
   </Step>
   <Step title="Open with gatewayUrl">
     ```text
-    http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
+    http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
     ```
 
     Optional one-time auth (if needed):
 
     ```text
-    http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>
+    http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
     ```
 
   </Step>
@@ -413,6 +413,7 @@ The Control UI is static files; the WebSocket target is configurable and can be
 <AccordionGroup>
   <Accordion title="Notes">
     - `gatewayUrl` is stored in localStorage after load and removed from the URL.
+    - If you pass a full `ws://` or `wss://` endpoint via `gatewayUrl`, URL-encode the `gatewayUrl` value so the browser parses the query string correctly.
     - `token` should be passed via the URL fragment (`#token=...`) whenever possible. Fragments are not sent to the server, which avoids request-log and Referer leakage. Legacy `?token=` query params are still imported once for compatibility, but only as a fallback, and are stripped immediately after bootstrap.
     - `password` is kept in memory only.
     - When `gatewayUrl` is set, the UI does not fall back to config or environment credentials. Provide `token` (or `password`) explicitly. Missing explicit credentials is an error.