Clawdbot User Guide, Install & Troubleshooting FAQs

Clawdbot Headless Chrome (CDP) Troubleshooting

If your agent can’t start browser automation, can’t connect to CDP, or keeps losing logins, this is the page for Clawdbot headless Chrome troubleshooting. The fastest path is: verify CDP (/json/version), eliminate port collisions, and standardize a persistent profile (--user-data-dir).

Symptoms

“CDP failed to start” / “cannot connect to browser”
Automation works once, then fails after reboot
Chrome starts but /json/version times out
Persistent sessions don’t stick (keeps logging you out)
Random 502/websocket instability after restarts (often port collisions / split-brain)

If your issues are caused by split state (root vs master), read:

Two Brains Are Not Better Than One →

Checks (ports, /json/version, profile locks)

Confirm a listener exists on your CDP port (example: 18800).
Hit /json/version to confirm CDP is reachable.
Confirm only one Chrome owns the profile directory.

# Listener check
ss -lntp | grep -E '18800|9222'

# CDP check
curl -s http://127.0.0.1:18800/json/version

# Targets list (optional)
curl -s http://127.0.0.1:18800/json/list

Image placeholder

(Insert: screenshot showing ss listener + /json/version returning webSocketDebuggerUrl.)

Fixes (known-good setup)

Operators usually converge on a stable pattern:

Prefer Chrome deb install over snap Chromium for server reliability (fewer sandbox surprises).
Use a persistent profile directory to keep logins (persistent session).
Standardize CDP port (pick one, document it, don’t overlap).

Example command (headless + CDP + persistent session)

google-chrome \
  --headless=new \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=18800 \
  --user-data-dir=/home/master/clawd/apps/console-data/chrome-profile

Then verify:

curl -s http://127.0.0.1:18800/json/version

Common causes (and what to do)

1) Port conflicts

Another process holding the CDP port will break automation or connect you to the wrong Chrome.

2) Profile locks / singleton issues

A persistent profile directory can only be used by one Chrome at a time. Crashes can leave a stale process or lock files.

3) Snap Chromium instability

Some environments see snap-related sandbox/permission failures. If you keep hitting weirdness, switch to Chrome deb.

4) Wrong user / split-brain (root vs non-root)

If Chrome runs as root sometimes and as a service user other times, you’ll get different HOME/profile paths and inconsistent persistence.

Prevention

Run Chrome under the same service user every time.
Keep one canonical HOME + DATA_DIR (One-Brain standard).
Document ports; don’t ad-hoc launch “just for a test.”

If you need the full reliability runbook, read: One Brain, One Console.

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