Summary

openclaw status --all / doctor currently treats a healthy managed OpenClaw Gateway listener as a port conflict when the gateway is intentionally bound on a non-loopback/LAN address for an internal reverse-proxy deployment.

This is the same false-positive class as #53398, but #53398 only covered the dual-stack loopback case (127.0.0.1 + ::1). A valid gateway.bind=lan / wildcard bind setup can still render misleading output such as:

• Port 18789 is already in use.
• Gateway already running locally. Stop it (...) or use a different port.

That wording is wrong when the only listener on the configured port is the expected managed OpenClaw Gateway and gateway health/liveness succeeds.

Why this matters

Some deployments intentionally do not use Tailscale and instead expose OpenClaw only through a controlled internal / allowlisted reverse-proxy path. In that setup the gateway may need to bind to LAN / wildcard rather than loopback.

That configuration can be unusual, but it is valid. It may deserve separate exposure/security/audit guidance, but it should not appear as a port-conflict error.

Local evidence from a validated setup

On a Linux/systemd install using the default gateway port:

GET http://127.0.0.1:18789/healthz
=> {"ok":true,"status":"live"}

ss -H -ltnp 'sport = :18789'
=> LISTEN 0.0.0.0:18789 users:(("MainThread",pid=<pid>,fd=27))

ps -p <pid> -o command=
=> /usr/bin/node .../openclaw/dist/index.js gateway --port 18789

The port is occupied, but by the configured, healthy OpenClaw Gateway itself. This should be rendered as OK / informational, not as a conflict.

Current root cause

The installed bundle maps to these source areas:

• src/infra/ports-format.ts
• src/commands/status-all/diagnosis.ts
• src/commands/doctor-gateway-daemon-flow.ts

Current behavior:

• buildPortHints() emits the stop/use-different-port hint for any listener classified as gateway.
• status-all only treats an empty listener set or isDualStackLoopbackGatewayListeners(...) as OK.
• doctor reports busy-port diagnostics without distinguishing expected Gateway listeners from foreign/conflicting owners.

Proposed behavior

Distinguish expected OpenClaw Gateway listeners from real conflicts.

OK / info:

• no listener
• a single OpenClaw Gateway listener on the configured port using loopback (127.0.0.1, ::1, localhost)
• a single OpenClaw Gateway listener on the configured port using wildcard/LAN bind (0.0.0.0, ::, *)
• the existing dual-stack loopback same-PID case from #53398

Still warn:

• unknown process owns the port
• SSH tunnel owns the port
• multiple unrelated listeners
• multiple OpenClaw Gateway PIDs on the same port
• mixed Gateway + non-Gateway listeners

Tested local patch shape

A local dist patch with this source-level shape fixed the false positive without restart and preserved conflict behavior.

src/infra/ports-format.ts

Add shared predicates near the existing dual-stack helper:

function isWildcardAddress(host: string): boolean {
  return host === "0.0.0.0" || host === "::" || host === "*";
}

function isExpectedGatewayBindAddress(host: string): boolean {
  return Boolean(classifyLoopbackAddressFamily(host)) || isWildcardAddress(host);
}

export function isSingleExpectedGatewayListener(
  listeners: PortListener[],
  port: number,
): boolean {
  if (listeners.length !== 1) return false;

  const [listener] = listeners;
  if (classifyPortListener(listener, port) !== "gateway") return false;
  if (typeof listener.pid !== "number" || !Number.isFinite(listener.pid)) return false;
  if (typeof listener.address !== "string") return false;

  const parsed = parseListenerAddress(listener.address);
  if (!parsed || parsed.port !== port) return false;

  return isExpectedGatewayBindAddress(parsed.host);
}

export function isExpectedGatewayListeners(
  listeners: PortListener[],
  port: number,
): boolean {
  return (
    isSingleExpectedGatewayListener(listeners, port) ||
    isDualStackLoopbackGatewayListeners(listeners, port)
  );
}

Then avoid conflict hints for expected Gateway listeners:

if (kinds.has("gateway") && !isExpectedGatewayListeners(listeners, port)) {
  hints.push(`Gateway already running locally. Stop it (${formatCliCommand("openclaw gateway stop")}) or use a different port.`);
}

if (listeners.length > 1 && !isExpectedGatewayListeners(listeners, port)) {
  hints.push("Multiple listeners detected; ensure only one gateway/tunnel per port unless intentionally running isolated profiles.");
}

src/commands/status-all/diagnosis.ts

Use the shared predicate instead of the dual-stack-loopback-only check:

const expectedGatewayListeners = isExpectedGatewayListeners(params.portUsage.listeners, params.port);
const portOk = params.portUsage.listeners.length === 0 || expectedGatewayListeners;

emitCheck(`Port ${params.port}`, portOk ? "ok" : "warn");

if (!portOk) {
  for (const line of formatPortDiagnostics(params.portUsage)) lines.push(`  ${muted(line)}`);
} else if (expectedGatewayListeners && params.portUsage.listeners.length > 0) {
  lines.push(`  ${muted("Detected OpenClaw Gateway listener on the configured port.")}`);
}

src/commands/doctor-gateway-daemon-flow.ts

Suppress busy-port notes only when the listener set is expected:

const diagnostics = await inspectPortUsage(resolveGatewayPort(params.cfg, process.env));

if (
  diagnostics.status === "busy" &&
  !isExpectedGatewayListeners(diagnostics.listeners, diagnostics.port)
) {
  note(formatPortDiagnostics(diagnostics).join("\n"), "Gateway port");
}

Local verification after patch

The local patch produced:

inspectPortUsage(18789) => status: "busy", one listener address: "*:18789"
isExpectedGatewayListeners(...) => true
buildPortHints(...) => []

openclaw status --all then rendered:

✓ Port 18789
  Detected OpenClaw Gateway listener on the configured port.

No Port 18789 warning remained. Gateway health stayed live before and after the patch.

Regression tests suggested

• single OpenClaw Gateway listener on 0.0.0.0:<port> is expected and produces no stop/use-different-port hint
• single OpenClaw Gateway listener on [::]:<port> is expected and produces no stop/use-different-port hint
• existing same-PID dual-stack loopback case remains expected
• two different OpenClaw Gateway PIDs still warn
• unknown process still warns
• SSH tunnel still warns
• doctor suppresses busy-port note only for expected Gateway listeners

Related

• #53398 fixed the same false-positive class for dual-stack loopback only. This issue extends the same principle to valid LAN/wildcard reverse-proxy deployments.