From 77c15ffcd620e89147f66e6437f1b433a0fccdb5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 25 Apr 2026 10:44:26 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@8cbb62d93c1db9a07cff3bb6fbdec481f72122b5 --- .openclaw-sync/source.json | 4 ++-- docs/cli/browser.md | 5 +++++ docs/tools/browser-control.md | 6 +++++- docs/tools/browser-linux-troubleshooting.md | 3 ++- docs/tools/browser.md | 12 +++++++++--- 5 files changed, 23 insertions(+), 7 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index b49b6f0c9..72a68e889 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "1549ded4ac0597f5f1faca06b8324244ede4cbec", - "syncedAt": "2026-04-25T10:41:37.983Z" + "sha": "8cbb62d93c1db9a07cff3bb6fbdec481f72122b5", + "syncedAt": "2026-04-25T10:43:04.887Z" } diff --git a/docs/cli/browser.md b/docs/cli/browser.md index d0af50937..962d8c7fc 100644 --- a/docs/cli/browser.md +++ b/docs/cli/browser.md @@ -56,6 +56,7 @@ Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure- openclaw browser status openclaw browser doctor openclaw browser start +openclaw browser start --headless openclaw browser stop openclaw browser --browser-profile openclaw reset-profile ``` @@ -67,6 +68,10 @@ Notes: OpenClaw did not launch the browser process itself. - For local managed profiles, `openclaw browser stop` stops the spawned browser process. +- `openclaw browser start --headless` applies only to that start request and + only when OpenClaw launches a local managed browser. It does not rewrite + `browser.headless` or profile config, and it is a no-op for an already-running + browser. - 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` diff --git a/docs/tools/browser-control.md b/docs/tools/browser-control.md index 78abfee9d..f88d8504c 100644 --- a/docs/tools/browser-control.md +++ b/docs/tools/browser-control.md @@ -28,7 +28,10 @@ For local integrations only, the Gateway exposes a small loopback HTTP API: - State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` - Settings: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` -All endpoints accept `?profile=`. +All endpoints accept `?profile=`. `POST /start?headless=true` requests a +one-shot headless launch for local managed profiles without changing persisted +browser config; attach-only, remote CDP, and existing-session profiles reject +that override because OpenClaw does not launch those browser processes. If shared-secret gateway auth is configured, browser HTTP routes require auth too: @@ -122,6 +125,7 @@ All commands accept `--browser-profile ` to target a specific profile, and ```bash openclaw browser status openclaw browser start +openclaw browser start --headless # one-shot local managed headless launch openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser tabs openclaw browser tab # shortcut for current tab diff --git a/docs/tools/browser-linux-troubleshooting.md b/docs/tools/browser-linux-troubleshooting.md index dd00cc624..0f909c740 100644 --- a/docs/tools/browser-linux-troubleshooting.md +++ b/docs/tools/browser-linux-troubleshooting.md @@ -37,7 +37,8 @@ Other common Linux launch failures: `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. + run `openclaw browser start --headless` for a one-shot managed launch, or run + OpenClaw in a real desktop session. ### Solution 1: Install Google Chrome (Recommended) diff --git a/docs/tools/browser.md b/docs/tools/browser.md index 720b582ab..02e80c58e 100644 --- a/docs/tools/browser.md +++ b/docs/tools/browser.md @@ -194,14 +194,20 @@ 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. +- `POST /start?headless=true` and `openclaw browser start --headless` request a + one-shot headless launch for local managed profiles without rewriting + `browser.headless` or profile config. Existing-session, attach-only, and + remote CDP profiles reject the override because OpenClaw does not launch those + browser processes. - 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`. + `request`, `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. + current process. `OPENCLAW_BROWSER_HEADLESS=0` forces headed mode for ordinary + starts and returns an actionable error on Linux hosts without a display server; + an explicit `start --headless` request still wins for that one launch. - `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.