Fix: Terminal Spinner Blocks WebSocket Handshake, Causing Gateway Closed (1000) Error

Problem

CLI commands like openclaw browser status consistently fail with:

Error: gateway closed (1000 normal closure): no close reason

Adding --json resolves the issue immediately:

openclaw browser status        # fails
openclaw browser status --json # succeeds

This confirms the failure is caused by the terminal spinner (enabled by default in non-JSON mode), not the gateway itself.

Root Cause

Client side

callGatewayFromCli in gateway-rpc-DDuWmIVq.js wraps the gateway call in withProgress, which activates a @clack/prompts spinner in non-JSON mode:

const showProgress = extra?.progress ?? opts.json !== true;
return await withProgress({
    label: `Gateway ${method}`,
    indeterminate: true,
    enabled: showProgress
}, async () => await callGateway({...}));

The spinner writes to stdout at frequent intervals. This blocks the Node.js event loop, delaying processing of the WebSocket connect.challenge event during the handshake sequence.

Server side

The gateway enforces a 3-second handshake timeout (DEFAULT_HANDSHAKE_TIMEOUT_MS = 3000). If the full handshake (Challenge → Connect → HelloOk) is not completed within this window, the server closes the connection:

// gateway-cli-Ol-vpIk7.js line 23225
const handshakeTimer = setTimeout(() => {
    if (!client) {
        setCloseCause("handshake-timeout", ...);
        close(); // code 1000, no reason string
    }
}, handshakeTimeoutMs);

The spinner-induced event loop delay causes the handshake to exceed 3 seconds, triggering this timeout — producing the misleading 1000 normal closure: no close reason error.

Workaround

Option 1: Use --json flag (Immediate)

openclaw browser status --json
openclaw gateway probe --json

Disables the spinner, handshake completes without event loop interference.

Option 2: Pipe output to suppress spinner

openclaw browser status | cat

Piping to cat may suppress TTY detection and disable the spinner depending on implementation.

Fix

Fix 1 — Client: Defer spinner start until after WebSocket handshake (Recommended)

Move withProgress to wrap only the post-handshake portion of the call, not the handshake itself:

// Before
return await withProgress({ ... }, async () => await callGateway({...}));

// After
const result = await callGateway({...}); // handshake completes first, no spinner
return await withProgress({ ... }, async () => result); // spinner only for processing

Or disable the spinner entirely during the WebSocket connect phase:

const gateway = await connectGateway(); // no spinner here
return await withProgress({ enabled: showProgress }, async () => {
    return await gateway.call(method, params);
});

Fix 2 — Client: Replace blocking spinner with non-blocking alternative

@clack/prompts spinner uses synchronous stdout writes that can block the event loop. Replace with a non-blocking timer-based approach:

function nonBlockingSpinner(label: string) {
  const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏']
  let i = 0
  // setImmediate yields to I/O between frames, preventing event loop blockage
  const tick = () => {
    process.stdout.write(`\r${frames[i++ % frames.length]} ${label}`)
    handle = setImmediate(tick)
  }
  let handle = setImmediate(tick)
  return { stop: () => { clearImmediate(handle); process.stdout.write('\r\x1b[K') } }
}

Fix 3 — Server: Increase handshake timeout and improve error clarity

Raise DEFAULT_HANDSHAKE_TIMEOUT_MS to provide a more generous window for slow TTY environments, and use a specific close code so the error is actionable:

// Before
const DEFAULT_HANDSHAKE_TIMEOUT_MS = 3000;
close(); // code 1000, no reason

// After
const DEFAULT_HANDSHAKE_TIMEOUT_MS = 8000; // more generous for spinner-heavy CLIs
close(1008, "handshake timeout: challenge not completed within allowed window");

This also makes the error immediately distinguishable from a genuine normal closure.

Fix 4 — Config: Allow spinner to be disabled globally

Add a config option to disable the spinner without requiring --json on every command:

{
  "cli": {
    "spinner": false
  }
}

const showProgress = extra?.progress
  ?? (opts.json !== true && config.cli?.spinner !== false);

Recommended Fix Order

Verification

After applying fixes:

# Should succeed without --json
openclaw browser status
openclaw gateway probe

# Gateway log should no longer show handshake-timeout cause
openclaw gateway logs --tail 20 | grep handshake

Environment

Upstream Fix Required

1. Decouple spinner lifecycle from WebSocket handshake — spinner must not be active during the Challenge → Connect → HelloOk sequence
2. Increase DEFAULT_HANDSHAKE_TIMEOUT_MS from 3000ms to at least 8000ms
3. Use close(1008, "handshake timeout") instead of close() — makes the error message actionable instead of misleading
4. Add cli.spinner config flag — allows users to globally opt out of spinner without --json