chore(sync): mirror docs from openclaw/openclaw@8cbb62d93c

.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"
 }

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.<name>.headless=false`

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=<name>`.
+All endpoints accept `?profile=<name>`. `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 <name>` 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

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.<name>.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)
 

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.