fix(cli): keep logs follow on live gateway state

vincentkoc · vincentkoc · commit dc7505a73d4c · 2026-05-22T19:26:52.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -63,6 +63,7 @@ Docs: https://docs.openclaw.ai
 - Codex app-server: keep native web search observations out of mirrored chat transcripts while preserving tool progress telemetry. Fixes #85109. Thanks @ugitmebaby.
 - OpenCode Go: strip unsupported Kimi reasoning replay fields before provider requests so repeated `kimi-k2.6` turns do not fail schema validation. Fixes #83812. Thanks @Sleeck.
 - Browser/CDP: add a WSL2 portproxy self-loop hint when Chrome DevTools endpoints accept connections but return an empty HTTP reply. Fixes #59209. Thanks @Owlock.
+- CLI/logs: read implicit local Gateway logs through the passive backend client path so `openclaw logs --follow` does not register as a paired device, and stop following stale configured-file fallbacks after live RPC failures. Fixes #83656 and #66841.
 - Agents/OpenAI: preserve structured provider error code, type, and redacted body metadata on boundary-aware transport failures.
 - Doctor/Codex: point native Codex asset warnings at the canonical `openclaw migrate plan codex` preview command. Fixes #84948. Thanks @markoa.
 - CLI/models: make `capability model auth logout --agent` remove auth profiles from the selected non-default agent store. Fixes #85092. Thanks @islandpreneur007.
diff --git a/docs/cli/logs.md b/docs/cli/logs.md
@@ -57,6 +57,7 @@ openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
 
 - Use `--local-time` to render timestamps in your local timezone.
 - If the implicit local loopback Gateway asks for pairing, closes during connect, or times out before `logs.tail` answers, `openclaw logs` falls back to the configured Gateway file log automatically. Explicit `--url` targets do not use this fallback.
+- `openclaw logs --follow` does not fall back to configured files after Gateway RPC failures, because following a stale side-by-side log can hide the active Gateway's real state.
 - When using `--follow`, transient gateway disconnects (WebSocket close, timeout, connection drop) trigger automatic reconnection with exponential backoff (up to 8 retries, capped at 30 s between attempts). A warning is printed to stderr on each retry, and a `[logs] gateway reconnected` notice is printed once a poll succeeds. In `--json` mode both the retry warning and the reconnect transition are emitted as `{"type":"notice"}` records on stderr. Non-recoverable errors (auth failure, bad configuration) still exit immediately.
 
 ## Related
diff --git a/src/cli/logs-cli.test.ts b/src/cli/logs-cli.test.ts
@@ -132,6 +132,47 @@ describe("logs cli", () => {
     expect(stderrWrites.join("")).toContain("Log cursor reset");
   });
 
+  it("uses the passive local Gateway client for implicit loopback log reads", async () => {
+    callGatewayFromCli.mockResolvedValueOnce({
+      file: "/tmp/openclaw.log",
+      lines: ["raw line"],
+    });
+
+    captureStdoutWrites();
+
+    await runLogsCli(["logs"]);
+
+    expect(callGatewayFromCli).toHaveBeenCalledWith(
+      "logs.tail",
+      expect.any(Object),
+      { cursor: undefined, limit: 200, maxBytes: 250_000 },
+      {
+        progress: true,
+        clientName: "gateway-client",
+        mode: "backend",
+        deviceIdentity: null,
+      },
+    );
+  });
+
+  it("keeps explicit Gateway URLs on the normal CLI client identity", async () => {
+    callGatewayFromCli.mockResolvedValueOnce({
+      file: "/tmp/openclaw.log",
+      lines: ["raw line"],
+    });
+
+    captureStdoutWrites();
+
+    await runLogsCli(["logs", "--url", "ws://127.0.0.1:18789"]);
+
+    expect(callGatewayFromCli).toHaveBeenCalledWith(
+      "logs.tail",
+      expect.any(Object),
+      { cursor: undefined, limit: 200, maxBytes: 250_000 },
+      { progress: true },
+    );
+  });
+
   it("wires --local-time through CLI parsing and emits local timestamps", async () => {
     callGatewayFromCli.mockResolvedValueOnce({
       file: "/tmp/openclaw.log",
@@ -278,39 +319,32 @@ describe("logs cli", () => {
   });
 
   describe("--follow retry behavior", () => {
-    it("uses local fallback (not retry warning) for loopback close errors in --follow mode", async () => {
-      // Loopback close errors are absorbed by shouldUseLocalLogsFallback inside fetchLogs —
-      // they never reach the retry path, so no "gateway disconnected" warning is emitted.
-      callGatewayFromCli.mockRejectedValueOnce(
-        new GatewayTransportError({
-          kind: "closed",
-          code: 1006,
-          reason: "abnormal closure",
-          connectionDetails: {
-            url: "ws://127.0.0.1:18789",
-            urlSource: "local loopback",
-            message: "",
-          },
-          message: "gateway closed (1006 abnormal closure): abnormal closure",
-        }),
-      );
-      readConfiguredLogTail.mockResolvedValueOnce({
-        file: "/tmp/openclaw.log",
-        cursor: 5,
-        lines: ["local fallback line"],
-        truncated: false,
-        reset: false,
+    it("retries loopback close errors in --follow mode instead of tailing fallback files", async () => {
+      const closeError = new GatewayTransportError({
+        kind: "closed",
+        code: 1006,
+        reason: "abnormal closure",
+        connectionDetails: {
+          url: "ws://127.0.0.1:18789",
+          urlSource: "local loopback",
+          message: "",
+        },
+        message: "gateway closed (1006 abnormal closure): abnormal closure",
       });
+      for (let i = 0; i <= 8; i += 1) {
+        callGatewayFromCli.mockRejectedValueOnce(closeError);
+      }
 
       const stderrWrites = captureStderrWrites();
       const stdoutWrites = captureStdoutWrites();
       const exitSpy = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
 
       await runLogsCli(["logs", "--follow", "--interval", "1"]);
 
-      expect(stderrWrites.join("")).toContain("Local Gateway RPC unavailable");
-      expect(stderrWrites.join("")).not.toContain("gateway disconnected");
-      expect(stdoutWrites.join("")).toContain("local fallback line");
+      expect(readConfiguredLogTail).not.toHaveBeenCalled();
+      expect((stderrWrites.join("").match(/gateway disconnected/g) ?? []).length).toBe(8);
+      expect(stderrWrites.join("")).toContain("Gateway not reachable");
+      expect(stdoutWrites.join("")).not.toContain("local fallback line");
       expect(exitSpy).toHaveBeenCalledWith(1);
     });
 
diff --git a/src/cli/logs-cli.ts b/src/cli/logs-cli.ts
@@ -6,6 +6,7 @@ import {
   type GatewayConnectionDetails,
 } from "../gateway/call.js";
 import { isLoopbackHost } from "../gateway/net.js";
+import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../gateway/protocol/client-info.js";
 import { readConnectPairingRequiredMessage } from "../gateway/protocol/connect-error-details.js";
 import { computeBackoff } from "../infra/backoff.js";
 import { formatErrorMessage } from "../infra/errors.js";
@@ -78,7 +79,7 @@ async function fetchLogs(
       "logs.tail",
       opts,
       { cursor, limit, maxBytes },
-      { progress: showProgress },
+      buildLogsTailGatewayExtra(opts, showProgress),
     );
     if (!payload || typeof payload !== "object") {
       throw new Error("Unexpected logs.tail response");
@@ -104,6 +105,9 @@ function normalizeErrorMessage(error: unknown): string {
 }
 
 function shouldUseLocalLogsFallback(opts: LogsCliOptions, error: unknown): boolean {
+  if (opts.follow) {
+    return false;
+  }
   if (!isLocalGatewayRpcUnavailableError(error)) {
     return false;
   }
@@ -116,6 +120,26 @@ function shouldUseLocalLogsFallback(opts: LogsCliOptions, error: unknown): boole
   return isImplicitLoopbackGatewayConnection(connection);
 }
 
+function buildLogsTailGatewayExtra(opts: LogsCliOptions, showProgress: boolean) {
+  const base = { progress: showProgress };
+  if (!shouldUsePassiveLocalLogsClient(opts)) {
+    return base;
+  }
+  return {
+    ...base,
+    clientName: GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT,
+    mode: GATEWAY_CLIENT_MODES.BACKEND,
+    deviceIdentity: null,
+  };
+}
+
+function shouldUsePassiveLocalLogsClient(opts: LogsCliOptions): boolean {
+  if (typeof opts.url === "string" && opts.url.trim().length > 0) {
+    return false;
+  }
+  return isImplicitLoopbackGatewayConnection(buildGatewayConnectionDetails());
+}
+
 function isImplicitLoopbackGatewayConnection(connection: GatewayConnectionDetails): boolean {
   if (connection.urlSource !== "local loopback") {
     return false;
