Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Bug]: Gateway WebSocket handshake timeout on local loopback (non-systemd env) breaks all CLI RPC commands [5 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#52766•Fetched 2026-04-08 01:19:45
View on GitHub
Comments
5
Participants
2
Timeline
23
Reactions
0
Author
mossaemossae
Participants
ArtyomkunArtyomkunmossaemossae
Timeline (top)
mentioned ×6subscribed ×6commented ×5cross-referenced ×2

In a non-systemd environment (e.g. container/VPS without systemd user services), the OpenClaw gateway accepts TCP connections on the loopback interface but consistently times out during the WebSocket auth handshake, making it impossible to use any CLI command that requires gateway RPC (e.g. cron add, cron list).

Error Message

4. Wait ~30 seconds -> error: Error: gateway timeout after 30000ms [WARN] handshake timeout conn=af65e95f remote=127.0.0.1 [WARN] { cause: 'handshake-timeout', handshake: 'failed', durationMs: 33013, handshakeMs: 3002 } connection attempt hit the handshake timeout without exception.

Root Cause

In a non-systemd environment (e.g. container/VPS without systemd user services), the OpenClaw gateway accepts TCP connections on the loopback interface but consistently times out during the WebSocket auth handshake, making it impossible to use any CLI command that requires gateway RPC (e.g. cron add, cron list).

Fix Action

Fix / Workaround

Severity: Blocks workflow - cron/reminder functionality is completely unusable. There is no working workaround.

Consequence: Scheduled reminders and cron jobs cannot be created via the CLI. Direct file writes to jobs.json as a workaround are silently ignored by the scheduler (see related issue). Users lose all timer/reminder functionality on affected setups.

RAW_BUFFERClick to expand / collapse

Bug type

Behavior bug (incorrect output/state without crash)

Summary

In a non-systemd environment (e.g. container/VPS without systemd user services), the OpenClaw gateway accepts TCP connections on the loopback interface but consistently times out during the WebSocket auth handshake, making it impossible to use any CLI command that requires gateway RPC (e.g. cron add, cron list).

Steps to reproduce

1. Start the gateway (openclaw gateway in foreground - systemd unavailable) 2. Confirm it's listening: ss -tlnp | grep 18796 -> shows LISTEN 3. Run openclaw cron add --name test --at "2026-03-18T02:30:00Z" --announce --message "test" 4. Wait ~30 seconds -> error:

Expected behavior

1. openclaw cron add should succeed on a running local gateway 2. Cron scheduler should pick up job file changes without requiring a full restart

Actual behavior

Error: gateway timeout after 30000ms Gateway target: ws://127.0.0.1:18796 Source: local loopback

Gateway Log Evidence

The gateway accepts the connection and sends a challenge, but drops it after 3s:

[WARN] handshake timeout conn=af65e95f remote=127.0.0.1 [WARN] { cause: 'handshake-timeout', handshake: 'failed', durationMs: 33013, handshakeMs: 3002 }

OpenClaw version

version- 2026.3.13

Operating system

Linux 6.8.0 (x64), no systemd user services

Install method

curl -fsSL https://openclaw.ai/install.sh | bash

Model

anthropic/claude-sonnet-4-6

Provider / routing chain

openclaw -> gateway (local loopback, ws://127.0.0.1:18796) -> [handshake timeout, never reaches agent]

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Impact and severity

Affected users/systems/channels: Any user running OpenClaw in a non-systemd environment (containers, VPS without systemd user services). Affects all CLI commands that require gateway RPC - specifically cron add, cron list, and related commands over the local loopback interface.

Severity: Blocks workflow - cron/reminder functionality is completely unusable. There is no working workaround.

Frequency: Always - reproduced consistently across multiple attempts over multiple days (2026-03-17 and 2026-03-23). Every single CLI→gateway connection attempt hit the handshake timeout without exception.

Consequence: Scheduled reminders and cron jobs cannot be created via the CLI. Direct file writes to jobs.json as a workaround are silently ignored by the scheduler (see related issue). Users lose all timer/reminder functionality on affected setups.

Additional information

1. The websocket upgrade itself works:

The WebSocket upgrade succeeds — confirmed via curl: curl -i -H "Upgrade: websocket" -H "Connection: Upgrade"
-H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ=="
-H "Sec-WebSocket-Version: 13"
http://127.0.0.1:18796/

Response: HTTP 101 Switching Protocols Gateway sends connect.challenge with nonce But CLI never completes the handshake - times out after 3s

This suggests the issue is in the challenge/response auth exchange specifically, not in network connectivity or port binding.

2. The gateway auth token is correctly configured:

Auth mode is set to "token" in config and gateway.auth.token is populated. The token is not missing — the handshake still fails regardless.

extent analysis

Fix Plan

To resolve the handshake timeout issue, we need to adjust the WebSocket connection timeout and authentication settings in the OpenClaw gateway configuration.

  • Increase the WebSocket connection timeout to allow more time for the handshake to complete:
# In openclaw gateway configuration file (e.g., config.py)
websocket_timeout = 60000  # Increase timeout to 60 seconds
  • Verify that the authentication token is correctly configured and populated:
# In openclaw gateway configuration file (e.g., config.py)
auth_mode = "token"
gateway_auth_token = "your_token_value"  # Ensure the token is populated
  • Update the challenge/response auth exchange to handle the handshake timeout:
# In openclaw gateway WebSocket handler (e.g., websocket_handler.py)
import asyncio

async def handle_handshake(websocket):
    try:
        # Send challenge and wait for response
        await websocket.send_json({"challenge": "your_challenge_value"})
        response = await asyncio.wait_for(websocket.recv_json(), timeout=60)  # Increase timeout to 60 seconds
        # Verify response and complete handshake
        if response["response"] == "your_expected_response":
            await websocket.send_json({"success": True})
        else:
            await websocket.send_json({"error": "Invalid response"})
    except asyncio.TimeoutError:
        # Handle handshake timeout
        await websocket.send_json({"error": "Handshake timeout"})

Verification

To verify that the fix worked, restart the OpenClaw gateway and attempt to run the openclaw cron add command again. The command should now succeed without timing out.

Extra Tips

  • Ensure that the OpenClaw gateway configuration file is correctly updated and reloaded after making changes.
  • If issues persist, try increasing the WebSocket connection timeout further or adjusting other authentication settings.
  • Consider implementing additional logging or debugging to help diagnose any future issues with the handshake process.

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…

FAQ

Expected behavior

1. openclaw cron add should succeed on a running local gateway 2. Cron scheduler should pick up job file changes without requiring a full restart

#device allocation#model download#tokenizer error#prompt formatting#chain error

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 - 💡(How to fix) Fix [Bug]: Gateway WebSocket handshake timeout on local loopback (non-systemd env) breaks all CLI RPC commands [5 comments, 2 participants]