From e8bf593869496cf903d287c232709fc2677ea416 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 25 Apr 2026 10:17:29 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@9b48e4c0b643a8afa51dc3adb659da757a473864 --- .openclaw-sync/source.json | 4 +-- docs/cli/browser.md | 4 +++ docs/tools/browser-linux-troubleshooting.md | 27 ++++++++++++--------- docs/tools/browser.md | 8 ++++++ 4 files changed, 30 insertions(+), 13 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 2dc836056..8f6652eb0 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "385da2db607218b176f351a596e41c3a6fff375d", - "syncedAt": "2026-04-25T10:00:48.072Z" + "sha": "9b48e4c0b643a8afa51dc3adb659da757a473864", + "syncedAt": "2026-04-25T10:16:00.573Z" } diff --git a/docs/cli/browser.md b/docs/cli/browser.md index 790d74479..d0af50937 100644 --- a/docs/cli/browser.md +++ b/docs/cli/browser.md @@ -67,6 +67,10 @@ Notes: OpenClaw did not launch the browser process itself. - For local managed profiles, `openclaw browser stop` stops the spawned browser process. +- On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles + run headless automatically unless `OPENCLAW_BROWSER_HEADLESS=0`, + `browser.headless=false`, or `browser.profiles..headless=false` + explicitly requests a visible browser. ## If the command is missing diff --git a/docs/tools/browser-linux-troubleshooting.md b/docs/tools/browser-linux-troubleshooting.md index 9362d937b..dd00cc624 100644 --- a/docs/tools/browser-linux-troubleshooting.md +++ b/docs/tools/browser-linux-troubleshooting.md @@ -31,9 +31,13 @@ Other common Linux launch failures: found stale `Singleton*` lock files in the managed profile directory. OpenClaw removes those locks and retries once when the lock points at a dead or different-host process. -- `Missing X server or $DISPLAY` means OpenClaw is trying to launch a visible - browser on a host without a desktop session. Use `browser.headless: true`, - start `Xvfb`, or run OpenClaw in a real desktop session. +- `Missing X server or $DISPLAY` means a visible browser was explicitly + requested on a host without a desktop session. By default, local managed + profiles now fall back to headless mode on Linux when `DISPLAY` and + `WAYLAND_DISPLAY` are both unset. If you set `OPENCLAW_BROWSER_HEADLESS=0`, + `browser.headless: false`, or `browser.profiles..headless: false`, + remove that headed override, set `OPENCLAW_BROWSER_HEADLESS=1`, start `Xvfb`, + or run OpenClaw in a real desktop session. ### Solution 1: Install Google Chrome (Recommended) @@ -120,14 +124,15 @@ curl -s http://127.0.0.1:18791/tabs ### Config Reference -| Option | Description | Default | -| ------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------- | -| `browser.enabled` | Enable browser control | `true` | -| `browser.executablePath` | Path to a Chromium-based browser binary (Chrome/Brave/Edge/Chromium) | auto-detected (prefers default browser when Chromium-based) | -| `browser.headless` | Run without GUI | `false` | -| `browser.noSandbox` | Add `--no-sandbox` flag (needed for some Linux setups) | `false` | -| `browser.attachOnly` | Don't launch browser, only attach to existing | `false` | -| `browser.cdpPort` | Chrome DevTools Protocol port | `18800` | +| Option | Description | Default | +| --------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- | +| `browser.enabled` | Enable browser control | `true` | +| `browser.executablePath` | Path to a Chromium-based browser binary (Chrome/Brave/Edge/Chromium) | auto-detected (prefers default browser when Chromium-based) | +| `browser.headless` | Run without GUI | `false` | +| `OPENCLAW_BROWSER_HEADLESS` | Per-process override for local managed browser headless mode | unset | +| `browser.noSandbox` | Add `--no-sandbox` flag (needed for some Linux setups) | `false` | +| `browser.attachOnly` | Don't launch browser, only attach to existing | `false` | +| `browser.cdpPort` | Chrome DevTools Protocol port | `18800` | ### Problem: "No Chrome tabs found for profile=\"user\"" diff --git a/docs/tools/browser.md b/docs/tools/browser.md index 0c3ceb011..720b582ab 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -194,6 +194,14 @@ Browser settings live in `~/.openclaw/openclaw.json`. - `attachOnly: true` means never launch a local browser; only attach if one is already running. - `headless` can be set globally or per local managed profile. Per-profile values override `browser.headless`, so one locally launched profile can stay headless while another remains visible. +- On Linux hosts without `DISPLAY` or `WAYLAND_DISPLAY`, local managed profiles + default to headless automatically when neither the environment nor profile/global + config explicitly chooses headed mode. `openclaw browser status --json` + reports `headlessSource` as `env`, `profile`, `config`, + `linux-display-fallback`, or `default`. +- `OPENCLAW_BROWSER_HEADLESS=1` forces local managed launches headless for the + current process. `OPENCLAW_BROWSER_HEADLESS=0` forces headed mode and returns + an actionable error on Linux hosts without a display server. - `executablePath` can be set globally or per local managed profile. Per-profile values override `browser.executablePath`, so different managed profiles can launch different Chromium-based browsers. - `color` (top-level and per-profile) tints the browser UI so you can see which profile is active. - Default profile is `openclaw` (managed standalone). Use `defaultProfile: "user"` to opt into the signed-in user browser.