fix(controller): stop masquerading gateway-WS failure as per-channel credential failure (#1128)

Issue #856: after 0.1.10-nightly.20260406 users reported all IM channels
showing as disconnected with a "Reconnect required" CTA, forcing them to
re-authenticate channels whose tokens on disk were still valid.

Root cause: openclaw-gateway-service.ts#getAllChannelsLiveStatus had two
fallback paths (WS-not-connected pre-check and RPC-throws catch) that
both returned status:"disconnected", configured:false, lastError:null
for every channel. The web UI treats that shape as a real credential
failure and prompts re-auth. When the OpenClaw gateway WS was
transiently unreachable (skillhub sync churn, deterministic-config
reload, langfuse restart, OAuth apiKey rejection) every channel got
flagged disconnected despite nothing being wrong.

Channel records on disk were never touched — only the live-status reply
lied.

Fix: both fallback paths now return status:"connecting", configured:true,
lastError:null. The existing UI path for "connecting" (home.tsx:273-327
getChannelStatusMeta) already renders the amber spinner without a
re-auth CTA, and the existing "Offline" + "Agent starting…" header pills
already communicate the gateway-unavailable state. No new banner or
i18n strings were needed.

Supporting cleanup: runtimeState / isBootPhasePreReady threading was
only used by the branch we just simplified, so the service constructor
drops that parameter. container.ts and the two test fixtures
(openclaw-gateway-service.test.ts, route-compat.test.ts) updated for the
new signature.

Tests: two new cases in openclaw-gateway-service.test.ts cover the
WS-not-connected and RPC-throws branches and assert the honest shape.

Packaged smoke test (macOS arm64, unsigned): baseline green, kill
openclaw via launchctl bootout + kill -9, UI flips to red Offline / amber
Agent-starting / amber Feishu-connecting with NO red shield and NO
Reconnect CTA; restart openclaw, UI returns to green within one poll
cycle with no re-auth required. Full write-up at
specs/design-docs/2026-04-15-channel-status-masquerade-fix.md including
a sidebar on launchd KeepAlive supervision (OpenClaw auto-restarts
within ~5s of a crash as long as the controller is alive).

Author: alchemistklk

apps/controller/src/app/container.ts

@@ -99,7 +99,7 @@ export async function createContainer(): Promise<ControllerContainer> {
   const openclawProcess = new OpenClawProcessManager(env);
   const watchTrigger = new OpenClawWatchTrigger(env, openclawProcess);
   const wsClient = new OpenClawWsClient(env);
-  const gatewayService = new OpenClawGatewayService(wsClient, runtimeState);
+  const gatewayService = new OpenClawGatewayService(wsClient);
   const controlPlaneHealth = new ControlPlaneHealthService(
     gatewayService,
     wsClient,

apps/controller/src/services/openclaw-gateway-service.ts

@@ -14,10 +14,6 @@ import type { OpenClawConfig } from "@nexu/shared";
 import { logger } from "../lib/logger.js";
 import { serializeOpenClawConfig } from "../lib/openclaw-config-serialization.js";
 import type { OpenClawWsClient } from "../runtime/openclaw-ws-client.js";
-import {
-  type ControllerRuntimeState,
-  isBootPhasePreReady,
-} from "../runtime/state.js";
 
 // ---------------------------------------------------------------------------
 // Public types — channel status & readiness
@@ -148,10 +144,7 @@ export class OpenClawGatewayService {
   /** SHA-256 hash of the last config we successfully observed. */
   private lastPushedConfigHash: string | null = null;
 
-  constructor(
-    private readonly wsClient: OpenClawWsClient,
-    private readonly runtimeState: ControllerRuntimeState,
-  ) {}
+  constructor(private readonly wsClient: OpenClawWsClient) {}
 
   /** Whether the WS client has completed handshake and is ready for RPC. */
   isConnected(): boolean {
@@ -327,24 +320,22 @@ export class OpenClawGatewayService {
     channels: ChannelLiveStatusEntry[];
   }> {
     if (!this.wsClient.isConnected()) {
-      // During boot or when gateway is still starting, show "connecting"
-      // instead of "disconnected" so the UI doesn't flash a scary red state.
-      const startupStatus: ChannelLiveStatus =
-        isBootPhasePreReady(this.runtimeState.bootPhase) ||
-        this.runtimeState.gatewayStatus === "starting"
-          ? "connecting"
-          : "disconnected";
+      // WS is not connected: we cannot observe live channel status. Report
+      // "connecting" regardless of boot phase so the UI surfaces a neutral
+      // gateway-offline state instead of a per-channel credential failure,
+      // and preserve configured: true for channels with persisted credentials
+      // so the UI does not render the "not configured" reconnect prompt.
       return {
         gatewayConnected: false,
         channels: channels.map((channel) => ({
           channelType: channel.channelType,
           channelId: channel.id,
           accountId: channel.accountId,
-          status: startupStatus,
+          status: "connecting",
           ready: false,
           connected: false,
           running: false,
-          configured: false,
+          configured: true,
           lastError: null,
         })),
       };
@@ -492,17 +483,21 @@ export class OpenClawGatewayService {
         { error: err instanceof Error ? err.message : String(err) },
         "openclaw_channels_live_status_error",
       );
+      // Gateway RPC failed mid-flight — treat as a transient gateway outage.
+      // Report "connecting" + configured: true so the UI shows the
+      // gateway-offline banner instead of prompting users to re-authenticate
+      // channels whose credentials on disk are still valid.
       return {
         gatewayConnected: false,
         channels: channels.map((channel) => ({
           channelType: channel.channelType,
           channelId: channel.id,
           accountId: channel.accountId,
-          status: "disconnected",
+          status: "connecting",
           ready: false,
           connected: false,
           running: false,
-          configured: false,
+          configured: true,
           lastError: null,
         })),
       };

apps/controller/tests/openclaw-gateway-service.test.ts

@@ -1,5 +1,5 @@
 import type { OpenClawConfig } from "@nexu/shared";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { OpenClawGatewayService } from "../src/services/openclaw-gateway-service.js";
 
 function makeConfig(overrides: Partial<OpenClawConfig> = {}): OpenClawConfig {
@@ -17,12 +17,9 @@ function makeConfig(overrides: Partial<OpenClawConfig> = {}): OpenClawConfig {
 
 describe("OpenClawGatewayService", () => {
   it("treats semantically identical configs as unchanged despite key reorder", async () => {
-    const service = new OpenClawGatewayService(
-      {
-        isConnected: () => true,
-      } as never,
-      {} as never,
-    );
+    const service = new OpenClawGatewayService({
+      isConnected: () => true,
+    } as never);
 
     const configA = makeConfig({
       plugins: {
@@ -47,4 +44,49 @@ describe("OpenClawGatewayService", () => {
 
     await expect(service.shouldPushConfig(configB)).resolves.toBe(false);
   });
+
+  describe("getAllChannelsLiveStatus gateway-offline reporting", () => {
+    const channels = [
+      { id: "ch1", channelType: "feishu", accountId: "feishu-acct" },
+      { id: "ch2", channelType: "slack", accountId: "T0001" },
+    ];
+
+    it("reports connecting + configured when WS is not connected", async () => {
+      const service = new OpenClawGatewayService({
+        isConnected: () => false,
+        request: vi.fn(),
+      } as never);
+
+      const result = await service.getAllChannelsLiveStatus(channels);
+
+      expect(result.gatewayConnected).toBe(false);
+      for (const entry of result.channels) {
+        expect(entry.status).toBe("connecting");
+        expect(entry.configured).toBe(true);
+        expect(entry.connected).toBe(false);
+        expect(entry.running).toBe(false);
+        expect(entry.lastError).toBeNull();
+      }
+    });
+
+    it("reports connecting + configured when the channels.status RPC throws", async () => {
+      const service = new OpenClawGatewayService({
+        isConnected: () => true,
+        request: vi.fn(async () => {
+          throw new Error("openclaw gateway not connected");
+        }),
+      } as never);
+
+      const result = await service.getAllChannelsLiveStatus(channels);
+
+      expect(result.gatewayConnected).toBe(false);
+      for (const entry of result.channels) {
+        expect(entry.status).toBe("connecting");
+        expect(entry.configured).toBe(true);
+        expect(entry.connected).toBe(false);
+        expect(entry.running).toBe(false);
+        expect(entry.lastError).toBeNull();
+      }
+    });
+  });
 });

apps/controller/tests/route-compat.test.ts

@@ -113,13 +113,10 @@ async function createTestContainer(
     isConnected: () => false,
     stop: vi.fn(),
   } as unknown as ControllerContainer["wsClient"];
-  const gatewayService = new OpenClawGatewayService(
-    {
-      isConnected: () => false,
-      request: vi.fn(),
-    } as never,
-    runtimeState,
-  );
+  const gatewayService = new OpenClawGatewayService({
+    isConnected: () => false,
+    request: vi.fn(),
+  } as never);
   const controlPlaneHealth = new ControlPlaneHealthService(
     gatewayService,
     wsClient,

specs/design-docs/2026-04-15-channel-status-masquerade-fix.md

@@ -0,0 +1,111 @@
+# Channel-status masquerade on OpenClaw gateway WS failure
+
+Date: 2026-04-15
+Related issue: [#856](https://github.com/…/issues/856) — "All channel connection states are reset in version 0.1.10-nightly.20260406"
+
+## Symptom
+
+After an update to `0.1.10-nightly.20260406`, users reported every IM channel (Feishu, DingTalk, WeCom, …) showing as disconnected with a "Reconnect required" CTA, forcing them to re-authenticate channels whose tokens on disk were still valid. Reported as "all channel connection states were reset."
+
+## Root cause
+
+Not data loss. The controller's `openclaw-gateway-service.ts:getAllChannelsLiveStatus` has two fallback paths — a pre-check when the WebSocket is not connected, and a catch block when the RPC throws mid-flight. Both paths were returning:
+
+```ts
+{
+  gatewayConnected: false,
+  channels: channels.map((channel) => ({
+    …,
+    status: "disconnected",
+    configured: false,
+    lastError: null,
+  })),
+}
+```
+
+The web UI (home.tsx, channels.tsx) treats `status: "disconnected" + configured: false` as a credential failure — same as a revoked token — and renders the red "Reconnect required" affordance. When the OpenClaw gateway WS was transiently unreachable (gateway restart loop from the Apr 3–6 nightly, skillhub sync churn, langfuse reload, etc.), every channel reported disconnected and every user was prompted to re-auth, despite nothing being wrong with their credentials.
+
+The channel records on disk (`~/.nexu/config.json`) were never touched — only the live-status reply lied.
+
+## Fix
+
+`apps/controller/src/services/openclaw-gateway-service.ts`: in both the WS-not-connected branch and the catch branch, report the degraded state honestly:
+
+```ts
+{
+  gatewayConnected: false,
+  channels: channels.map((channel) => ({
+    …,
+    status: "connecting",   // we cannot yet observe live state
+    configured: true,       // credentials on disk are still valid
+    lastError: null,
+  })),
+}
+```
+
+The web UI already renders `"connecting"` as an amber spinner with no re-auth CTA (see `apps/web/src/pages/home.tsx:273-327` `getChannelStatusMeta`). The existing top-level "Offline" pill (driven by `/api/internal/desktop/ready`) and the "Agent starting…" pill (driven by `agent.alive`) already communicate the gateway-unavailable state clearly — no new banner or copy was needed.
+
+Now-unused `runtimeState` / `isBootPhasePreReady` threading was removed from the service; `container.ts` and 2 test fixtures updated for the simplified constructor.
+
+## Why the Apr 10–14 fixes masked the defect
+
+The catch block itself has existed for a long time; it only became visibly problematic in the `0.1.10-nightly.20260406` build because that nightly had several OpenClaw-reload loops that kept flipping the WS connection:
+
+| Commit | Fix |
+| --- | --- |
+| `7a03c2b0` | batch skillhub sync to prevent OpenClaw restart loop |
+| `87ea4cb9` | deterministic openclaw.json serialization (stops key-reorder reloads) |
+| `02e73549` | make langfuse-tracer always-allow to avoid gateway restart |
+| `bf631409` | stop emitting `apiKey: ""` for OAuth providers (OpenClaw was rejecting the whole models.providers block) |
+
+Those commits stabilized the gateway so the catch block stopped firing in practice, which is why testers stopped seeing the symptom after Apr 14. The latent masquerade stayed on main until this PR: any future WS flap would have reproduced #856 exactly.
+
+## Verification
+
+### Unit
+- `apps/controller/tests/openclaw-gateway-service.test.ts`: two new cases covering the WS-not-connected and RPC-throws branches assert `gatewayConnected: false`, `status: "connecting"`, `configured: true`.
+- Existing tests (`apps/web/tests/channel-live-status.test.ts`, `apps/controller/tests/route-compat.test.ts`) pass against the simplified service constructor.
+- `pnpm typecheck` ✅ • `pnpm lint` ✅ (0 errors from this change) • controller suite: 255 passing / 24 pre-existing failures unchanged.
+
+### Packaged smoke test (macOS arm64, unsigned build)
+
+Baseline: Feishu connected, "Running", "Agent running" (all green). `curl /api/v1/channels/live-status` → `gatewayConnected: true, agent.alive: true, status: "connected"`.
+
+Kill OpenClaw: `launchctl bootout gui/$(id -u)/io.nexu.openclaw && kill -9 <pid>`
+
+Expected (and observed):
+- Header pill flips to red **"Offline"**
+- Agent pill flips to amber **"Agent starting…"**
+- Feishu row shows amber **"Connecting…"** — *no* red shield, *no* "Reconnect" CTA
+- API: `gatewayConnected: false`, `status: "connecting"`, `configured: true`, `agent.alive: false`
+
+Restart OpenClaw: `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.nexu.openclaw.plist`
+
+Expected (and observed):
+- Within ~2–3s: all pills return to green, no re-auth required
+- API: `gatewayConnected: true`, `status: "connected"`, `agent.alive: true`
+
+## Supervision sidebar: OpenClaw auto-restart
+
+Surfaced while smoke-testing. In the packaged desktop the OpenClaw plist is configured for automatic supervision:
+
+```
+KeepAlive.OtherJobEnabled."io.nexu.controller" = true   # respawn while controller alive
+ThrottleInterval = 5                                    # min 5s between respawns
+RunAtLoad = false
+```
+
+A crashed OpenClaw (e.g. OOM, `kill -9`) is automatically respawned by launchd within 5s as long as the controller is alive. Verified live: killed pid 59414, launchd respawned as pid 63386 without any user action, API recovered to healthy within one poll cycle.
+
+Scenarios where OpenClaw can stay down:
+1. The controller itself has died (KeepAlive is gated on `io.nexu.controller`).
+2. Someone (or an updater) explicitly `launchctl bootout`s the plist — used in teardown, update-install, and smoke tests.
+3. The `MAX_CONSECUTIVE_RESTARTS=10` circuit breaker in `daemon-supervisor-restart.test.ts` trips after 10 consecutive failed respawns.
+
+So the "Offline" state we occasionally saw during testing was a direct artifact of the test-only `launchctl bootout`, not a production regression. Normal crashes self-heal without user action.
+
+## Out of scope
+
+- Root-causing future WS flaps. The Apr 10–14 stability fixes removed the known loops; further regressions belong in their own tickets.
+- Changes to `ChannelLiveStatus` enum / `channelLiveStatusResponseSchema`. The `"connecting"` value already existed and renders correctly; adding a new `"unknown"` variant would require SDK regeneration and UI work for no additional user benefit.
+- `openclaw-ws-client.ts` reconnection policy.