fix(tui): follow active gateway port

steipete · vincentkoc · steipete · commit 6a1a9bbc31e0 · 2026-07-06T00:03:46.000-04:00
Co-authored-by: haishmg &lt;4529977+haishmg@users.noreply.github.com&gt;

Co-authored-by: Vincent Koc &lt;vincentkoc@ieee.org&gt;
diff --git a/docs/cli/tui.md b/docs/cli/tui.md
@@ -38,6 +38,9 @@ Aliases: `openclaw chat` and `openclaw terminal` invoke this command with
 - `--local` cannot combine with `--url`, `--token`, or `--password`.
 - `tui` resolves configured Gateway auth SecretRefs for token/password auth
   when possible (`env`/`file`/`exec` providers).
+- With no explicit URL or port, `tui` follows the active local Gateway port
+  recorded by the running Gateway. Explicit `--url`, `OPENCLAW_GATEWAY_URL`,
+  `OPENCLAW_GATEWAY_PORT`, and remote Gateway config keep precedence.
 - Launched from inside a configured agent workspace directory, TUI auto-selects
   that agent for the session key default (unless `--session` is explicitly
   `agent:<id>:...`).
diff --git a/src/cli/gateway-cli/run-loop.ts b/src/cli/gateway-cli/run-loop.ts
@@ -107,6 +107,11 @@ export async function runGatewayLoop(params: {
   healthHost?: string;
   waitForHealthyChild?: (port: number, pid?: number, host?: string) => Promise<boolean>;
 }) {
+  // macOS/BSD process inspection reports process.title instead of the original
+  // argv. Give the long-running Gateway a verifiable identity for lock readers.
+  if (process.title === "openclaw") {
+    process.title = "openclaw-gateway";
+  }
   let startupStartedAt = Date.now();
   // Eagerly resolve the lifecycle runtime module before installing signal
   // listeners. Without this, every subsequent lifecycle path (SIGUSR1,
diff --git a/src/infra/gateway-lock.test.ts b/src/infra/gateway-lock.test.ts
@@ -9,7 +9,12 @@ import { setTimeout as nativeSleep } from "node:timers/promises";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { resolveConfigPath, resolveStateDir } from "../config/paths.js";
 import { createSuiteTempRootTracker } from "../test-helpers/temp-dir.js";
-import { acquireGatewayLock, GatewayLockError, type GatewayLockOptions } from "./gateway-lock.js";
+import {
+  acquireGatewayLock,
+  GatewayLockError,
+  readActiveGatewayLockPort,
+  type GatewayLockOptions,
+} from "./gateway-lock.js";
 
 type GatewayLock = NonNullable<Awaited<ReturnType<typeof acquireGatewayLock>>>;
 
@@ -94,11 +99,17 @@ function makeProcStat(pid: number, startTime: number) {
   return `${pid} (node) ${fields.join(" ")}`;
 }
 
-function createLockPayload(params: { configPath: string; startTime: number; createdAt?: string }) {
+function createLockPayload(params: {
+  configPath: string;
+  startTime: number;
+  createdAt?: string;
+  port?: number;
+}) {
   return {
     pid: process.pid,
     createdAt: params.createdAt ?? new Date().toISOString(),
     configPath: params.configPath,
+    ...(params.port ? { port: params.port } : {}),
     startTime: params.startTime,
   };
 }
@@ -199,6 +210,66 @@ describe("gateway lock", () => {
     await expectGatewayLock(lock2).release();
   });
 
+  it("records and reads the active runtime port from a verified gateway lock", async () => {
+    const env = await makeEnv();
+    const lock = expectGatewayLock(
+      await acquireForTest(env, {
+        platform: "darwin",
+        port: 48789,
+        readProcessCmdline: () => ["openclaw-gateway"],
+      }),
+    );
+
+    try {
+      await expect(
+        readActiveGatewayLockPort({
+          env,
+          lockDir: resolveTestLockDir(),
+          platform: "darwin",
+          readProcessCmdline: () => ["openclaw-gateway"],
+        }),
+      ).resolves.toBe(48789);
+    } finally {
+      await lock.release();
+    }
+  });
+
+  it("keeps a retitled gateway lock owned during concurrent acquisition", async () => {
+    const env = await makeEnv();
+    const lock = expectGatewayLock(await acquireForTest(env, { platform: "darwin", port: 48789 }));
+    const connectSpy = createPortProbeConnectionSpy("connect");
+
+    try {
+      await expect(
+        acquireForTest(env, {
+          platform: "darwin",
+          port: 48789,
+          timeoutMs: 15,
+          readProcessCmdline: () => ["openclaw-gateway"],
+        }),
+      ).rejects.toBeInstanceOf(GatewayLockError);
+      expect(connectSpy).toHaveBeenCalled();
+    } finally {
+      await lock.release();
+    }
+  });
+
+  it("ignores active-port metadata when the lock owner cannot be verified", async () => {
+    const env = await makeEnv();
+    const { lockPath, configPath } = resolveLockPath(env);
+    const payload = createLockPayload({ configPath, startTime: 111, port: 48789 });
+    await fs.writeFile(lockPath, JSON.stringify(payload), "utf8");
+
+    await expect(
+      readActiveGatewayLockPort({
+        env,
+        lockDir: resolveTestLockDir(),
+        platform: "darwin",
+        readProcessCmdline: () => null,
+      }),
+    ).resolves.toBeUndefined();
+  });
+
   it("treats recycled linux pid as stale when start time mismatches", async () => {
     const env = await makeEnv();
     const { lockPath, configPath } = resolveLockPath(env);
diff --git a/src/infra/gateway-lock.ts b/src/infra/gateway-lock.ts
@@ -26,13 +26,15 @@ type LockPayload = {
   pid: number;
   createdAt: string;
   configPath: string;
+  port?: number;
   startTime?: number;
 };
 
 const LockPayloadSchema = z.object({
   pid: z.number(),
   createdAt: z.string(),
   configPath: z.string(),
+  port: z.number().int().min(1).max(65_535).optional(),
   startTime: z.number().optional(),
 }) as z.ZodType<LockPayload>;
 
@@ -172,6 +174,7 @@ async function resolveGatewayOwnerStatus(
   platform: NodeJS.Platform,
   port: number | undefined,
   readCmdline?: (pid: number) => string[] | null,
+  opts: { trustUnknownCmdlineOwner?: boolean } = {},
 ): Promise<LockOwnerStatus> {
   if (port != null) {
     const portFree = await checkPortFree(port);
@@ -204,9 +207,11 @@ async function resolveGatewayOwnerStatus(
     // start-time), "unknown" lets the stale-lock heuristic eventually reclaim
     // very old locks. On win32/darwin/other, conservatively assume "alive" to
     // preserve single-instance guarantees when wmic/ps is unavailable.
-    return platform === "linux" ? "unknown" : "alive";
+    return platform === "linux" || opts.trustUnknownCmdlineOwner === false ? "unknown" : "alive";
   }
-  return isGatewayArgv(args) ? "alive" : "dead";
+  // Long-running gateways retitle themselves so macOS/BSD process inspection
+  // can identify the owner after the original argv is no longer available.
+  return isGatewayArgv(args, { allowGatewayBinary: true }) ? "alive" : "dead";
 }
 
 async function readLockPayload(lockPath: string): Promise<LockPayload | null> {
@@ -226,6 +231,26 @@ function resolveGatewayLockPath(env: NodeJS.ProcessEnv, lockDir = resolveGateway
   return { lockPath, configPath };
 }
 
+export async function readActiveGatewayLockPort(
+  opts: Pick<GatewayLockOptions, "env" | "lockDir" | "platform" | "readProcessCmdline"> = {},
+): Promise<number | undefined> {
+  const env = opts.env ?? process.env;
+  const { lockPath } = resolveGatewayLockPath(env, opts.lockDir);
+  const payload = await readLockPayload(lockPath);
+  if (!payload?.port) {
+    return undefined;
+  }
+  const ownerStatus = await resolveGatewayOwnerStatus(
+    payload.pid,
+    payload,
+    opts.platform ?? process.platform,
+    undefined,
+    opts.readProcessCmdline,
+    { trustUnknownCmdlineOwner: false },
+  );
+  return ownerStatus === "alive" ? payload.port : undefined;
+}
+
 export async function acquireGatewayLock(
   opts: GatewayLockOptions = {},
 ): Promise<GatewayLockHandle | null> {
@@ -269,6 +294,9 @@ export async function acquireGatewayLock(
           createdAt: resolveTimestampMsToIsoString(now()),
           configPath,
         };
+        if (typeof port === "number" && Number.isInteger(port) && port > 0 && port <= 65_535) {
+          payload.port = port;
+        }
         if (typeof startTime === "number" && Number.isFinite(startTime)) {
           payload.startTime = startTime;
         }
diff --git a/src/infra/gateway-process-argv.test.ts b/src/infra/gateway-process-argv.test.ts
@@ -34,6 +34,7 @@ describe("isGatewayArgv", () => {
   it("matches the openclaw executable but gates the gateway binary behind the opt-in flag", () => {
     expect(isGatewayArgv(["C:\\bin\\openclaw.cmd", "gateway"])).toBe(true);
     expect(isGatewayArgv(["/usr/local/bin/openclaw-gateway", "gateway"])).toBe(false);
+    expect(isGatewayArgv(["openclaw-gateway"])).toBe(false);
     expect(
       isGatewayArgv(["/usr/local/bin/openclaw-gateway", "gateway"], {
         allowGatewayBinary: true,
@@ -44,6 +45,7 @@ describe("isGatewayArgv", () => {
         allowGatewayBinary: true,
       }),
     ).toBe(true);
+    expect(isGatewayArgv(["openclaw-gateway"], { allowGatewayBinary: true })).toBe(true);
   });
 
   it("rejects unknown gateway argv even when the token is present", () => {
diff --git a/src/infra/gateway-process-argv.ts b/src/infra/gateway-process-argv.ts
@@ -12,8 +12,10 @@ export function parseProcCmdline(raw: string): string[] {
 
 export function isGatewayArgv(args: string[], opts?: { allowGatewayBinary?: boolean }): boolean {
   const normalized = args.map(normalizeProcArg);
+  const exe = (normalized[0] ?? "").replace(/\.(bat|cmd|exe)$/i, "");
+  const isGatewayBinary = exe.endsWith("/openclaw-gateway") || exe === "openclaw-gateway";
   if (!normalized.includes("gateway")) {
-    return false;
+    return opts?.allowGatewayBinary === true && isGatewayBinary;
   }
 
   const entryCandidates = [
@@ -28,10 +30,9 @@ export function isGatewayArgv(args: string[], opts?: { allowGatewayBinary?: bool
     return true;
   }
 
-  const exe = (normalized[0] ?? "").replace(/\.(bat|cmd|exe)$/i, "");
   return (
     exe.endsWith("/openclaw") ||
     exe === "openclaw" ||
-    (opts?.allowGatewayBinary === true && exe.endsWith("/openclaw-gateway"))
+    (opts?.allowGatewayBinary === true && isGatewayBinary)
   );
 }
diff --git a/src/tui/gateway-chat.test.ts b/src/tui/gateway-chat.test.ts
@@ -11,6 +11,8 @@ import {
 } from "../gateway/gateway-connection.test-mocks.js";
 import { captureEnv, withEnvAsync } from "../test-utils/env.js";
 
+const readActiveGatewayLockPortMock = vi.hoisted(() => vi.fn());
+
 vi.mock("../config/config.js", async () => {
   const mocks = await import("../gateway/gateway-connection.test-mocks.js");
   return {
@@ -31,6 +33,10 @@ vi.mock("../gateway/net.js", async () => {
   };
 });
 
+vi.mock("../infra/gateway-lock.js", () => ({
+  readActiveGatewayLockPort: readActiveGatewayLockPortMock,
+}));
+
 const { GatewayChatClient, resolveGatewayConnection } = await import("./gateway-chat.js");
 const { GatewayClientRequestError } = await import("../gateway/client.js");
 
@@ -110,11 +116,13 @@ describe("resolveGatewayConnection", () => {
   beforeEach(() => {
     envSnapshot = captureEnv([
       "OPENCLAW_GATEWAY_URL",
+      "OPENCLAW_GATEWAY_PORT",
       "OPENCLAW_GATEWAY_TOKEN",
       "OPENCLAW_GATEWAY_PASSWORD",
       "OPENCLAW_TUI_SETUP_AUTH_SOURCE",
     ]);
     loadConfig.mockReset();
+    readActiveGatewayLockPortMock.mockReset().mockResolvedValue(undefined);
     resolveGatewayPort.mockReset();
     resolveStateDir.mockReset();
     resolveConfigPath.mockReset();
@@ -127,6 +135,7 @@ describe("resolveGatewayConnection", () => {
         env.OPENCLAW_CONFIG_PATH ?? `${stateDir}/openclaw.json`,
     );
     delete process.env.OPENCLAW_GATEWAY_URL;
+    delete process.env.OPENCLAW_GATEWAY_PORT;
     delete process.env.OPENCLAW_GATEWAY_TOKEN;
     delete process.env.OPENCLAW_GATEWAY_PASSWORD;
     delete process.env.OPENCLAW_TUI_SETUP_AUTH_SOURCE;
@@ -185,6 +194,32 @@ describe("resolveGatewayConnection", () => {
 
     expect(result.preauthHandshakeTimeoutMs).toBe(30_000);
   });
+
+  it("uses a verified active local Gateway port when no target is explicit", async () => {
+    loadConfig.mockReturnValue({
+      gateway: { mode: "local", port: 18789, auth: { token: "config-token" } },
+    });
+    readActiveGatewayLockPortMock.mockResolvedValue(48789);
+
+    const result = await resolveGatewayConnection({});
+
+    expect(result.url).toBe("ws://127.0.0.1:48789");
+    expect(result.token).toBe("config-token");
+  });
+
+  it("keeps an explicit Gateway port ahead of active lock metadata", async () => {
+    loadConfig.mockReturnValue({
+      gateway: { mode: "local", port: 18789, auth: { token: "config-token" } },
+    });
+    readActiveGatewayLockPortMock.mockResolvedValue(48789);
+
+    await withEnvAsync({ OPENCLAW_GATEWAY_PORT: "19001" }, async () => {
+      const result = await resolveGatewayConnection({});
+
+      expect(result.url).toBe("ws://127.0.0.1:19001");
+      expect(readActiveGatewayLockPortMock).not.toHaveBeenCalled();
+    });
+  });
   it("uses config auth token for local mode when both config and env tokens are set", async () => {
     loadConfig.mockReturnValue({ gateway: { mode: "local", auth: { token: "config-token" } } });
 
diff --git a/src/tui/gateway-chat.ts b/src/tui/gateway-chat.ts
@@ -28,6 +28,7 @@ import { startGatewayClientWhenEventLoopReady } from "../gateway/client-start-re
 import { GatewayClient, GatewayClientRequestError } from "../gateway/client.js";
 import { isLoopbackHost } from "../gateway/net.js";
 import { formatErrorMessage } from "../infra/errors.js";
+import { readActiveGatewayLockPort } from "../infra/gateway-lock.js";
 import { sleep } from "../utils/sleep.js";
 import { VERSION } from "../version.js";
 import { TUI_SETUP_AUTH_SOURCE_CONFIG, TUI_SETUP_AUTH_SOURCE_ENV } from "./setup-launch-env.js";
@@ -347,9 +348,19 @@ export async function resolveGatewayConnection(
     explicitAuth,
     errorHint: "Fix: pass --token or --password when using --url.",
   });
+  const hasExplicitGatewayTarget = Boolean(
+    urlOverride ||
+    env.OPENCLAW_GATEWAY_URL?.trim() ||
+    env.OPENCLAW_GATEWAY_PORT?.trim() ||
+    isRemoteMode,
+  );
+  const activeLocalGatewayPort = hasExplicitGatewayTarget
+    ? undefined
+    : await readActiveGatewayLockPort();
   const url = buildGatewayConnectionDetails({
     config,
     ...(urlOverride ? { url: urlOverride } : {}),
+    ...(activeLocalGatewayPort ? { localPortOverride: activeLocalGatewayPort } : {}),
   }).url;
   const allowInsecureLocalOperatorUi = (() => {
     if (config.gateway?.controlUi?.allowInsecureAuth !== true) {
