From beb569a5a3e3072d227dbf4cef9ad48499781085 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 29 Apr 2026 16:58:55 -0700 Subject: [PATCH] fix(gateway): surface unreachable status diagnostics --- CHANGELOG.md | 1 + src/commands/gateway-status.test.ts | 40 ++++++++++++++++++++++ src/commands/gateway-status.ts | 1 + src/commands/gateway-status/output.test.ts | 31 ++++++++++++++++- src/commands/gateway-status/output.ts | 11 ++++++ 5 files changed, 83 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 341e2760a56..61be2b38b5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai - Status: show the `openai-codex` OAuth profile for `openai/gpt-*` sessions running through the native Codex runtime instead of reporting auth as unknown. (#76197) Thanks @mbelinky. - Plugins/externalization: keep diagnostics ClawHub packages and persisted bundled-plugin relocation on npm-first install metadata for launch, and omit Discord from the core package now that its external package is published. Thanks @vincentkoc. - Plugins/Codex: allow the official npm Codex plugin to install without the unsafe-install override, keep `/codex` command ownership, and cover the real npm Docker live path through managed `.openclaw/npm` dependencies plus uninstall failure proof. +- Gateway/status: add concrete service, config, listener-owner, and log collection next steps when gateway probes fail and Bonjour finds no local gateway, so frozen or port-conflict reports include the data needed for root-cause triage. Refs #49012. Thanks @vincentkoc. ## 2026.5.2 diff --git a/src/commands/gateway-status.test.ts b/src/commands/gateway-status.test.ts index d7205441b83..152d99f168b 100644 --- a/src/commands/gateway-status.test.ts +++ b/src/commands/gateway-status.test.ts @@ -312,6 +312,46 @@ describe("gateway-status command", () => { expect(targets[0]?.summary).toBeTruthy(); }); + it("includes diagnostic next steps when no gateway is reachable or discoverable", async () => { + const { runtime, runtimeLogs, runtimeErrors } = createRuntimeCapture(); + const defaultProbeGateway = probeGateway.getMockImplementation(); + try { + probeGateway.mockImplementation(async (opts: { url: string }) => ({ + ok: false, + url: opts.url, + connectLatencyMs: null, + error: "connection refused", + close: null, + auth: { + role: null, + scopes: [], + capability: "unknown", + }, + health: null, + status: null, + presence: null, + configSnapshot: null, + })); + + await expect(runGatewayStatus(runtime, { timeout: "1000", json: true })).rejects.toThrow( + "__exit__:1", + ); + } finally { + probeGateway.mockReset(); + if (defaultProbeGateway) { + probeGateway.mockImplementation(defaultProbeGateway); + } + } + + expect(runtimeErrors).toHaveLength(0); + const parsed = JSON.parse(runtimeLogs.join("\n")) as { + warnings?: Array<{ code?: string; message?: string }>; + }; + const warning = parsed.warnings?.find((entry) => entry.code === "no_gateway_reachable"); + expect(warning?.message).toContain("openclaw gateway status --deep --require-rpc"); + expect(warning?.message).toContain("ss -ltnp"); + }); + it("omits discovery wsUrl when only TXT hints are present", async () => { const { runtime, runtimeLogs, runtimeErrors } = createRuntimeCapture(); discoverGatewayBeacons.mockResolvedValueOnce([ diff --git a/src/commands/gateway-status.ts b/src/commands/gateway-status.ts index 1f6d8a79e83..099a8b44be6 100644 --- a/src/commands/gateway-status.ts +++ b/src/commands/gateway-status.ts @@ -121,6 +121,7 @@ export async function gatewayStatusCommand( sshTarget: probePass.sshTarget, sshTunnelStarted: probePass.sshTunnelStarted, sshTunnelError: probePass.sshTunnelError, + discoveryCount: probePass.discovery.length, localTlsLoadError: localTlsRuntime && !localTlsRuntime.enabled && localTlsRuntime.required ? (localTlsRuntime.error ?? "gateway tls is enabled but local TLS runtime could not load") diff --git a/src/commands/gateway-status/output.test.ts b/src/commands/gateway-status/output.test.ts index 87b3164ed2a..09d99b2ed33 100644 --- a/src/commands/gateway-status/output.test.ts +++ b/src/commands/gateway-status/output.test.ts @@ -18,7 +18,8 @@ vi.mock("../../terminal/theme.js", async () => { }; }); -const { writeGatewayStatusJson, writeGatewayStatusText } = await import("./output.js"); +const { buildGatewayStatusWarnings, writeGatewayStatusJson, writeGatewayStatusText } = + await import("./output.js"); function createRuntimeCapture(): RuntimeEnv { return { @@ -80,6 +81,34 @@ describe("gateway status output", () => { writeRuntimeJson.mockReset(); }); + it("warns with diagnostic next steps when no probes or Bonjour discovery find a gateway", () => { + const warnings = buildGatewayStatusWarnings({ + probed: [ + createTarget( + "localLoopback", + createProbe("unknown", { + ok: false, + connectLatencyMs: null, + error: "connection refused", + }), + ), + ], + sshTarget: null, + sshTunnelStarted: false, + sshTunnelError: null, + discoveryCount: 0, + }); + + expect(warnings).toContainEqual( + expect.objectContaining({ + code: "no_gateway_reachable", + message: expect.stringContaining("openclaw gateway status --deep --require-rpc"), + targetIds: ["localLoopback"], + }), + ); + expect(warnings.at(0)?.message).toContain("lsof -nP -iTCP:"); + }); + it("derives summary capability from reachable probes only in json output", () => { const runtime = createRuntimeCapture(); writeGatewayStatusJson({ diff --git a/src/commands/gateway-status/output.ts b/src/commands/gateway-status/output.ts index a17c31d3377..3bf89ce80c7 100644 --- a/src/commands/gateway-status/output.ts +++ b/src/commands/gateway-status/output.ts @@ -18,6 +18,9 @@ export type GatewayStatusWarning = { targetIds?: string[]; }; +const noReachableGatewayDiagnostic = + "No gateway answered any probe and Bonjour discovery returned no local gateways. Run `openclaw gateway status --deep --require-rpc` to inspect service state, config paths, listener owners, and logs; include `ss -ltnp` or `lsof -nP -iTCP: -sTCP:LISTEN` for the configured port when filing a report."; + export function pickPrimaryProbedTarget(probed: GatewayStatusProbedTarget[]) { const reachable = probed.filter((entry) => isProbeReachable(entry.probe)); return ( @@ -35,6 +38,7 @@ export function buildGatewayStatusWarnings(params: { sshTunnelStarted: boolean; sshTunnelError: string | null; localTlsLoadError?: string | null; + discoveryCount?: number; }): GatewayStatusWarning[] { const reachable = params.probed.filter((entry) => isProbeReachable(entry.probe)); const degradedScopeLimited = params.probed.filter((entry) => @@ -59,6 +63,13 @@ export function buildGatewayStatusWarnings(params: { targetIds: ["localLoopback"], }); } + if (reachable.length === 0 && params.discoveryCount === 0) { + warnings.push({ + code: "no_gateway_reachable", + message: noReachableGatewayDiagnostic, + targetIds: params.probed.map((entry) => entry.target.id), + }); + } if (reachable.length > 1) { warnings.push({ code: "multiple_gateways",