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.