Clawd Console
Your command deck
Clawdbot User Guide, Install & Troubleshooting FAQs

Clawdbot Websocket Disconnected

“Clawdbot websocket disconnected” can mean two different connections are failing. The fix depends on which websocket is dropping: client ↔ console (your browser tab to the Console) or console ↔ gateway (the Console backend to the Clawdbot gateway).

Quick triage

  1. If the page itself 502s, start with gateway/ports/reverse proxy.
  2. If the UI loads but live updates stop, check client ↔ console websocket.
  3. If chat sends but nothing executes, check console ↔ gateway connectivity.
  4. If restarts “fix it” temporarily, suspect port collisions or split-brain.
Most common root cause
Two brains competing for ports/state (root vs master, duplicate services). Start here:

What websocket is disconnecting?

Use this mental model:

  • Client ↔ Console: your browser tab maintains a WS connection to the Console for live updates.
  • Console ↔ Gateway: the Console maintains a WS (or equivalent persistent link) to the gateway to send/receive events.
Image placeholder
(Insert: diagram showing client↔console and console↔gateway links + ports.)

Common causes

  • Gateway down (service stopped/crash loop) → Console can’t maintain backend connectivity.
  • Port collision (old process holds the port) → restarts don’t restart what you think.
  • Reverse proxy config missing websocket upgrade headers/timeouts → client WS drops.
  • Split-brain (root vs master installs) → mismatched tokens/config; inconsistent behavior.
  • Network idle timeouts (cloud LB/WAF) → long-lived WS dropped after X minutes.

Fixes

1) Confirm gateway health

Start here if console↔gateway is failing:

2) Eliminate port collisions

ss -lntp
# Look for unexpected listeners, duplicate PIDs, or ports owned by the wrong user.

3) If client↔console WS drops, check the proxy

If you’re behind nginx, the websocket path needs proper upgrade headers and timeouts. A misconfig looks like: UI loads, but “live” dies or reconnects forever.

4) Fix split-brain (the real cure for “random disconnects”)

If you have two installs/users starting services, you’ll see nondeterministic disconnects and “works after restart” behavior.

Prevention

  • One-Brain standard: one service user, one HOME, one DATA_DIR, one set of ports.
  • Document ports and restart only via systemd (avoid ad-hoc node runs).
  • Proxy hygiene: set websocket upgrade headers + sane read timeouts.
  • Monitor reconnect loops — they’re usually an early warning of split-brain or port collisions.

Related pages

Get Early Access!

Launching any day…

Hosted Clawdbot + ClawdConsole workspaces are coming very, very soon.

Join the waitlist and we’ll spin up your workspace the moment access opens.

  • Same operator cockpit you’re seeing here
  • Private hosted workspace
  • We’ll email you your link when it’s ready
Back to FAQ hub: User Guide, Install & Troubleshooting FAQs