feat: add runtime seam, Hermes adapter support, and demo gateway mode (#89)

* fix: include kanbanImmersive in immersiveOverlayActive calculation When Kanban board is open, HUD elements (camera preset buttons, edit toolbar, overlays) should be suppressed. The kanbanImmersive flag was defined but not included in the immersiveOverlayActive condition, causing HUD elements to remain visible. This fix adds kanbanImmersive to the immersiveOverlayActive calculation so HUD elements are properly hidden when the Kanban board is open. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * Fix: Hide mini status bar when Kanban immersive overlay is open Wraps the bottom-left mini status bar (showing agent stats, vibe score, and control hints) with !immersiveOverlayActive check to match the behavior of other HUD elements like camera controls and toolbar. This ensures the status bar is properly hidden when the Kanban board or any other immersive overlay is active, maintaining a clean immersive experience. Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * chore: drop unrelated package-lock line from branch Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> * universal-backend-plan * backend-neutral runtime seam * package.json update * feat: add Hermes gateway adapter as alternative to OpenClaw Adds a WebSocket adapter that lets Claw3D connect to a Hermes AI agent runtime without any changes to the frontend. The adapter implements the full Claw3D gateway protocol and bridges it to the Hermes HTTP API. Changes: - server/hermes-gateway-adapter.js: WebSocket bridge implementing the Claw3D gateway protocol against the Hermes HTTP API. Supports all core methods (agents, sessions, chat streaming, cron, config, files, approvals) and multi-agent orchestration via spawn_agent/delegate_task tools. Persists conversation history to ~/.hermes/clawd3d-history.json. - scripts/clawd3d-start.sh: All-in-one startup script that launches Hermes, the adapter, and the Next.js dev server with auto port conflict resolution. Alias as `claw3d` for convenience. - src/features/office/hooks/useCronAgents.ts: Hook that polls the gateway for cron-scheduled agents and surfaces them in the 3D office. - package.json: adds `hermes-adapter` npm script - .env.example: documents Hermes config vars - docs/hermes-gateway.md: setup guide and protocol reference Usage: npm run hermes-adapter # start adapter (connect to http://localhost:8642) npm run dev # start Claw3D, point browser at localhost:3000 # or: bash scripts/clawd3d-start.sh (starts everything automatically) Both OpenClaw and Hermes are supported simultaneously — the gateway URL in NEXT_PUBLIC_GATEWAY_URL determines which backend Claw3D connects to. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: add read_agent_context tool for cross-agent coordination Agents can now read each other's conversation history via the read_agent_context tool, enabling the orchestrator to check what a sub-agent has done before re-delegating work. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: wire Hermes office UX and role-aware runtime updates * feature update - demomode & hermes adapter * fix lint blockers * lintfix #2 * fix: stabilize retro office camera preset callbacks * Initial plan * fix: stabilize retro office overview preset hooks Agent-Logs-Url: https://github.com/gsknnft/Claw3D/sessions/9cc71555-591e-44cf-aec4-25affbdcb405 Co-authored-by: gsknnft <123185582+gsknnft@users.noreply.github.com> * feat: add truthful backend selection, Hermes adapter hardening, and demo gateway mode * fix: address bugbot review and finalize backend selection * fixed - onboarding and hermes calls * office systems roadmap * feat specs in docs * specs ready * feat: continue custom runtime seam and gateway alignment * custom lane wired * feat: add custom runtime provider path and office runtime alignment * runtime fixes * fix lukes findings * fix lukes findings #2 * stable UI & connect screen page -> overlay * better baseline for connection * stable providers & ui rendering * best launch yet * nearly no gateway on reconnect * auto reconnect last state * fix: preserve selected runtime across reconnects Keep backend selection aligned with the operator's chosen runtime instead of reviving a mismatched last-known-good adapter, and keep custom runtimes prompting for reconnect when Studio cannot auto-connect them. Made-with: Cursor --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Luke The Dev <iamlukethedev@users.noreply.github.com> Co-authored-by: Elias Pfeffer <eliaspfeffer@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: iamlukethedev <lucas.guilherme@smartwayslfl.com>
2026-04-02 16:27:24 -04:00
parent a997f13601
commit 083c146aac
77 changed files with 10045 additions and 399 deletions
@@ -7,6 +7,8 @@ import {
  type GatewayHelloOk,
 } from "./openclaw/GatewayBrowserClient";
 import type {
+  StudioGatewayProfilePublic,
+  StudioGatewayAdapterType,
  StudioGatewaySettings,
  StudioSettings,
  StudioSettingsPatch,
@@ -20,6 +22,18 @@ import { resolveStudioProxyGatewayUrl } from "@/lib/gateway/proxy-url";
 import { ensureGatewayReloadModeHotForLocalStudio } from "@/lib/gateway/gatewayReloadMode";
 import { GatewayResponseError } from "@/lib/gateway/errors";

+const gatewayDebugEnabled = process.env.NODE_ENV !== "production";
+
+const gatewayDebugLog = (message: string, details?: Record<string, unknown>) => {
+  if (!gatewayDebugEnabled) return;
+  if (details) {
+    console.info("[gateway-client]", message, details);
+    return;
+  }
+  console.info("[gateway-client]", message);
+};
+import { probeCustomRuntime } from "@/lib/runtime/custom/http";
+
 export type ReqFrame = {
  type: "req";
  id: string;
@@ -82,7 +96,7 @@ export const isSameSessionKey = (a: string, b: string) => {
 };

 const CONNECT_FAILED_CLOSE_CODE = 4008;
-const GATEWAY_CONNECT_TIMEOUT_MS = 8_000;
+const GATEWAY_CONNECT_TIMEOUT_MS = 13_000;

 const parseConnectFailedCloseReason = (
  reason: string
@@ -100,10 +114,67 @@ const parseConnectFailedCloseReason = (

 const DEFAULT_UPSTREAM_GATEWAY_URL =
  process.env.NEXT_PUBLIC_GATEWAY_URL || "ws://localhost:18789";
+const DEFAULT_CUSTOM_RUNTIME_URL = "http://localhost:7770";
+const INITIAL_AUTO_CONNECT_DELAY_MS = 900;
+const INITIAL_CONNECT_RETRY_DELAY_MS = 1_200;
+
+const isAutoManagedAdapter = (adapterType: StudioGatewayAdapterType) =>
+  adapterType !== "custom";
+
+export const resolveInitialGatewayAutoConnectDelayMs = (
+  adapterType: StudioGatewayAdapterType
+): number => {
+  switch (adapterType) {
+    case "hermes":
+    case "demo":
+      return INITIAL_AUTO_CONNECT_DELAY_MS;
+    default:
+      return 0;
+  }
+};
+
+export const resolveInitialGatewayConnectAttemptCount = (
+  adapterType: StudioGatewayAdapterType,
+  hasConnectedOnce: boolean
+): number => {
+  switch (adapterType) {
+    case "hermes":
+    case "demo":
+      return 2;
+    default:
+      if (hasConnectedOnce) return 1;
+      return 1;
+  }
+};
+
+const resolveDefaultGatewayProfile = (
+  adapterType: StudioGatewayAdapterType,
+  localDefaults: StudioGatewaySettings | null
+): { url: string; token: string } => {
+  switch (adapterType) {
+    case "custom":
+      return { url: DEFAULT_CUSTOM_RUNTIME_URL, token: "" };
+    case "demo":
+    case "hermes":
+      return { url: "ws://localhost:18789", token: "" };
+    case "openclaw":
+    default:
+      return {
+        url: localDefaults?.url || DEFAULT_UPSTREAM_GATEWAY_URL,
+        token: localDefaults?.token ?? "",
+      };
+  }
+};

 const normalizeLocalGatewayDefaults = (value: unknown): StudioGatewaySettings | null => {
  if (!value || typeof value !== "object") return null;
-  const raw = value as { url?: unknown; token?: unknown; tokenConfigured?: unknown };
+  const raw = value as {
+    url?: unknown;
+    token?: unknown;
+    tokenConfigured?: unknown;
+    adapterType?: unknown;
+    profiles?: unknown;
+  };
  const url = typeof raw.url === "string" ? raw.url.trim() : "";
  if (!url) return null;
  // Accept both full settings ({ url, token }) and the sanitized public
@@ -111,7 +182,40 @@ const normalizeLocalGatewayDefaults = (value: unknown): StudioGatewaySettings |
  // tokenConfigured is present the actual token isn't available on the
  // client — leave it empty so the connection dialog can prompt if needed.
  const token = typeof raw.token === "string" ? raw.token.trim() : "";
-  return { url, token };
+  const adapterType =
+    raw.adapterType === "demo" ||
+    raw.adapterType === "hermes" ||
+    raw.adapterType === "openclaw" ||
+    raw.adapterType === "custom"
+      ? raw.adapterType
+      : "openclaw";
+  const profiles = normalizeGatewayProfilesPublic(raw.profiles);
+  return { url, token, adapterType, ...(profiles ? { profiles } : {}) };
+};
+
+const normalizeGatewayProfilePublic = (
+  value: unknown
+): { url: string; token: string } | null => {
+  if (!value || typeof value !== "object") return null;
+  const raw = value as { url?: unknown };
+  const url = typeof raw.url === "string" ? raw.url.trim() : "";
+  if (!url) return null;
+  return { url, token: "" };
+};
+
+const normalizeGatewayProfilesPublic = (
+  value: unknown
+): Partial<Record<StudioGatewayAdapterType, { url: string; token: string }>> | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const raw = value as Partial<Record<StudioGatewayAdapterType, StudioGatewayProfilePublic>>;
+  const profiles: Partial<Record<StudioGatewayAdapterType, { url: string; token: string }>> = {};
+  for (const adapterType of ["openclaw", "hermes", "demo", "custom"] as const) {
+    const profile = normalizeGatewayProfilePublic(raw[adapterType]);
+    if (profile) {
+      profiles[adapterType] = profile;
+    }
+  }
+  return Object.keys(profiles).length > 0 ? profiles : undefined;
 };

 type StatusHandler = (status: GatewayStatus) => void;
@@ -419,14 +523,30 @@ export const syncGatewaySessionSettings = async ({
 const doctorFixHint =
  "Run `npx openclaw doctor --fix` on the gateway host (or `pnpm openclaw doctor --fix` in a source checkout).";

+const protocolMismatchHint =
+  "This gateway looks too old for Claw3D's protocol v3. Upgrade OpenClaw, use the Hermes adapter, or run `npm run demo-gateway` for a no-framework office demo.";
+
+const isGatewayProtocolMismatchError = (error: GatewayResponseError) => {
+  if (error.code.trim().toUpperCase() !== "INVALID_REQUEST") return false;
+  const message = error.message.trim();
+  if (!message) return false;
+  return /minProtocol|maxProtocol/i.test(message);
+};
+
 const formatGatewayError = (error: unknown) => {
  if (error instanceof GatewayResponseError) {
+    if (isGatewayProtocolMismatchError(error)) {
+      return `Gateway error (${error.code}): ${error.message}. ${protocolMismatchHint}`;
+    }
    if (error.code === "INVALID_REQUEST" && /invalid config/i.test(error.message)) {
      return `Gateway error (${error.code}): ${error.message}. ${doctorFixHint}`;
    }
    return `Gateway error (${error.code}): ${error.message}`;
  }
  if (error instanceof Error) {
+    if (/timed out connecting to the gateway/i.test(error.message)) {
+      return `${error.message} If you are testing locally, an older OpenClaw build may be speaking an incompatible protocol. Try upgrading OpenClaw, using the Hermes adapter, or running \`npm run demo-gateway\`.`;
+    }
    return error.message;
  }
  return "Unknown gateway error.";
@@ -437,6 +557,9 @@ export type GatewayConnectionState = {
  status: GatewayStatus;
  gatewayUrl: string;
  token: string;
+  selectedAdapterType: StudioGatewayAdapterType;
+  detectedAdapterType: StudioGatewayAdapterType | null;
+  activeAdapterType: StudioGatewayAdapterType;
  localGatewayDefaults: StudioGatewaySettings | null;
  error: string | null;
  connectPromptReady: boolean;
@@ -446,6 +569,7 @@ export type GatewayConnectionState = {
  useLocalGatewayDefaults: () => void;
  setGatewayUrl: (value: string) => void;
  setToken: (value: string) => void;
+  setSelectedAdapterType: (value: StudioGatewayAdapterType) => void;
  clearError: () => void;
 };

@@ -523,13 +647,27 @@ export const useGatewayConnection = (
  const [client] = useState(() => new GatewayClient());
  const didAutoConnect = useRef(false);
  const hasConnectedOnceRef = useRef(false);
-  const loadedGatewaySettings = useRef<{ gatewayUrl: string; token: string } | null>(null);
+  const loadedGatewaySettings = useRef<{
+    gatewayUrl: string;
+    token: string;
+    adapterType: StudioGatewayAdapterType;
+    profiles?: Partial<Record<StudioGatewayAdapterType, { url: string; token: string }>>;
+    hasLastKnownGood: boolean;
+  } | null>(null);
  const retryAttemptRef = useRef(0);
  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const autoConnectTimerRef = useRef<number | null>(null);
  const wasManualDisconnectRef = useRef(false);

  const [gatewayUrl, setGatewayUrl] = useState(DEFAULT_UPSTREAM_GATEWAY_URL);
  const [token, setToken] = useState("");
+  const [selectedAdapterType, setSelectedAdapterTypeState] =
+    useState<StudioGatewayAdapterType>("openclaw");
+  const [adapterProfiles, setAdapterProfiles] = useState<
+    Partial<Record<StudioGatewayAdapterType, { url: string; token: string }>>
+  >({});
+  const [detectedAdapterType, setDetectedAdapterType] =
+    useState<StudioGatewayAdapterType | null>(null);
  const [localGatewayDefaults, setLocalGatewayDefaults] = useState<StudioGatewaySettings | null>(
    null
  );
@@ -537,6 +675,19 @@ export const useGatewayConnection = (
  const [error, setError] = useState<string | null>(null);
  const [connectErrorCode, setConnectErrorCode] = useState<string | null>(null);
  const [settingsLoaded, setSettingsLoaded] = useState(false);
+  const [hasLastKnownGoodState, setHasLastKnownGoodState] = useState(false);
+  const setSelectedAdapterType = useCallback(
+    (value: StudioGatewayAdapterType) => {
+      setSelectedAdapterTypeState(value);
+      const profile =
+        adapterProfiles[value] ?? resolveDefaultGatewayProfile(value, localGatewayDefaults);
+      setGatewayUrl(profile.url);
+      setToken(profile.token);
+      setError(null);
+      setConnectErrorCode(null);
+    },
+    [adapterProfiles, localGatewayDefaults]
+  );

  useEffect(() => {
    let cancelled = false;
@@ -554,26 +705,92 @@ export const useGatewayConnection = (
        if (cancelled) return;
        const normalizedDefaults = normalizeLocalGatewayDefaults(envelope.localGatewayDefaults);
        setLocalGatewayDefaults(normalizedDefaults);
+        const lastKnownGood =
+          gateway && "lastKnownGood" in gateway && gateway.lastKnownGood
+            ? {
+                url:
+                  typeof gateway.lastKnownGood.url === "string"
+                    ? gateway.lastKnownGood.url
+                    : "",
+                token:
+                  "token" in gateway.lastKnownGood &&
+                  typeof gateway.lastKnownGood.token === "string"
+                    ? gateway.lastKnownGood.token
+                    : "",
+                adapterType:
+                  gateway.lastKnownGood.adapterType === "demo" ||
+                  gateway.lastKnownGood.adapterType === "hermes" ||
+                  gateway.lastKnownGood.adapterType === "openclaw" ||
+                  gateway.lastKnownGood.adapterType === "custom"
+                    ? gateway.lastKnownGood.adapterType
+                    : "openclaw",
+              }
+            : null;
        // When the user has no saved gateway URL, prefer the runtime
        // localGatewayDefaults (from openclaw.json / CLAW3D_GATEWAY_URL)
        // over the build-time NEXT_PUBLIC_GATEWAY_URL which may be stale
        // or empty if the operator forgot to rebuild after .env changes.
        const hasSavedUrl = Boolean(gateway?.url?.trim());
+        const savedAdapterType =
+          hasSavedUrl && gateway && "adapterType" in gateway && typeof gateway.adapterType === "string"
+            ? ((gateway.adapterType === "demo" ||
+                gateway.adapterType === "hermes" ||
+                gateway.adapterType === "openclaw" ||
+                gateway.adapterType === "custom"
+                ? gateway.adapterType
+                : "openclaw") as StudioGatewayAdapterType)
+            : null;
+        const nextAdapterType =
+          savedAdapterType ??
+          lastKnownGood?.adapterType ??
+          normalizedDefaults?.adapterType ??
+          "openclaw";
+        const lastKnownGoodForSelectedAdapter =
+          lastKnownGood?.adapterType === nextAdapterType ? lastKnownGood : null;
        const resolvedUrl = hasSavedUrl
          ? gateway!.url
-          : normalizedDefaults?.url || DEFAULT_UPSTREAM_GATEWAY_URL;
-        const nextGatewayUrl = resolvedUrl;
-        const nextToken = hasSavedUrl
-          ? (gateway && "token" in gateway && typeof gateway.token === "string"
-              ? gateway.token
-              : "")
-          : normalizedDefaults?.token ?? "";
+          : lastKnownGoodForSelectedAdapter?.url ||
+            normalizedDefaults?.url ||
+            DEFAULT_UPSTREAM_GATEWAY_URL;
+        const baseProfiles = {
+          ...(gateway?.profiles
+            ? normalizeGatewayProfilesPublic(gateway.profiles)
+            : undefined),
+          ...(normalizedDefaults?.profiles ?? {}),
+        };
+        const mergedProfiles = {
+          ...baseProfiles,
+          ...(hasSavedUrl
+            ? {
+                [nextAdapterType]: {
+                  url: resolvedUrl,
+                  token:
+                    gateway && "token" in gateway && typeof gateway.token === "string"
+                      ? gateway.token
+                      : "",
+                },
+              }
+            : {}),
+        };
+        const selectedProfile = (
+          mergedProfiles[nextAdapterType] ??
+          lastKnownGoodForSelectedAdapter ??
+          resolveDefaultGatewayProfile(nextAdapterType, normalizedDefaults)
+        );
+        const nextGatewayUrl = selectedProfile.url;
+        const nextToken = selectedProfile.token;
        loadedGatewaySettings.current = {
          gatewayUrl: nextGatewayUrl.trim(),
          token: nextToken,
+          adapterType: nextAdapterType,
+          profiles: mergedProfiles,
+          hasLastKnownGood: Boolean(lastKnownGoodForSelectedAdapter?.url),
        };
        setGatewayUrl(nextGatewayUrl);
        setToken(nextToken);
+        setSelectedAdapterTypeState(nextAdapterType);
+        setAdapterProfiles(mergedProfiles);
+        setHasLastKnownGoodState(Boolean(lastKnownGoodForSelectedAdapter?.url));
      } catch (err) {
        if (!cancelled) {
          const message = err instanceof Error ? err.message : "Failed to load gateway settings.";
@@ -585,6 +802,9 @@ export const useGatewayConnection = (
            loadedGatewaySettings.current = {
              gatewayUrl: DEFAULT_UPSTREAM_GATEWAY_URL.trim(),
              token: "",
+              adapterType: "openclaw",
+              profiles: undefined,
+              hasLastKnownGood: false,
            };
          }
          setSettingsLoaded(true);
@@ -599,11 +819,14 @@ export const useGatewayConnection = (

  useEffect(() => {
    return client.onStatus((nextStatus) => {
+      gatewayDebugLog("status", { nextStatus });
      setStatus(nextStatus);
      if (nextStatus !== "connecting") {
        setError(null);
        if (nextStatus === "connected") {
          setConnectErrorCode(null);
+        } else {
+          setDetectedAdapterType(null);
        }
      }
    });
@@ -611,6 +834,10 @@ export const useGatewayConnection = (

  useEffect(() => {
    return () => {
+      if (autoConnectTimerRef.current) {
+        clearTimeout(autoConnectTimerRef.current);
+        autoConnectTimerRef.current = null;
+      }
      if (retryTimerRef.current) {
        clearTimeout(retryTimerRef.current);
        retryTimerRef.current = null;
@@ -620,35 +847,145 @@ export const useGatewayConnection = (
  }, [client]);

  const connect = useCallback(async () => {
+    if (autoConnectTimerRef.current) {
+      clearTimeout(autoConnectTimerRef.current);
+      autoConnectTimerRef.current = null;
+    }
+    if (retryTimerRef.current) {
+      clearTimeout(retryTimerRef.current);
+      retryTimerRef.current = null;
+    }
+    gatewayDebugLog("connect:start", {
+      selectedAdapterType,
+      gatewayUrl,
+      hasToken: Boolean(token),
+    });
    setError(null);
    setConnectErrorCode(null);
+    retryAttemptRef.current = 0;
    wasManualDisconnectRef.current = false;
+    if (selectedAdapterType === "custom") {
+      setStatus("connecting");
+      try {
+        await settingsCoordinator.flushPending();
+        await probeCustomRuntime(gatewayUrl);
+        setDetectedAdapterType("custom");
+        setStatus("connected");
+        setConnectErrorCode(null);
+        retryAttemptRef.current = 0;
+        gatewayDebugLog("connect:custom-success", { gatewayUrl });
+      } catch (err) {
+        setStatus("disconnected");
+        setDetectedAdapterType(null);
+        setConnectErrorCode("studio.custom_runtime_probe_failed");
+        setError(formatGatewayError(err));
+        gatewayDebugLog("connect:custom-failed", {
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+      return;
+    }
    try {
      await settingsCoordinator.flushPending();
-      await client.connect({
-        gatewayUrl: resolveStudioProxyGatewayUrl(),
-        token,
-        authScopeKey: gatewayUrl,
-        clientName: "openclaw-control-ui",
-      });
+      const maxAttempts = resolveInitialGatewayConnectAttemptCount(
+        selectedAdapterType,
+        hasConnectedOnceRef.current
+      );
+      let lastError: unknown = null;
+      for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+          await client.connect({
+            gatewayUrl: resolveStudioProxyGatewayUrl(),
+            token,
+            authScopeKey: gatewayUrl,
+            clientName: "openclaw-control-ui",
+            disableDeviceAuth: selectedAdapterType !== "openclaw",
+          });
+          lastError = null;
+          break;
+        } catch (err) {
+          lastError = err;
+          gatewayDebugLog("connect:attempt-failed", {
+            selectedAdapterType,
+            attempt: attempt + 1,
+            maxAttempts,
+            message: err instanceof Error ? err.message : String(err),
+          });
+          if (attempt + 1 >= maxAttempts) {
+            throw err;
+          }
+          client.disconnect();
+          await new Promise<void>((resolve) => {
+            window.setTimeout(resolve, INITIAL_CONNECT_RETRY_DELAY_MS);
+          });
+        }
+      }
+      if (lastError) {
+        throw lastError;
+      }
      await ensureGatewayReloadModeHotForLocalStudio({
        client,
        upstreamGatewayUrl: gatewayUrl,
      });
+      const hello = client.getLastHello();
+      const nextDetectedAdapterType =
+        hello?.adapterType === "demo" ||
+        hello?.adapterType === "hermes" ||
+        hello?.adapterType === "openclaw" ||
+        hello?.adapterType === "custom"
+          ? hello.adapterType
+          : "openclaw";
+      setDetectedAdapterType(nextDetectedAdapterType);
      retryAttemptRef.current = 0;
+      setHasLastKnownGoodState(nextDetectedAdapterType === selectedAdapterType);
+      settingsCoordinator.schedulePatch({
+        gateway: {
+          lastKnownGood: {
+            url: gatewayUrl.trim(),
+            token,
+            adapterType: nextDetectedAdapterType,
+          },
+        },
+      });
+      gatewayDebugLog("connect:success", {
+        selectedAdapterType,
+        detectedAdapterType: nextDetectedAdapterType,
+      });
    } catch (err) {
      setConnectErrorCode(err instanceof GatewayResponseError ? err.code : null);
      setError(formatGatewayError(err));
+      gatewayDebugLog("connect:failed", {
+        selectedAdapterType,
+        code: err instanceof GatewayResponseError ? err.code : null,
+        message: err instanceof Error ? err.message : String(err),
+      });
    }
-  }, [client, gatewayUrl, settingsCoordinator, token]);
+  }, [client, gatewayUrl, selectedAdapterType, settingsCoordinator, token]);

  useEffect(() => {
    if (didAutoConnect.current) return;
    if (!settingsLoaded) return;
+    if (!hasLastKnownGoodState) return;
    if (!gatewayUrl.trim()) return;
+    if (!isAutoManagedAdapter(selectedAdapterType)) return;
    didAutoConnect.current = true;
-    void connect();
-  }, [connect, gatewayUrl, settingsLoaded]);
+    const delayMs = resolveInitialGatewayAutoConnectDelayMs(selectedAdapterType);
+    gatewayDebugLog("auto-connect", {
+      selectedAdapterType,
+      gatewayUrl,
+      delayMs,
+    });
+    autoConnectTimerRef.current = window.setTimeout(() => {
+      autoConnectTimerRef.current = null;
+      void connect();
+    }, delayMs);
+    return () => {
+      if (autoConnectTimerRef.current) {
+        window.clearTimeout(autoConnectTimerRef.current);
+        autoConnectTimerRef.current = null;
+      }
+    };
+  }, [connect, gatewayUrl, hasLastKnownGoodState, selectedAdapterType, settingsLoaded]);

  // Auto-retry on disconnect (gateway busy, network blip, etc.)
  useEffect(() => {
@@ -663,9 +1000,21 @@ export const useGatewayConnection = (
      connectErrorCode,
      attempt,
    });
+    if (!isAutoManagedAdapter(selectedAdapterType)) return;
    if (delay === null) return;
+    gatewayDebugLog("auto-retry-scheduled", {
+      selectedAdapterType,
+      attempt: attempt + 1,
+      delay,
+      gatewayUrl,
+      status,
+    });
    retryTimerRef.current = setTimeout(() => {
      retryAttemptRef.current = attempt + 1;
+      gatewayDebugLog("auto-retry-fire", {
+        selectedAdapterType,
+        attempt: retryAttemptRef.current,
+      });
      void connect();
    }, delay);

@@ -675,7 +1024,7 @@ export const useGatewayConnection = (
        retryTimerRef.current = null;
      }
    };
-  }, [connect, connectErrorCode, error, gatewayUrl, status]);
+  }, [connect, connectErrorCode, error, gatewayUrl, selectedAdapterType, status]);

  // Reset retry count on successful connection
  useEffect(() => {
@@ -685,12 +1034,46 @@ export const useGatewayConnection = (
    }
  }, [status]);

+  useEffect(() => {
+    if (!settingsLoaded) return;
+    setAdapterProfiles((current) => {
+      const nextProfile = {
+        url: gatewayUrl.trim(),
+        token,
+      };
+      const existing = current[selectedAdapterType];
+      if (
+        existing &&
+        existing.url === nextProfile.url &&
+        existing.token === nextProfile.token
+      ) {
+        return current;
+      }
+      return {
+        ...current,
+        [selectedAdapterType]: nextProfile,
+      };
+    });
+  }, [gatewayUrl, selectedAdapterType, settingsLoaded, token]);
+
  useEffect(() => {
    if (!settingsLoaded) return;
    const baseline = loadedGatewaySettings.current;
    if (!baseline) return;
    const nextGatewayUrl = gatewayUrl.trim();
-    if (nextGatewayUrl === baseline.gatewayUrl && token === baseline.token) {
+    const nextProfiles = {
+      ...adapterProfiles,
+      [selectedAdapterType]: {
+        url: nextGatewayUrl,
+        token,
+      },
+    };
+    if (
+      nextGatewayUrl === baseline.gatewayUrl &&
+      token === baseline.token &&
+      selectedAdapterType === baseline.adapterType &&
+      JSON.stringify(nextProfiles) === JSON.stringify(baseline.profiles ?? {})
+    ) {
      return;
    }
    settingsCoordinator.schedulePatch(
@@ -698,11 +1081,13 @@ export const useGatewayConnection = (
        gateway: {
          url: nextGatewayUrl,
          token,
+          adapterType: selectedAdapterType,
+          profiles: nextProfiles,
        },
      },
      400
    );
-  }, [gatewayUrl, settingsCoordinator, settingsLoaded, token]);
+  }, [adapterProfiles, gatewayUrl, selectedAdapterType, settingsCoordinator, settingsLoaded, token]);

  const useLocalGatewayDefaults = useCallback(() => {
    if (!localGatewayDefaults) {
@@ -710,17 +1095,31 @@ export const useGatewayConnection = (
    }
    setGatewayUrl(localGatewayDefaults.url);
    setToken(localGatewayDefaults.token);
+    setAdapterProfiles((current) => ({
+      ...current,
+      [localGatewayDefaults.adapterType]: {
+        url: localGatewayDefaults.url,
+        token: localGatewayDefaults.token,
+      },
+    }));
+    setSelectedAdapterTypeState(localGatewayDefaults.adapterType);
    setError(null);
    setConnectErrorCode(null);
  }, [localGatewayDefaults]);

  const disconnect = useCallback(() => {
+    gatewayDebugLog("disconnect", { selectedAdapterType });
    setError(null);
    setConnectErrorCode(null);
    wasManualDisconnectRef.current = true;
+    setDetectedAdapterType(null);
+    if (selectedAdapterType === "custom") {
+      setStatus("disconnected");
+      return;
+    }
    client.disconnect();
    clearGatewayBrowserSessionStorage();
-  }, [client]);
+  }, [client, selectedAdapterType]);

  const clearError = useCallback(() => {
    setError(null);
@@ -728,16 +1127,26 @@ export const useGatewayConnection = (
  }, []);

  const connectPromptReady = settingsLoaded;
+  const activeAdapterType =
+    status === "connected" ? detectedAdapterType ?? selectedAdapterType : selectedAdapterType;
  const shouldPromptForConnect =
    settingsLoaded &&
    status !== "connected" &&
-    (!gatewayUrl.trim() || !token.trim() || wasManualDisconnectRef.current || Boolean(error));
+    (selectedAdapterType === "custom" ||
+      !hasLastKnownGoodState ||
+      !gatewayUrl.trim() ||
+      (selectedAdapterType === "openclaw" && !token.trim()) ||
+      wasManualDisconnectRef.current ||
+      Boolean(error));

  return {
    client,
    status,
    gatewayUrl,
    token,
+    selectedAdapterType,
+    detectedAdapterType,
+    activeAdapterType,
    localGatewayDefaults,
    error,
    connectPromptReady,
@@ -747,6 +1156,7 @@ export const useGatewayConnection = (
    useLocalGatewayDefaults,
    setGatewayUrl,
    setToken,
+    setSelectedAdapterType,
    clearError,
  };
 };