openclaw-browser-chain-debug

---
name: openclaw-browser-chain-debug
description: "Diagnose OpenClaw browser control failures including browser start timeouts, Chrome CDP startup failures, missing DISPLAY, browser profile launch issues, and gateway/browser environment mismatches. Use when browser automation, browser-based cron jobs, or profile openclaw fails to start, times out, or returns Request was aborted after browser steps. Also use when deciding whether a task should run with a profile browser versus an attach browser: prefer profile for unattended automation and recurring jobs; prefer attach when a human's already-open logged-in tab or manual cooperation is required."
---

# OpenClaw Browser Chain Debug

Use this skill to debug the OpenClaw browser control chain systematically before changing config.

## First decision: profile browser vs attach browser

Choose the browser mode before debugging deeper, because many "timeout" issues are really mode mismatches.

### Use **profile browser** when

Use `profile=openclaw` or another profile browser for:
- unattended automation
- cron jobs
- recurring checks
- stable repeatable flows
- flows that should not depend on the user's currently open tab
- cases where OpenClaw should own the browser lifecycle

Default automation choice:
- `profile=openclaw` for bot-owned automation

Why:
- isolated session
- reproducible state
- safer for long-running automation
- easier to reason about failures

### Use **attach / user browser** when

Use attach-style control (`profile=user` or current user browser attach flow) for:
- taking over a page the human already opened
- using existing cookies/logins in the user's live browser
- cases where the human may need to click, scan, approve, or solve CAPTCHA
- login recovery and manual collaboration flows
- debugging a page that only works in the current visible user session

Why:
- reuses existing logged-in state
- supports human-in-the-loop actions
- avoids rebuilding fragile login state in automation profiles

### Common mistake

Do **not** force `profile=openclaw` for flows that really require:
- the human's already-logged-in tab
- manual scan/approval
- extension relay / attach behavior

Do **not** force attach/user-tab control for:
- cron jobs
- unattended background refresh tasks
- large recurring inspection loops

## Quick workflow

1. Confirm the symptom.
2. Check whether the chosen browser mode is correct.
3. Check browser runtime state.
4. Check gateway/service environment.
5. Read the exact browser error from logs.
6. Classify the failure.
7. Apply the smallest fix that matches the failure mode.
8. Re-test with the minimal browser start/status path.

## Step 1: Confirm the symptom

Gather the exact failure text first. Common triggers:
- `browser start(profile=openclaw)` timed out
- `Failed to start Chrome CDP`
- `Missing X server or $DISPLAY`
- browser-dependent cron ended as `Request was aborted`
- `running:false` / `cdpReady:false`
- user asked for browser takeover but the automation was incorrectly routed through a profile browser

Do not guess from the top-level timeout alone.

## Step 2: Check browser runtime state

Run these first:

```bash
openclaw gateway status
openclaw status
```

Then use the browser tool or equivalent checks to inspect:
- profile name
- `running`
- `cdpReady`
- `headless`
- `noSandbox`
- detected Chrome path
- CDP port

Interpretation:
- `gateway running` + `browser running:false` usually means browser/profile launch failure, not full gateway outage.
- `running:true` + `cdpReady:false` usually means Chrome launched badly or CDP never became reachable.
- attach/user flows failing while profile flows work often means user-side browser attach/approval was never completed.

## Step 3: Check service environment

Inspect the environment seen by the gateway/service, not just your interactive shell.

Key variables:
- `DISPLAY`
- `XDG_SESSION_TYPE`
- `WAYLAND_DISPLAY`
- optionally `XAUTHORITY`

Also check whether the host actually has a display server:

```bash
printf 'DISPLAY=%s\nXDG_SESSION_TYPE=%s\nWAYLAND_DISPLAY=%s\n' "$DISPLAY" "$XDG_SESSION_TYPE" "$WAYLAND_DISPLAY"
ps -ef | grep -E '[X]org|[X]wayland|[X]vfb'
```

Important pattern:
- If Xorg exists on the host but the gateway environment has empty `DISPLAY`, the issue is usually **service/session environment mismatch**, not “no GUI exists anywhere”.

## Step 4: Read logs before fixing

Search the OpenClaw log for browser-specific evidence:

```bash
grep -nE 'browser|CDP|DISPLAY|X server|18800|timeout' /tmp/openclaw/openclaw-$(date +%F).log | tail -n 120
```

Prioritize the deepest concrete error over generic timeout wrappers.

## Step 5: Classify the failure

### A. Missing display / GUI mismatch

Signals:
- `Missing X server or $DISPLAY`
- `headless:false`
- service env has empty `DISPLAY`
- host may still have Xorg running

Root cause:
- OpenClaw is trying to launch headed Chrome from a service that is not attached to a desktop session.

Preferred fix:
- Prefer **headless** mode for cron/profile automation.

Alternative fix:
- If headed mode is required, wire the gateway service into the desktop session environment (`DISPLAY`, `XAUTHORITY`, etc.). This is more fragile.

### B. Sandbox/container launch problem

Signals:
- Chrome mentions sandbox failure
- running in container/root-like environment
- error suggests trying `browser.noSandbox: true`

Fix:
- Only if the environment truly requires it, enable `browser.noSandbox: true` after checking config schema first.

### C. Gateway alive, browser lane stuck

Signals:
- gateway RPC probe OK
- browser tool repeatedly times out
- logs show lane congestion, repeated browser failures, or cascading cron timeouts

Fix direction:
- reduce browser concurrency
- stagger browser-heavy cron jobs
- add explicit degraded-mode alerts instead of letting the whole cron hang

### D. Wrong browser mode selected

Signals:
- a cron/unattended flow was pointed at attach/user browser
- a human-cooperative flow was pointed at `profile=openclaw`
- login/captcha/approval depended on user presence but automation expected fully unattended success

Fix:
- move unattended jobs to profile browser
- move human-in-the-loop / existing-tab tasks to attach or `profile=user`
- update the prompt/skill so the mode choice is explicit up front

## Step 6: Repair policy

Use the smallest repair that matches the evidence.

Recommended order:
1. Confirm the browser mode is correct: profile vs attach.
2. Prefer headless browser for unattended automation.
3. Only wire DISPLAY/XAUTHORITY if a visible browser is truly needed.
4. Only change `noSandbox` when sandbox/root/container evidence points there.
5. After browser is stable, harden browser-dependent cron jobs with degraded mode and explicit alerts.

## Step 7: Re-test minimally

After any fix, re-test in this order:
1. gateway status
2. browser status
3. browser start/status for `openclaw` or the intended mode
4. one minimal browser-dependent task
5. only then re-run the full cron/job

Do not jump straight to the largest cron as the first verification step.

## Browser-dependent cron hardening

If a cron depends on browser:
- use profile browser by default, not attach/user-tab control
- persist partial state before browser work
- send explicit `browser down` alerts when browser is unavailable
- avoid long per-platform fan-out before a final summary
- degrade to latest-known state when safe, but mark it stale
- avoid one browser failure making the whole job silent

## Local lesson from this host

On this host, one confirmed root cause was:
- Xorg existed on the machine
- but the OpenClaw systemd service had empty `DISPLAY` / `XDG_SESSION_TYPE` / `WAYLAND_DISPLAY`
- and the `openclaw` profile was non-headless
- which caused Chrome CDP startup failure and browser timeouts

For the exact checklist and interpretation, read `references/checklist.md`.