Summary

Managed browser tooling should return a structured, actionable result when a profile is configured for headed launch but the current environment has no display server.

Problem to solve

In headless or service contexts, a browser profile may be configured with headless=false, but $DISPLAY / $WAYLAND_DISPLAY is unavailable. The browser tool can then fail before opening a page, even when the calling workflow only needs automation/headless access.

The current failure is understandable to an expert, but it is not ideal for automation:

• it is a hard stop rather than a structured degraded state;
• it does not distinguish “profile misconfigured for this runtime” from “browser unavailable”;
• it can block workflows that could safely run headless.

Proposed solution

Proposed shape

One of:

• auto-fallback to headless for automation-managed profiles when no display server exists and the profile policy allows fallback; or
• return a structured error with machine-readable reason such as no_display_for_headed_profile, plus remediation fields.

Recommended response fields:

{
  "ok": false,
  "reason": "no_display_for_headed_profile",
  "profile": "openclaw",
  "requestedHeadless": false,
  "displayPresent": false,
  "remediation": "Set profile headless=true, set OPENCLAW_BROWSER_HEADLESS=1, or run under a display/Xvfb."
}

Acceptance criteria

• Browser launch failure distinguishes missing display from other launch failures.
• The returned error is structured enough for agents/tools to branch on it.
• Optional headless fallback is controlled by profile policy/config, not silently applied everywhere.
• Documentation explains headed vs headless behavior for service contexts.

Alternatives considered

No response

Impact

This improves reliability for scheduled or server-side browser workflows and avoids unnecessary user intervention when a headless fallback would be safe.

Evidence/examples

No response

Additional information

No response