Clawdbot User Guide, Install & Troubleshooting FAQs

Clawdbot Gateway (Troubleshooting + Fixes)

The Clawdbot gateway is the always-on bridge between your agent runtime and the outside world (channels, tools, browser control, and the Console). If the gateway is down — or if you have two gateways — everything looks flaky: 502s, “websocket disconnected”, or messages that never execute.

Symptoms

Console shows gateway disconnected / offline
Chat messages send, but no tools run / no replies
Repeated “websocket disconnected” loops
Duplicate replies (often two gateways responding)
502 after restart (proxy points to a port that changed or is held by a ghost process)

Fastest next click

Clawdbot websocket disconnected →

Checks (ports, tokens, process)

Your goal is to answer: is the gateway running, and is it the only one?

Process owner: confirm it’s running as the intended service user (avoid root vs master split-brain).
Ports: confirm the expected ports are listening and owned by the expected PID.
Tokens/config: confirm the Console is pointing to the correct gateway and token.

# List listeners
ss -lntp

# List relevant processes
ps aux | egrep 'claw|gateway|openclaw|clawdbot|node' | head

Image placeholder

(Insert: screenshot of gateway status + ss output showing the port listener PID/user.)

Common failure modes

Port collision / ghost process: old gateway process still holds the port after restart.
Token mismatch: Console is configured with a different token than the running gateway expects.
Split-brain install: gateway started under root sometimes and under a service user other times, creating two config/state stores.
Crash loop: gateway is restarting repeatedly due to a config or dependency error.

Fixes (restart pattern + port cleanup)

Use a single canonical restart path (systemd). Avoid starting ad-hoc gateway processes by hand, which often creates split-brain.

1) Restart the gateway cleanly

systemctl restart clawdbot-gateway
# or: clawdbot gateway restart (depending on your install)

2) Confirm ports after restart

ss -lntp
# Confirm only one gateway is listening on the expected port(s).

3) If you see duplicate processes, fix the brain

Duplicate gateways are the classic cause of duplicate replies and intermittent disconnects.

Prevention

One-Brain standard: one service user, one HOME, one DATA_DIR, one set of ports.
Document ports and stop relying on “whatever was open.”
Monitor reconnect loops and restart storms as early indicators.

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