#15304: feat(browser): add browser-use no-relay profile driver
docs
cli
stale
size: M
Cluster:
Browser Enhancements and Fixes
## Summary
Add an optional `browser-use` browser profile driver to support direct CDP attachment without Chrome extension relay/tab attach.
This introduces a no-relay backend path while keeping current defaults unchanged.
## What changed
- Add `browser-use` as a supported profile driver in browser config/types/schema.
- Route runtime behavior by driver:
- `browser-use` skips managed browser launch.
- `browser-use` skips extension relay startup.
- Validates direct CDP reachability and emits driver-specific guidance.
- `stop`/`reset-profile` are non-destructive for external browser sessions.
- Wire profile creation support in API + CLI for `driver=browser-use`.
- Require explicit `cdpUrl` when creating `browser-use` profiles.
- Keep existing `chrome` relay path as default behavior.
## Docs
- Update browser tool docs for direct CDP mode setup + security notes.
- Update browser CLI docs with `browser-use` profile examples.
## Tests
Executed locally:
```bash
corepack pnpm exec vitest run \
src/browser/config.test.ts \
src/browser/profiles-service.test.ts \
src/browser/server-context.browser-use-driver.test.ts
```
Result: 21 passed / 0 failed
Executed locally:
```bash
corepack pnpm exec oxlint --type-aware \
src/browser/client.ts \
src/browser/config.ts \
src/browser/profiles-service.ts \
src/browser/routes/basic.ts \
src/browser/server-context.ts \
src/cli/browser-cli-manage.ts \
src/config/types.browser.ts \
src/config/zod-schema.ts \
src/browser/config.test.ts \
src/browser/profiles-service.test.ts \
src/browser/server-context.browser-use-driver.test.ts
```
Result: 0 warnings / 0 errors
## Backward compatibility
- Default browser flow remains unchanged (`chrome` relay path).
- New behavior only applies when profile driver is explicitly set to `browser-use`.
## Follow-ups (optional)
- Expose profile `driver` in status/list output for visibility.
- Add localized docs parity for browser-use examples.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR adds a new `browser-use` browser profile driver that attaches directly to an existing CDP endpoint (no managed Chrome launch and no extension relay). It updates the config types/schema/docs and routes runtime behavior in `src/browser/server-context.ts` so `browser-use` profiles only perform reachability checks, while `stop`/`reset-profile` are non-destructive for externally-managed sessions. Profile creation paths are wired through the API/CLI and tests cover the new driver resolution and runtime branching.
Main issue spotted: `BrowserProfileConfig.driver` was widened to include `"clawd"` in `src/config/types.browser.ts`, but runtime/config resolution still only meaningfully handles `openclaw|extension|browser-use` (and treats anything else as `openclaw`). That makes the public type/schema misleading and can mask misconfiguration unless it’s either removed or fully supported end-to-end.
<h3>Confidence Score: 4/5</h3>
- This PR is close to safe to merge, with one config-type/schema inconsistency to address.
- Runtime branching for the new `browser-use` driver is straightforward and covered by targeted tests, but the config type was widened to include `"clawd"` without corresponding routing semantics, which can mislead users and silently change behavior on misconfiguration.
- src/config/types.browser.ts (and any related config typing/export points)
<sub>Last reviewed commit: ebc98c9</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#20207: fix(browser): use profile driver instead of hardcoded name
by mahsumaktas · 2026-02-18
83.6%
#22952: fix(browser): suggest remote profile when local Chrome is not insta...
by dashed · 2026-02-21
78.0%
#23363: Browser: fallback to managed profile and improve runtime diagnostics
by isdoho · 2026-02-22
77.7%
#14944: fix(browser): prefer openclaw profile in headless/noSandbox environ...
by BenediktSchackenberg · 2026-02-12
77.6%
#6193: fix(browser): default to openclaw profile instead of chrome extensi...
by mikezaoldyeck · 2026-02-01
76.6%
#9020: fix(browser): skip port ownership and WS reachability checks for re...
by yepack · 2026-02-04
76.4%
#15595: fix(browser): avoid local port conflicts for remote cdp
by TsekaLuk · 2026-02-13
75.1%
#23189: feat(browser): add custom userDataDir support for Chrome profiles
by delta8z · 2026-02-22
74.4%
#19966: feat: add language support for browser profiles
by cyfrit · 2026-02-18
74.3%
#9728: fix(gateway): browser.snapshot ignores profile parameter (#9723)
by divol89 · 2026-02-05
74.3%