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

Clawdbot Debugging (Remote Debugging + CDP)

This page covers Clawdbot debugging for browser automation issues using Chrome DevTools Protocol (CDP). If you’re seeing “CDP failed to start,” “cannot connect to browser,” or you need to inspect what headless Chrome is doing, start here.

Quick diagnostics (what to check first)

  1. Is Chrome running? Confirm the process exists.
  2. Is the remote debugging port listening? Confirm the port is bound.
  3. Does /json/version respond? This proves CDP is reachable.
  4. Are you connecting to the right host? Prefer 127.0.0.1 on the same box; avoid mismatched 0.0.0.0 URLs.
  5. Is the profile locked? A stale Chrome instance can hold the profile directory.
If you’re new
Start from the basics, then come back:

CDP endpoints you should know

If your remote debugging port is 18800:

  • Version: http://127.0.0.1:18800/json/version
  • Targets: http://127.0.0.1:18800/json/list
curl -s http://127.0.0.1:18800/json/version
curl -s http://127.0.0.1:18800/json/list
Image placeholder
(Insert: screenshot of /json/version output highlighting webSocketDebuggerUrl.)

How Clawdbot uses remote debugging (CDP)

Clawdbot (and many automation stacks) talk to Chrome via CDP. The flow is:

  1. Start Chrome with --remote-debugging-port.
  2. Query /json/version to discover the webSocketDebuggerUrl.
  3. Connect via WebSocket to drive the browser.

If step 2 fails, you don’t have a Clawdbot problem — you have a Chrome/port/network problem.

Common issues (ports, ws URLs, locks)

1) Port collisions

If another process already holds the remote debugging port, Chrome may fail to start or your automation connects to the wrong instance.

ss -lntp | grep -E '18800|9222'
# If the listener PID/user is not what you expect, that’s the bug.

2) Wrong bind address (0.0.0.0 vs 127.0.0.1)

Chrome often reports a WS URL using 0.0.0.0. Many clients should still connect via 127.0.0.1 (same host). If you’re connecting remotely, you must explicitly bind and firewall it safely.

3) Profile locks / Singleton errors

If you reuse a persistent --user-data-dir, only one Chrome can own it at a time. A crash can leave lock files, or a stray Chrome process can keep it open.

Symptom: Chrome won’t start, or starts with a new temporary profile (breaking persistent sessions).

4) Snap/Chromium packaging weirdness

On some servers, snap Chromium introduces sandbox/permission issues. Many operators prefer the Chrome deb install for stability.

Fixes

  • Standardize your CDP port (pick one, document it, don’t overlap).
  • Use a persistent profile directory if you need persistent sessions.
  • Keep it local: connect from the same host to 127.0.0.1 unless you truly need remote access.
  • One-Brain rule: ensure Chrome + gateway + console run under the same service user and same HOME.

If your debugging issue is part of a larger stability problem, read: One Brain, One Console.

Prevention

  • Run Chrome with explicit flags: remote-debugging address/port + user-data-dir.
  • Track ports in one place (runbook) to avoid collisions.
  • Keep durable state in DATA_DIR and keep service HOME consistent.

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