From 6c6bc6ff1ce4d7133f1a46913b0a466cea30bae6 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 16 Jan 2026 09:01:45 +0000
Subject: [PATCH] fix: add control UI auth guidance

---
 CHANGELOG.md                |  1 +
 ui/src/ui/views/overview.ts | 49 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2d827a08e..57a5b003f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@
 - Onboarding: switch channels setup to a single-select loop with per-channel actions and disabled hints in the picker.
 - TUI: show provider/model labels for the active session and default model.
 - Heartbeat: add per-agent heartbeat configuration and multi-agent docs example.
+- UI: show gateway auth guidance + doc link on unauthorized Control UI connections.
 - Fix: list model picker entries as provider/model pairs for explicit selection. (#970) — thanks @mcinteerj.
 - Fix: align OpenAI image-gen defaults with DALL-E 3 standard quality and document output formats. (#880) — thanks @mkbehr.
 - Fix: persist `gateway.mode=local` after selecting Local run mode in `clawdbot configure`, even if no other sections are chosen.
diff --git a/ui/src/ui/views/overview.ts b/ui/src/ui/views/overview.ts
index 4664a7312..fa03ca9c1 100644
--- a/ui/src/ui/views/overview.ts
+++ b/ui/src/ui/views/overview.ts
@@ -31,6 +31,52 @@ export function renderOverview(props: OverviewProps) {
   const tick = snapshot?.policy?.tickIntervalMs
     ? `${snapshot.policy.tickIntervalMs}ms`
     : "n/a";
+  const authHint = (() => {
+    if (props.connected || !props.lastError) return null;
+    const lower = props.lastError.toLowerCase();
+    const authFailed = lower.includes("unauthorized") || lower.includes("connect failed");
+    if (!authFailed) return null;
+    const hasToken = Boolean(props.settings.token.trim());
+    const hasPassword = Boolean(props.password.trim());
+    if (!hasToken && !hasPassword) {
+      return html`
+        <div class="muted" style="margin-top: 8px;">
+          This gateway requires auth. Add a token or password, then click Connect.
+          <div style="margin-top: 6px;">
+            <span class="mono">clawdbot dashboard --no-open</span> → tokenized URL<br />
+            <span class="mono">clawdbot doctor --generate-gateway-token</span> → set token
+          </div>
+          <div style="margin-top: 6px;">
+            <a
+              class="session-link"
+              href="https://docs.clawd.bot/web/dashboard"
+              target="_blank"
+              rel="noreferrer"
+              title="Control UI auth docs (opens in new tab)"
+              >Docs: Control UI auth</a
+            >
+          </div>
+        </div>
+      `;
+    }
+    return html`
+      <div class="muted" style="margin-top: 8px;">
+        Auth failed. Re-copy a tokenized URL with
+        <span class="mono">clawdbot dashboard --no-open</span>, or update the token,
+        then click Connect.
+        <div style="margin-top: 6px;">
+          <a
+            class="session-link"
+            href="https://docs.clawd.bot/web/dashboard"
+            target="_blank"
+            rel="noreferrer"
+            title="Control UI auth docs (opens in new tab)"
+            >Docs: Control UI auth</a
+          >
+        </div>
+      </div>
+    `;
+  })();
 
   return html`
     <section class="grid grid-cols-2">
@@ -119,7 +165,8 @@ export function renderOverview(props: OverviewProps) {
         </div>
         ${props.lastError
           ? html`<div class="callout danger" style="margin-top: 14px;">
-              ${props.lastError}
+              <div>${props.lastError}</div>
+              ${authHint ?? ""}
             </div>`
           : html`<div class="callout" style="margin-top: 14px;">
               Use Connections to link WhatsApp, Telegram, Discord, Signal, or iMessage.