Summary

Expose a first-class way to start an OpenClaw-managed browser profile in headed mode at runtime, matching the existing internal /start?headless=false route behavior.

Suggested public surfaces:

• openclaw browser start --headed, or --headless=false
• browser tool action="start" with headless: false or headed: true

Problem

For browser automation workflows, a practical human-handoff pattern is:

1. Run the dedicated OpenClaw browser profile headless for normal unattended work.
2. If the agent gets stuck, hits auth/2FA/CAPTCHA, or needs human judgment, stop the managed browser process.
3. Restart the same profile in headed mode so the human can take over the visible browser window.
4. After the human completes the step, reattach to the same profile/session and continue.

Today, the internals are close to supporting this, but the public CLI/tool surface is incomplete.

Current observations from installed OpenClaw 2026.4.29:

• POST /start parses a headless query override and calls profileCtx.ensureBrowserAvailable({ headless }).
• resolveManagedBrowserHeadlessMode() gives the request-level headlessOverride priority over config-derived headless mode.
• stopRunningBrowser() stops the managed Chrome process without restarting the Gateway.
• openclaw browser start exposes --headless, but not --headed or --headless=false.
• The browser tool schema likewise does not appear to expose a headless: false start override.

This means users can force headless from the CLI, but cannot cleanly force headed at runtime without editing openclaw.json / browser.headless or using the lower-level HTTP route manually.

Editing openclaw.json is not a good handoff mechanism because it can require Gateway reload/restart and affects broader browser configuration rather than just the immediate managed-browser launch.

Expected behavior

Users should be able to perform a human handoff without mutating config:

openclaw browser stop --browser-profile openclaw
openclaw browser start --browser-profile openclaw --headed

Equivalent tool-level flow should also be possible:

{ "action": "stop", "profile": "openclaw" }
{ "action": "start", "profile": "openclaw", "headless": false }

The same dedicated profile should be reused so cookies/localStorage/auth state survive the handoff.

Important behavior note

headless / headed is a Chrome process launch property. If an existing managed Chrome process is already reachable, ensureBrowserAvailable() can return the existing process without relaunching it. So switching from headless to headed requires stopping the managed browser process first, then starting it again with headless=false.

This is fine, but the public UX should make it clear. Possible options:

• document stop -> start --headed as the intended handoff sequence
• optionally add a --restart / --replace flag later, but that is not required for the minimal fix

Non-goals

• Do not require editing openclaw.json.
• Do not require restarting the Gateway.
• Do not attempt to mutate headless/headed mode on a running Chrome process.
• Do not apply this override to incompatible modes such as remote CDP / attach-only / existing-session if those are intentionally rejected today.

Related work

• #37125 / PR #69228: per-profile headless config override. Useful, but config-level rather than runtime handoff.
• PR #45207: added openclaw browser start --headless and request-level headless override. This issue asks for the symmetric headed runtime override to be exposed.
• #64464 / #64317: headed environment/display issues. Related operationally, but not the same feature gap.

Implementation sketch

Small-scope change:

1. Add --headed to openclaw browser start.
2. Pass query: { headless: false } to /start when --headed is set.
3. Reject --headless --headed together with a clear CLI error.
4. Add the same boolean surface to the browser tool start action, if applicable.
5. Add tests for:
   • --headless sends headless=true
   • --headed sends headless=false
   • no flag sends no override
   • conflicting flags fail clearly

User impact

This enables unattended browser automation that can fall back to a human-visible browser window for login/2FA/CAPTCHA/manual judgment, while keeping the Gateway alive and preserving the dedicated profile state.