#22952: fix(browser): suggest remote profile when local Chrome is not installed
agents
size: S
Cluster:
Browser Enhancements and Fixes
## Summary
When deployed in a containerized gateway (no local Chrome), the agent's browser tool fails with "No supported browser found" if the LLM explicitly passes `profile: "openclaw"`. This happens because:
1. `config.ts` auto-creates an "openclaw" loopback profile (`127.0.0.1`) on every instance
2. The `profile` parameter in the tool schema had no description, so the LLM infers "openclaw" as the natural profile name
3. The loopback profile tries to launch a local Chrome that doesn't exist
Meanwhile, omitting the profile parameter works fine — it falls through to the configured `defaultProfile` (e.g., a remote CDP endpoint).
### Changes
- **`browser-tool.schema.ts`**: Add description to `profile` parameter guiding LLMs to omit it (use default)
- **`server-context.ts`**: Pre-launch check — if no Chrome executable and there's a remote default profile, throw a helpful error suggesting the remote profile
- **`chrome.ts`**: Export `resolveBrowserExecutable()` for reuse; improve error message to list available remote profiles
### New test
- `server-context.loopback-fallback-to-remote.test.ts`: Verifies the fallback suggestion and the pass-through when no remote default exists
## Test plan
- [x] All 49 existing browser tests pass (6 test files)
- [x] New test covers both fallback and no-fallback scenarios
- [ ] Manual verification: `POST /start` with no profile → works; `POST /start?profile=openclaw` → helpful error suggesting remote profile
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR improves the browser tool's behavior in containerized environments where local Chrome is not installed. When an LLM explicitly requests a loopback profile (like "openclaw") but no local browser exists and a remote CDP endpoint is available, the error message now suggests using the remote profile instead of failing with a generic "No supported browser found" error.
The changes include:
- Added description to `profile` parameter in browser tool schema to guide LLMs to omit it and use the default
- Pre-launch check in `ensureBrowserAvailable()` that detects missing browser executables and suggests remote default profile
- Enhanced error message in `launchOpenClawChrome()` listing available remote profiles
- Exported `resolveBrowserExecutable()` for reuse across modules
- New test coverage for the fallback suggestion logic
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The changes are well-contained, properly tested, and improve error messaging without altering core logic. The new validation check prevents failures earlier in the process with clearer guidance, and all existing tests should continue to pass.
- No files require special attention
<sub>Last reviewed commit: 4aeb4a7</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#14944: fix(browser): prefer openclaw profile in headless/noSandbox environ...
by BenediktSchackenberg · 2026-02-12
82.9%
#13568: Fix browser (OpenClaw-managed) launch fail by binding remote debugg...
by singlag · 2026-02-10
82.2%
#20207: fix(browser): use profile driver instead of hardcoded name
by mahsumaktas · 2026-02-18
80.5%
#6193: fix(browser): default to openclaw profile instead of chrome extensi...
by mikezaoldyeck · 2026-02-01
80.5%
#15595: fix(browser): avoid local port conflicts for remote cdp
by TsekaLuk · 2026-02-13
80.2%
#23363: Browser: fallback to managed profile and improve runtime diagnostics
by isdoho · 2026-02-22
78.9%
#9020: fix(browser): skip port ownership and WS reachability checks for re...
by yepack · 2026-02-04
78.8%
#15304: feat(browser): add browser-use no-relay profile driver
by rajanrengasamy · 2026-02-13
78.0%
#16030: fix(browser): extend single-tab fallback to remote CDP profiles
by lailoo · 2026-02-14
78.0%
#9728: fix(gateway): browser.snapshot ignores profile parameter (#9723)
by divol89 · 2026-02-05
77.3%