openclaw - 💡(How to fix) Fix openclaw gateway restart hangs on macOS with SMB-mounted volumes (lsof stat() timeout) [1 comments, 2 participants]

Description

Environment

• OS: macOS 15.x (Darwin 25.4.0, arm64)
• Node: v25.8.2
• OpenClaw: 2026.4.26 (be8c246)
• Network mounts: Synology DS224plus via SMB, used for Time Machine backup
  • Mount path: /Volumes/.timemachine/DS224plus._smb._tcp.local./.../Mac_backup

Symptoms

Running openclaw gateway restart or openclaw gateway --force causes the process to hang for extended periods (30s to minutes). During the hang, the following warning repeats many times:

lsof: WARNING: can't stat() smbfs file system /Volumes/.timemachine/DS224plus._smb._tcp.local./XXXX/Mac_backup
      Output information may be incomplete.
      assuming "dev=3600007c" from mount table

Eventually it either times out or fails with:

Force: Error: lsof permission denied while inspecting gateway port: ...

Root Cause Analysis

OpenClaw's port-checking logic uses lsof in 4 separate call sites across 3 files:

The command used is: lsof -nP -iTCP:{port} -sTCP:LISTEN -FpFc[n]

On macOS, lsof traverses all mounted filesystems to build its file descriptor table, even when the -i flag limits results to a single network port. When an SMB/NFS mount is unresponsive (e.g., NAS is busy with Time Machine backup, network congestion, disk sleep wake-up), lsof blocks for the SMB timeout (10-30s+) on each stat() call.

This affects every CLI operation that needs to inspect port 18789, causing the Gateway restart sequence to feel like it takes "10+ minutes" as it goes through multiple retry/timeout cycles.

Attempted workaround: -b flag

The lsof -b flag (which skips blocking kernel calls like stat(), readlink()) was tested but does not resolve the issue — macOS lsof still traverses SMB mounts at the VFS layer regardless of -b.

Proposed fix

Replace lsof-based port checking with a pure Node.js approach:

// Instead of calling lsof, probe directly:
const net = require('net');
const server = net.createServer();
server.listen(port, '127.0.0.1', () => {
  server.close(); // port is free
});
server.on('error', (err) => {
  if (err.code === 'EADDRINUSE') /* port is busy */;
});

This would be immune to filesystem mount issues and also faster than spawning lsof.

Alternatively, at minimum, the readUnixListeners async code path already has a ss (socket statistics) fallback — extending this to the sync paths or making the sync paths async could help.