Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Gateway accepts connections before ready signal, causing handshake timeouts on startup [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#73652•Fetched 2026-04-29 06:16:57
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
0
Author
spenceryang1996-dotspenceryang1996-dot
Participants
clawsweeper[bot]clawsweeper[bot]spenceryang1996-dotspenceryang1996-dot
Timeline (top)
commented ×1cross-referenced ×1

Fix Action

Fixed

PR fix notes

PR #51282: feat(gateway): make handshake timeout configurable via gateway.handshakeTimeoutMs

Description (problem / solution / changelog)

Summary

Add gateway.handshakeTimeoutMs config option so users can tune the WebSocket handshake timeout from their config file, without patching dist files or relying solely on env vars.

Changes

  • src/config/types.gateway.ts: Add handshakeTimeoutMs?: number to GatewayConfig
  • src/gateway/server-constants.ts: Read config value in getHandshakeTimeoutMs() with priority: env var > config file > default (10s)
  • src/config/schema.help.ts: Add help text for the new field

Priority Order

  1. OPENCLAW_HANDSHAKE_TIMEOUT_MS env var (existing, unchanged)
  2. gateway.handshakeTimeoutMs in config file (new)
  3. Default: 10,000 ms

Context

#49262 bumped the default from 3s to 10s, but #51274 reports that loaded gateways (600MB+, 80+ tasks) still need higher values. The reporter currently patches dist files via a systemd drop-in. This PR lets them set it in config instead:

gateway:
  handshakeTimeoutMs: 15000

Closes #51274

Changed files

  • src/config/schema.help.ts (modified, +2/-0)
  • src/config/types.gateway.ts (modified, +7/-0)
  • src/gateway/server-constants.ts (modified, +13/-0)
RAW_BUFFERClick to expand / collapse

Problem

Gateway listens on TCP port and accepts WebSocket connections before it is internally ready, causing all clients that connect during the ~15-22s startup window to experience handshake timeouts.

Steps to Reproduce

  1. Start OpenClaw Gateway (or trigger a config reload / restart)
  2. Immediately open control UI or connect a client
  3. Connection times out after ~15-22 seconds

Expected Behavior

Gateway should either:

  • Not accept connections until fully ready, OR
  • Send an explicit "not ready" signal so clients can retry

Observed Behavior

  • Gateway prints "gateway ready" to log at the end of initialization
  • TCP port is already listening and accepting connections before that message
  • Clients attempt handshake during this window and timeout

Log Evidence

Example from v2026.4.26 (be8c246):

``` 23:33:04.525 Chrome client initiates connection (port 61326) 23:33:04.526 handshake timeout: 14799ms ← client already trying 23:33:04.708 "gateway ready" ← only now is gateway truly ready ```

Multiple clients (Chrome browser, possibly openclaw-tui) hit this on every restart. The gap between port opening and "gateway ready" is ~15-22 seconds.

Version

  • OpenClaw: 2026.4.26 (be8c246)
  • Node: v25.8.0
  • Platform: Darwin (Mac mini, arm64)
  • Gateway: loopback on port 18789

Configuration

Gateway bind: loopback only (127.0.0.1) No firewall changes needed; this is local loopback connectivity issue.

This appears to be a startup sequencing bug where the HTTP/WebSocket server starts accepting connections before internal initialization is complete.

extent analysis

TL;DR

Delay accepting WebSocket connections until the gateway is fully initialized to prevent handshake timeouts.

Guidance

  • Investigate the gateway's initialization sequence to identify why the TCP port is listening before the "gateway ready" message is printed.
  • Consider adding a flag or signal to indicate when the gateway is ready to accept connections, and only start listening on the TCP port after this flag is set.
  • Review the log evidence to understand the timing of the handshake timeout and the "gateway ready" message to determine the optimal delay for accepting connections.
  • Evaluate the possibility of sending an explicit "not ready" signal to clients that connect during the startup window, allowing them to retry the connection.

Example

// Pseudocode example of delaying TCP port listening
const gatewayReady = false;

// Initialization sequence...
// ...

// Set gatewayReady flag when initialization is complete
gatewayReady = true;
console.log("gateway ready");

// Only start listening on TCP port when gateway is ready
if (gatewayReady) {
  // Start TCP server and accept connections
}

Notes

The exact implementation details may vary depending on the gateway's internal architecture and the Node.js version being used. This guidance provides a general direction for resolving the issue.

Recommendation

Apply a workaround by delaying the acceptance of WebSocket connections until the gateway is fully initialized, as this approach is more feasible given the provided information.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#request error#file not found#serialization error#model compatibility#GPU setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix Gateway accepts connections before ready signal, causing handshake timeouts on startup [1 pull requests, 1 comments, 2 participants]