github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-18 21:47:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(browser): prefer user profile over chrome relay

Browse Source
This commit is contained in:
Peter Steinberger
2026-03-14 04:15:25 +00:00
parent 1f9cc647f8
commit b6d1d0d72d
21 changed files with 211 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/tools/browser-linux-troubleshooting.md
View File

@@ -123,7 +123,7 @@ curl -s http://127.0.0.1:18791/tabs
### Problem: "Chrome extension relay is running, but no tab is connected"
You’re using the `chrome` profile (extension relay). It expects the OpenClaw
You’re using the `chrome-relay` profile (extension relay). It expects the OpenClaw
browser extension to be attached to a live tab.
Fix options:
@@ -135,5 +135,5 @@ Fix options:
Notes:
- The `chrome` profile uses your **system default Chromium browser** when possible.
- The `chrome-relay` profile uses your **system default Chromium browser** when possible.
- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.

4
docs/tools/browser-login.md
View File

@@ -23,8 +23,8 @@ OpenClaw controls a **dedicated Chrome profile** (named `openclaw`, orange‑tin
For agent browser tool calls:
- Default choice: the agent should use its isolated `openclaw` browser.
- Use the **user browser** only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
- If you need to force the choice, use `browserSession="agent"` or `browserSession="user"`.
- Use `profile="user"` only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
- If you have multiple user-browser profiles, specify the profile explicitly instead of guessing.
Two easy ways to access it:

6
docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md
View File

@@ -33,7 +33,7 @@ Choose this when:
### Option 2: Chrome extension relay
Use the built-in `chrome` profile plus the OpenClaw Chrome extension.
Use the built-in `chrome-relay` profile plus the OpenClaw Chrome extension.
Choose this when:
@@ -155,7 +155,7 @@ Example:
{
browser: {
enabled: true,
defaultProfile: "chrome",
defaultProfile: "chrome-relay",
relayBindHost: "0.0.0.0",
},
}
@@ -197,7 +197,7 @@ openclaw browser tabs --browser-profile remote
For the extension relay:
```bash
openclaw browser tabs --browser-profile chrome
openclaw browser tabs --browser-profile chrome-relay
```
Good result:

73
docs/tools/browser.md
View File

@@ -18,8 +18,8 @@ Beginner view:
- Think of it as a **separate, agent-only browser**.
- The `openclaw` profile does **not** touch your personal browser profile.
- The agent can **open tabs, read pages, click, and type** in a safe lane.
- The default `chrome` profile uses the **system default Chromium browser** via the
extension relay; switch to `openclaw` for the isolated managed browser.
- The built-in `user` profile attaches to your real signed-in Chrome session;
`chrome-relay` is the explicit extension-relay profile.
## What you get
@@ -43,22 +43,22 @@ openclaw browser --browser-profile openclaw snapshot
If you get “Browser disabled”, enable it in config (see below) and restart the
Gateway.
## Profiles: `openclaw` vs `chrome`
## Profiles: `openclaw` vs `user` vs `chrome-relay`
- `openclaw`: managed, isolated browser (no extension required).
- `chrome`: extension relay to your **system browser** (requires the OpenClaw
extension to be attached to a tab).
- `existing-session`: official Chrome MCP attach flow for a running Chrome
profile.
- `user`: built-in Chrome MCP attach profile for your **real signed-in Chrome**
session.
- `chrome-relay`: extension relay to your **system browser** (requires the
OpenClaw extension to be attached to a tab).
For agent browser tool calls:
- Default: use the isolated `openclaw` browser.
- Use the **user browser** only when existing logged-in sessions matter and the
user is at the computer to click/approve any attach prompt.
- If you need to force the choice, use `browserSession="agent"` or
`browserSession="user"`.
- `profile` is the explicit override when you already know which profile to use.
- Prefer `profile="user"` when existing logged-in sessions matter and the user
is at the computer to click/approve any attach prompt.
- Use `profile="chrome-relay"` only when the user explicitly wants the Chrome
extension / toolbar-button attach flow.
- `profile` is the explicit override when you want a specific browser mode.
Set `browser.defaultProfile: "openclaw"` if you want managed mode by default.
@@ -88,11 +88,16 @@ Browser settings live in `~/.openclaw/openclaw.json`.
profiles: {
openclaw: { cdpPort: 18800, color: "#FF4500" },
work: { cdpPort: 18801, color: "#0066CC" },
"chrome-live": {
user: {
driver: "existing-session",
attachOnly: true,
color: "#00AA00",
},
"chrome-relay": {
driver: "extension",
cdpUrl: "http://127.0.0.1:18792",
color: "#00AA00",
},
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
},
},
@@ -113,7 +118,7 @@ Notes:
- `browser.ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias for compatibility.
- `attachOnly: true` means “never launch a local browser; only attach if it is already running.”
- `color` + per-profile `color` tint the browser UI so you can see which profile is active.
- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "chrome"` to opt into the Chrome extension relay.
- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "user"` to opt into the signed-in user browser, or `defaultProfile: "chrome-relay"` for the extension relay.
- Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
- Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.
- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do
@@ -287,7 +292,7 @@ OpenClaw supports multiple named profiles (routing configs). Profiles can be:
Defaults:
- The `openclaw` profile is auto-created if missing.
- The `chrome` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).
- The `chrome-relay` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).
- Existing-session profiles are opt-in; create them with `--driver existing-session`.
- Local CDP ports allocate from **18800–18899** by default.
- Deleting a profile moves its local data directory to Trash.
@@ -331,8 +336,8 @@ openclaw browser extension install
2. Use it:
- CLI: `openclaw browser --browser-profile chrome tabs`
- Agent tool: `browser` with `browserSession="user"` (or `profile="chrome"`)
- CLI: `openclaw browser --browser-profile chrome-relay tabs`
- Agent tool: `browser` with `profile="chrome-relay"`
Optional: if you want a different name or relay port, create your own profile:
@@ -348,8 +353,9 @@ Notes:
- This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).
- Detach by clicking the extension icon again.
- Agent use: prefer `browserSession="user"` for logged-in sites. The user must be
present to click the extension and attach the tab.
- Agent use: prefer `profile="user"` for logged-in sites. Use `profile="chrome-relay"`
only when you specifically want the extension flow. The user must be present
to click the extension and attach the tab.
## Chrome existing-session via MCP
@@ -362,14 +368,12 @@ Official background and setup references:
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
Create a profile:
Built-in profile:
```bash
openclaw browser create-profile \
--name chrome-live \
--driver existing-session \
--color "#00AA00"
```
- `user`
Optional: create your own custom existing-session profile if you want a
different name or color.
Then in Chrome:
@@ -380,10 +384,10 @@ Then in Chrome:
Live attach smoke test:
```bash
openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```
What success looks like:
@@ -402,9 +406,10 @@ What to check if attach does not work:
Agent use:
- Use `browserSession="user"` when you need the user’s logged-in browser state.
- If you know the profile name, pass `profile="chrome-live"` (or your custom
existing-session profile).
- Use `profile="user"` when you need the user’s logged-in browser state.
- If you use a custom existing-session profile, pass that explicit profile name.
- Prefer `profile="user"` over `profile="chrome-relay"` unless the user
explicitly wants the extension / attach-tab flow.
- Only choose this mode when the user is at the computer to approve the attach
prompt.
- the Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
@@ -432,7 +437,7 @@ WSL2 / cross-namespace example:
browser: {
enabled: true,
relayBindHost: "0.0.0.0",
defaultProfile: "chrome",
defaultProfile: "chrome-relay",
},
}
```

6
docs/tools/chrome-extension.md
View File

@@ -62,7 +62,7 @@ After upgrading OpenClaw:
## Use it (set gateway token once)
OpenClaw ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.
OpenClaw ships with a built-in browser profile named `chrome-relay` that targets the extension relay on the default port.
Before first attach, open extension Options and set:
@@ -71,8 +71,8 @@ Before first attach, open extension Options and set:
Use it:
- CLI: `openclaw browser --browser-profile chrome tabs`
- Agent tool: `browser` with `profile="chrome"`
- CLI: `openclaw browser --browser-profile chrome-relay tabs`
- Agent tool: `browser` with `profile="chrome-relay"`
If you want a different name or a different relay port, create your own profile:

9
docs/tools/index.md
View File

@@ -310,17 +310,16 @@ Profile management:
Common parameters:
- `browserSession` (`agent` | `user`)
- `profile` (optional; defaults to `browser.defaultProfile`)
- `target` (`sandbox` | `host` | `node`)
- `node` (optional; picks a specific node id/name)
Notes:
- Requires `browser.enabled=true` (default is `true`; set `false` to disable).
- `browserSession="agent"` is the safe default: isolated OpenClaw-managed browser.
- `browserSession="user"` means the real local host browser. Use it only when existing logins/cookies matter and the user is present to click/approve any attach prompt.
- `browserSession="user"` is host-only; do not combine it with sandbox/node targets.
- All actions accept optional `profile` parameter for multi-instance support.
- `profile` overrides `browserSession` when both are supplied.
- Omit `profile` for the safe default: isolated OpenClaw-managed browser (`openclaw`).
- Use `profile="user"` for the real local host browser when existing logins/cookies matter and the user is present to click/approve any attach prompt.
- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
- `profile="user"` and `profile="chrome-relay"` are host-only; do not combine them with sandbox/node targets.
- When `profile` is omitted, uses `browser.defaultProfile` (defaults to `openclaw`).
- Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
- Port range: 18800-18899 (~100 profiles max).