OpenClaw Browser WSL Attach

Automatically prepare, repair, and attach an OpenClaw-controlled Chromium browser in WSL or Linux environments where OpenClaw runs as root or in a headless s...

Security Scan

The skill's files and runtime instructions are consistent with its stated purpose (preparing and attaching a Chromium instance for OpenClaw in WSL/headless/root environments); it modifies the user's OpenClaw config and starts a local Chromium process but does not request external credentials or download remote code.

Purpose & Capability

Name/description, SKILL.md, and the three scripts all align: they edit ~/.openclaw/openclaw.json, create a backup, start a Chromium instance with remote debugging on a local port, and perform local health checks. Nothing in the bundle requires unrelated credentials, network endpoints, or tools.

Instruction Scope

The runtime instructions explicitly tell the agent/operator to run the included scripts which will modify ~/.openclaw/openclaw.json (a timestamped backup is created), kill/launch Chromium, and probe a local CDP endpoint. The healthcheck prints some environment variables (HOME, DISPLAY, XDG_RUNTIME_DIR) and process listings. This behavior is within scope for configuring browser attach behavior but is intrusive to the user's OpenClaw config and will start/kill local processes — the user should expect and permit those changes.

Install Mechanism

No install spec or remote downloads are present; all code is included in the skill bundle. Nothing will be fetched from arbitrary URLs or written from external sources during install.

Credentials

The skill declares no required env vars or credentials. The scripts optionally read a few environment variables (OPENCLAW_BROWSER_CDP_PORT, OPENCLAW_BROWSER_BIN, OPENCLAW_BROWSER_USER_DATA_DIR, OPENCLAW_BROWSER_LOG) and standard ones like HOME — these are reasonable for configuring local paths and ports and are proportional to the task.

Persistence & Privilege

The skill will modify the user's OpenClaw config file (writes ~/.openclaw/openclaw.json and a timestamped .bak) and can start/kill Chromium processes. It does not request always:true or system-wide privileged configuration beyond the user's files, but it does instruct using --no-sandbox when running as root which reduces Chromium's runtime isolation (a necessary but security-reducing choice).

Assessment

This skill appears to do what it says: it will update your ~/.openclaw/openclaw.json (it creates a timestamped backup), start/kill a local Chromium process with remote debugging on localhost:18800, and print local environment and process information. Before running: review the included scripts yourself, confirm you are comfortable with the config change and the backup, and ensure port 18800 is not exposed to untrusted networks. Be aware that the script runs Chromium with --no-sandbox when used as root (this reduces browser isolation and is a tradeoff for running as root); if possible prefer running as a non-root user or inspect the user-data-dir used by the script. There are no external downloads or credential exfiltration patterns present, but run these tools manually the first time so you can review outputs and logs (/tmp/openclaw-browser.log and the created backup).

Prepare a stable OpenClaw browser session by using Chromium in attachOnly mode with remote debugging enabled. Prefer this workflow in WSL, headless Linux, or root-run OpenClaw environments where direct browser launch is flaky.

Workflow

1. Check browser readiness before changing anything.
2. If OpenClaw browser is already attached and healthy, reuse it.
3. If Chromium exists but OpenClaw launch is unstable, switch to attachOnly mode.
4. Run python3 scripts/configure-browser.py and restart the gateway.
5. Start Chromium manually with CDP on port 18800.
6. Verify curl http://127.0.0.1:18800/json/version and openclaw browser status.
7. Then use normal browser actions through OpenClaw.

Quick checks

Run these checks first:

openclaw browser status
command -v chromium || command -v chromium-browser || command -v google-chrome
curl -s http://127.0.0.1:18800/json/version

Interpretation:

• If openclaw browser status shows running: true, the browser is ready.
• If CDP JSON returns but OpenClaw still fails to launch browser itself, prefer attachOnly.
• If Chromium is missing, install or point browser.executablePath to a valid Chromium-based browser.

Preferred configuration

Use this browser config in ~/.openclaw/openclaw.json for WSL/root/headless Linux:

"browser": {
  "enabled": true,
  "executablePath": "/usr/bin/chromium",
  "headless": true,
  "noSandbox": true,
  "attachOnly": true
}

Notes:

• Use noSandbox: true when Chromium runs as root.
• Use attachOnly: true when OpenClaw-managed launch times out or is unreliable.
• browser: unknown and detectedBrowser: custom are acceptable if running: true and CDP works.

Start Chromium manually

Use the bundled scripts in this order:

python3 scripts/configure-browser.py
# restart gateway after config changes
bash scripts/start-browser.sh
bash scripts/healthcheck.sh

What each script does:

• configure-browser.py: updates ~/.openclaw/openclaw.json for WSL/root/headless attachOnly mode and writes a timestamped backup
• start-browser.sh: creates the OpenClaw browser profile directory, kills stale Chromium on port 18800 when needed, starts headless Chromium, and prints verification output
• healthcheck.sh: shows binary, status, CDP, process, and environment diagnostics

Verify success

Healthy state usually looks like:

• curl http://127.0.0.1:18800/json/version returns JSON
• openclaw browser status shows running: true
• openclaw browser tabs works

Once healthy, continue with OpenClaw browser tooling normally.

Repair workflow

If browser control breaks later:

1. Re-run openclaw browser status
2. Re-run bash scripts/start-browser.sh
3. Run bash scripts/healthcheck.sh
4. If needed, inspect /tmp/openclaw-browser.log
5. Confirm port 18800 is not blocked by another process
6. Restart gateway only after config changes

User-facing guidance

After setup, the user can simply ask for browser tasks in natural language, for example:

• open a URL
• search a phrase
• log into a site
• click a button
• extract page content
• take a screenshot

Read references/troubleshooting.md when browser attach still fails after the standard workflow.

Prefer this skill whenever the task is about making OpenClaw browser automation reliable on this machine, not just using the browser tool once.