feat(browser): support per-profile headless

Co-authored-by: nakamotoliu <nakamotoliu2026@gmail.com>
Co-authored-by: Nakamoto <nakamoto@claude.ai>

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-52af51e35e05d0cbaa1a79fb415f2c2fe56ad5d52a62efa9cbb9c32489d517f5  config-baseline.json
-642b4e2c9891e710790313df097b4e0db75a197ec0908e9c03bdc76f5bbdf9b0  config-baseline.core.json
+8f23e853ccde6cd021b84b32fe205f456f8516667683d16c9b56d6598f608989  config-baseline.json
+037bf4a873587adb8349f531c0ad79cd4f90e01712f5aa5d8b4387be73538a7f  config-baseline.core.json
 22d7cd6d8279146b2d79c9531a55b80b52a2c99c81338c508104729154fdd02d  config-baseline.channel.json
-d47a574045a47356e513ab308d7dcad9fa0b389f50e93c5cf0f820fab858e70e  config-baseline.plugin.json
+86f615b7d267b03888af0af7ccb3f8232a6b636f8a741d522ff425e46729ba81  config-baseline.plugin.json

docs/tools/browser.md

@@ -137,7 +137,7 @@ Browser settings live in `~/.openclaw/openclaw.json`.
     executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
     profiles: {
       openclaw: { cdpPort: 18800, color: "#FF4500" },
-      work: { cdpPort: 18801, color: "#0066CC" },
+      work: { cdpPort: 18801, color: "#0066CC", headless: true },
       user: {
         driver: "existing-session",
         attachOnly: true,
@@ -177,6 +177,7 @@ Browser settings live in `~/.openclaw/openclaw.json`.
 <Accordion title="Profile behavior">
 
 - `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.
 - `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.
 - Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
@@ -235,6 +236,7 @@ Or set it in config, per platform:
 - **Remote control (node host):** run a node host on the machine that has the browser; the Gateway proxies browser actions to it.
 - **Remote CDP:** set `browser.profiles.<name>.cdpUrl` (or `browser.cdpUrl`) to
   attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.
+- `headless` only affects local managed profiles that OpenClaw launches. It does not restart or change existing-session or remote CDP browsers.
 
 Stopping behavior differs by profile mode: