fix(gateway): accept port for health and probe

BryanTegomoh · BryanTegomoh · commit 6ba0afbe106c · 2026-06-18T16:54:15.000-05:00
diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md
@@ -165,10 +165,15 @@ When you set `--url`, the CLI does not fall back to config or environment creden
 
 ```bash
 openclaw gateway health --url ws://127.0.0.1:18789
+openclaw gateway health --port 18789
 ```
 
 The HTTP `/healthz` endpoint is a liveness probe: it returns once the server can answer HTTP. The HTTP `/readyz` endpoint is stricter and stays red while startup plugin sidecars, channels, or configured hooks are still settling. Local or authenticated detailed readiness responses include an `eventLoop` diagnostic block with event-loop delay, event-loop utilization, CPU core ratio, and a `degraded` flag.
 
+<ParamField path="--port <port>" type="number">
+  Target a local loopback Gateway on this port.
+</ParamField>
+
 ### `gateway usage-cost`
 
 Fetch usage-cost summaries from session logs.
@@ -340,8 +345,13 @@ If multiple probe targets are reachable, it prints all of them. An SSH tunnel, T
 ```bash
 openclaw gateway probe
 openclaw gateway probe --json
+openclaw gateway probe --port 18789
 ```
 
+<ParamField path="--port <port>" type="number">
+  Use this port for the local loopback probe target and SSH tunnel remote port.
+</ParamField>
+
 <AccordionGroup>
   <Accordion title="Interpretation">
     - `Reachable: yes` means at least one target accepted a WebSocket connect.
diff --git a/src/cli/gateway-cli/call.ts b/src/cli/gateway-cli/call.ts
@@ -17,6 +17,7 @@ export type GatewayRpcOpts = {
   timeout?: string;
   expectFinal?: boolean;
   json?: boolean;
+  localPortOverride?: number;
 };
 
 const DEFAULT_GATEWAY_RPC_TIMEOUT_MS = 10_000;
@@ -50,6 +51,7 @@ export const callGatewayCli = async (method: string, opts: GatewayRpcOpts, param
         params,
         expectFinal: Boolean(opts.expectFinal),
         timeoutMs,
+        localPortOverride: opts.localPortOverride,
         clientName: GATEWAY_CLIENT_NAMES.CLI,
         mode: GATEWAY_CLIENT_MODES.CLI,
       }),
diff --git a/src/cli/gateway-cli/register.option-collisions.test.ts b/src/cli/gateway-cli/register.option-collisions.test.ts
@@ -68,6 +68,7 @@ vi.mock("../daemon-cli/register-service-commands.js", () => ({
 }));
 
 vi.mock("../../commands/health.js", () => ({
+  emitReachableGatewayAuthDiagnostic: vi.fn(async () => false),
   formatHealthChannelLines: () => [],
 }));
 
@@ -171,6 +172,32 @@ describe("gateway register option collisions", () => {
         expect(runtime).toBe(defaultRuntime);
       },
     },
+    {
+      name: "forwards --port to gateway probe",
+      argv: ["gateway", "probe", "--port", "19080", "--json"],
+      assert: () => {
+        expect(gatewayStatusCommand).toHaveBeenCalledTimes(1);
+        const [opts] = firstGatewayStatusCall();
+        expect((opts as { port?: string } | undefined)?.port).toBe("19080");
+      },
+    },
+    {
+      name: "projects gateway health --port into local config",
+      argv: ["gateway", "health", "--port", "19081", "--json"],
+      assert: () => {
+        expect(defaultRuntime.error.mock.calls).toEqual([]);
+        expect(callGatewayCli).toHaveBeenCalledTimes(1);
+        const [method, opts] = firstGatewayCall();
+        expect(method).toBe("health");
+        const gatewayOpts = opts as
+          | { config?: { gateway?: { port?: number } }; localPortOverride?: number }
+          | undefined;
+        expect(gatewayOpts?.localPortOverride).toBe(19081);
+        expect(gatewayOpts?.config).toEqual({
+          gateway: { mode: "local", port: 19081 },
+        });
+      },
+    },
     {
       name: "passes decimal usage-cost --days values",
       argv: ["gateway", "usage-cost", "--days", "7", "--json"],
diff --git a/src/cli/gateway-cli/register.ts b/src/cli/gateway-cli/register.ts
@@ -18,6 +18,7 @@ import { defaultRuntime } from "../../runtime.js";
 import { createLazyImportLoader } from "../../shared/lazy-promise.js";
 import { inheritOptionFromParent } from "../command-options.js";
 import { addGatewayServiceCommands } from "../daemon-cli/register-service-commands.js";
+import { parseGatewayPortOption } from "../gateway-port-option.js";
 import { formatHelpExamples } from "../help-format.js";
 import type { GatewayRpcOpts } from "./call.js";
 import type { GatewayDiscoverOpts } from "./discover.js";
@@ -168,6 +169,34 @@ function resolveGatewayRpcOptions<T extends { token?: string; password?: string
   };
 }
 
+async function resolveGatewayRpcOptionsWithLocalPort(
+  opts: GatewayRpcOpts & { port?: unknown },
+  command?: Command,
+): Promise<GatewayRpcOpts> {
+  const rpcOpts = resolveGatewayRpcOptions(opts, command);
+  const port = parseGatewayPortOption(opts.port ?? inheritOptionFromParent(command, "port"));
+  if (port === undefined) {
+    return rpcOpts;
+  }
+  if (typeof opts.url === "string" && opts.url.trim()) {
+    throw new Error("Use either --url or --port, not both.");
+  }
+  const { readBestEffortConfig } = await loadConfigModule();
+  const config = await readBestEffortConfig();
+  return {
+    ...rpcOpts,
+    localPortOverride: port,
+    config: {
+      ...config,
+      gateway: {
+        ...config.gateway,
+        mode: "local",
+        port,
+      },
+    },
+  };
+}
+
 async function renderCostUsageSummaryAsync(
   summary: CostUsageSummary,
   days: number,
@@ -553,10 +582,11 @@ export function registerGatewayCli(program: Command) {
     gateway
       .command("health")
       .description("Fetch Gateway health")
+      .option("--port <port>", "Local Gateway port")
       .action(async (opts, command) => {
         await runGatewayCommand(
           async () => {
-            const rpcOpts = resolveGatewayRpcOptions(opts, command);
+            const rpcOpts = await resolveGatewayRpcOptionsWithLocalPort(opts, command);
             const [
               { emitReachableGatewayAuthDiagnostic, formatHealthChannelLines },
               { styleHealthChannelLine },
@@ -728,6 +758,7 @@ export function registerGatewayCli(program: Command) {
       "Show gateway reachability, auth capability, and read-probe summary (local + remote)",
     )
     .option("--url <url>", "Explicit Gateway WebSocket URL (still probes localhost)")
+    .option("--port <port>", "Local Gateway port")
     .option("--ssh <target>", "SSH target for remote gateway tunnel (user@host or user@host:port)")
     .option("--ssh-identity <path>", "SSH identity file path")
     .option("--ssh-auto", "Try to derive an SSH target from Bonjour discovery", false)
@@ -739,7 +770,13 @@ export function registerGatewayCli(program: Command) {
       await runGatewayCommand(async () => {
         const rpcOpts = resolveGatewayRpcOptions(opts, command);
         const { gatewayStatusCommand } = await loadGatewayStatusModule();
-        await gatewayStatusCommand(rpcOpts, defaultRuntime);
+        await gatewayStatusCommand(
+          {
+            ...rpcOpts,
+            port: opts.port ?? inheritOptionFromParent(command, "port"),
+          },
+          defaultRuntime,
+        );
       });
     });
 
diff --git a/src/cli/gateway-port-option.test.ts b/src/cli/gateway-port-option.test.ts
@@ -0,0 +1,21 @@
+// Gateway port option tests cover strict CLI validation before transports open.
+import { describe, expect, it } from "vitest";
+import { parseGatewayPortOption } from "./gateway-port-option.js";
+
+describe("parseGatewayPortOption", () => {
+  it("accepts TCP port values", () => {
+    expect(parseGatewayPortOption("18789")).toBe(18789);
+    expect(parseGatewayPortOption(65_535)).toBe(65_535);
+  });
+
+  it("treats absent values as no override", () => {
+    expect(parseGatewayPortOption(undefined)).toBeUndefined();
+    expect(parseGatewayPortOption("")).toBeUndefined();
+  });
+
+  it.each(["0", "65536", "1e4", "18789ms"])("rejects invalid port value %s", (value) => {
+    expect(() => parseGatewayPortOption(value)).toThrow(
+      "--port must be an integer between 1 and 65535.",
+    );
+  });
+});
diff --git a/src/cli/gateway-port-option.ts b/src/cli/gateway-port-option.ts
@@ -0,0 +1,26 @@
+// Shared parser for CLI flags that select a local Gateway TCP port.
+import { parseStrictPositiveInteger } from "../infra/parse-finite-number.js";
+
+const MAX_TCP_PORT = 65_535;
+
+export function parseGatewayPortOption(raw: unknown, flagName = "--port"): number | undefined {
+  if (raw === undefined || raw === null) {
+    return undefined;
+  }
+
+  const value =
+    typeof raw === "string"
+      ? raw.trim()
+      : typeof raw === "number" || typeof raw === "bigint"
+        ? String(raw)
+        : "";
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = parseStrictPositiveInteger(value);
+  if (parsed === undefined || parsed > MAX_TCP_PORT) {
+    throw new Error(`${flagName} must be an integer between 1 and ${MAX_TCP_PORT}.`);
+  }
+  return parsed;
+}
diff --git a/src/commands/gateway-status.test.ts b/src/commands/gateway-status.test.ts
@@ -297,7 +297,14 @@ function mockLocalTokenEnvRefConfig(envTokenId = "MISSING_GATEWAY_TOKEN") {
 
 async function runGatewayStatus(
   runtime: ReturnType<typeof createRuntimeCapture>["runtime"],
-  opts: { timeout: string; json?: boolean; ssh?: string; sshAuto?: boolean; sshIdentity?: string },
+  opts: {
+    timeout: string;
+    json?: boolean;
+    port?: unknown;
+    ssh?: string;
+    sshAuto?: boolean;
+    sshIdentity?: string;
+  },
 ) {
   await gatewayStatusCommand(opts, asRuntimeEnv(runtime));
 }
@@ -914,6 +921,27 @@ describe("gateway-status command", () => {
     expect(requireProbeCall("ws://127.0.0.1:18789").timeoutMs).toBe(15_000);
   });
 
+  it("uses --port for the local loopback probe target", async () => {
+    const { runtime, runtimeLogs, runtimeErrors } = createRuntimeCapture();
+    probeGateway.mockClear();
+    readBestEffortConfig.mockResolvedValueOnce({
+      gateway: {
+        mode: "local",
+        port: 18789,
+        auth: { mode: "token", token: "ltok" },
+      },
+    } as never);
+
+    await runGatewayStatus(runtime, { timeout: "15000", json: true, port: "19080" });
+
+    expect(runtimeErrors).toHaveLength(0);
+    expect(requireProbeCall("ws://127.0.0.1:19080").timeoutMs).toBe(15_000);
+    const parsed = JSON.parse(runtimeLogs.join("\n")) as {
+      network?: { localLoopbackUrl?: string | null };
+    };
+    expect(parsed.network?.localLoopbackUrl).toBe("ws://127.0.0.1:19080");
+  });
+
   it("uses configured handshake timeout as the default local probe budget", async () => {
     const { runtime } = createRuntimeCapture();
     probeGateway.mockClear();
diff --git a/src/commands/gateway-status.ts b/src/commands/gateway-status.ts
@@ -1,5 +1,6 @@
 /** CLI entrypoint for `openclaw gateway status`. */
 import { isRich } from "../../packages/terminal-core/src/theme.js";
+import { parseGatewayPortOption } from "../cli/gateway-port-option.js";
 import { withProgress } from "../cli/progress.js";
 import { readBestEffortConfig, resolveGatewayPort } from "../config/config.js";
 import { resolveWideAreaDiscoveryDomain } from "../infra/widearea-dns.js";
@@ -42,6 +43,7 @@ export async function gatewayStatusCommand(
     url?: string;
     token?: string;
     password?: string;
+    port?: unknown;
     timeout?: unknown;
     json?: boolean;
     ssh?: string;
@@ -55,12 +57,13 @@ export async function gatewayStatusCommand(
   const rich = isRich() && opts.json !== true;
   const defaultTimeoutMs = Math.max(3000, cfg.gateway?.handshakeTimeoutMs ?? 0);
   const overallTimeoutMs = parseTimeoutMs(opts.timeout, defaultTimeoutMs);
+  const portOverride = parseGatewayPortOption(opts.port);
   const wideAreaDomain = resolveWideAreaDiscoveryDomain({
     configDomain: cfg.discovery?.wideArea?.domain,
   });
-  const baseTargets = resolveTargets(cfg, opts.url);
-  const network = buildNetworkHints(cfg);
-  const remotePort = resolveGatewayPort(cfg);
+  const baseTargets = resolveTargets(cfg, opts.url, portOverride);
+  const network = buildNetworkHints(cfg, portOverride);
+  const remotePort = portOverride ?? resolveGatewayPort(cfg);
   const discoveryTimeoutMs = Math.min(1200, overallTimeoutMs);
 
   let sshTarget = sanitizeSshTarget(opts.ssh) ?? sanitizeSshTarget(cfg.gateway?.remote?.sshTarget);
diff --git a/src/commands/gateway-status/helpers.test.ts b/src/commands/gateway-status/helpers.test.ts
@@ -316,6 +316,22 @@ describe("gateway-status local target scheme", () => {
     const hints = buildNetworkHints(cfg as never);
     expect(hints.localLoopbackUrl).toBe("wss://127.0.0.1:18789");
   });
+
+  it("uses a local port override for loopback targets and network hints", () => {
+    const cfg = {
+      gateway: {
+        mode: "local",
+        port: 18789,
+      },
+    };
+
+    const targets = resolveTargets(cfg as never, undefined, 19080);
+    const localLoopbackTarget = targets.find((target) => target.id === "localLoopback");
+    expect(localLoopbackTarget?.url).toBe("ws://127.0.0.1:19080");
+
+    const hints = buildNetworkHints(cfg as never, 19080);
+    expect(hints.localLoopbackUrl).toBe("ws://127.0.0.1:19080");
+  });
 });
 
 describe("resolveProbeBudgetMs", () => {
diff --git a/src/commands/gateway-status/helpers.ts b/src/commands/gateway-status/helpers.ts
@@ -87,7 +87,11 @@ function normalizeWsUrl(value: string): string | null {
 }
 
 /** Builds the deduplicated ordered gateway probe targets from CLI input and config. */
-export function resolveTargets(cfg: OpenClawConfig, explicitUrl?: string): GatewayStatusTarget[] {
+export function resolveTargets(
+  cfg: OpenClawConfig,
+  explicitUrl?: string,
+  localPortOverride?: number,
+): GatewayStatusTarget[] {
   const targets: GatewayStatusTarget[] = [];
   const add = (t: GatewayStatusTarget) => {
     if (!targets.some((x) => x.url === t.url)) {
@@ -111,7 +115,7 @@ export function resolveTargets(cfg: OpenClawConfig, explicitUrl?: string): Gatew
     });
   }
 
-  const port = resolveGatewayPort(cfg);
+  const port = localPortOverride ?? resolveGatewayPort(cfg);
   const localScheme = cfg.gateway?.tls?.enabled === true ? "wss" : "ws";
   add({
     id: "localLoopback",
@@ -252,10 +256,10 @@ export function extractConfigSummary(snapshotUnknown: unknown): GatewayConfigSum
   };
 }
 
-/** Builds local and tailnet gateway URL hints for the configured gateway port. */
-export function buildNetworkHints(cfg: OpenClawConfig) {
+/** Builds local and tailnet gateway URL hints for the selected gateway port. */
+export function buildNetworkHints(cfg: OpenClawConfig, localPortOverride?: number) {
   const { tailnetIPv4 } = inspectBestEffortPrimaryTailnetIPv4();
-  const port = resolveGatewayPort(cfg);
+  const port = localPortOverride ?? resolveGatewayPort(cfg);
   const localScheme = cfg.gateway?.tls?.enabled === true ? "wss" : "ws";
   return {
     localLoopbackUrl: `${localScheme}://127.0.0.1:${port}`,
diff --git a/src/gateway/call.test.ts b/src/gateway/call.test.ts
@@ -626,6 +626,29 @@ describe("callGateway url resolution", () => {
     expect(lastClientOptions?.password).toBeUndefined();
   });
 
+  it("lets an explicit local port override bypass gateway env URL and port", async () => {
+    getRuntimeConfig.mockReturnValue({
+      gateway: { mode: "local", bind: "loopback" },
+    });
+    resolveGatewayPort.mockImplementation((_config?: unknown, env?: unknown) => {
+      const candidateEnv = env as NodeJS.ProcessEnv | undefined;
+      return Number(candidateEnv?.OPENCLAW_GATEWAY_PORT ?? 18789);
+    });
+    pickPrimaryTailnetIPv4.mockReturnValue(undefined);
+    process.env.OPENCLAW_GATEWAY_URL = "wss://gateway-in-container.internal:9443/ws";
+    process.env.OPENCLAW_GATEWAY_PORT = "19001";
+    process.env.OPENCLAW_GATEWAY_TOKEN = "env-token";
+
+    await callGateway({
+      method: "health",
+      token: "explicit-token",
+      localPortOverride: 19082,
+    });
+
+    expect(lastClientOptions?.url).toBe("ws://127.0.0.1:19082");
+    expect(lastClientOptions?.token).toBe("explicit-token");
+  });
+
   it("uses env URL override credentials without resolving local password SecretRefs", async () => {
     getRuntimeConfig.mockReturnValue({
       gateway: {
diff --git a/src/gateway/call.ts b/src/gateway/call.ts
diff --git a/src/gateway/connection-details.ts b/src/gateway/connection-details.ts
