openclaw/docs/tools/browser/existing-session.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Named browser profiles and attaching to a running Chrome session through Chrome DevTools MCP"
title: "Multi-profile and existing-session attach"
read_when:
  - You want the agent to use your signed-in browser session
  - You are creating extra named browser profiles
  - You need the Chrome MCP launch overrides or the existing-session limits
---

## Profiles (multi-browser)

OpenClaw supports multiple named profiles (routing configs). Profiles can be:

- **openclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port
- **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)
- **existing session**: your existing Chrome profile via Chrome DevTools MCP auto-connect

Defaults:

- The `openclaw` profile is auto-created if missing.
- The `user` profile is built-in for Chrome MCP existing-session attach.
- Existing-session profiles are opt-in beyond `user`; 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.

All control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.

## Existing session via Chrome DevTools MCP

OpenClaw can also attach to a running Chromium-based browser profile through the
official Chrome DevTools MCP server. This reuses the tabs and login state
already open in that browser profile.

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)

Built-in profile: `user`. Create your own custom existing-session profile if
you want a different name or browser data directory.

By default the built-in `user` profile uses Chrome MCP auto-connect, which
targets the default local Google Chrome profile. Use `userDataDir` for Brave,
Edge, Chromium, or a non-default Chrome profile. `~` expands to your OS home
directory:

```json5
{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
      },
    },
  },
}
```

Then in the matching browser:

1. Open that browser's inspect page for remote debugging.
2. Enable remote debugging.
3. Keep the browser running and approve the connection prompt when OpenClaw attaches.

Common inspect pages:

- Chrome: `chrome://inspect/#remote-debugging`
- Brave: `brave://inspect/#remote-debugging`
- Edge: `edge://inspect/#remote-debugging`

Live attach smoke test:

```bash
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:

- `status` shows `driver: existing-session`
- `status` shows `transport: chrome-mcp`
- `status` shows `running: true`
- `tabs` lists your already-open browser tabs
- `snapshot` returns refs from the selected live tab

What to check if attach does not work:

- the target Chromium-based browser is version `144+`
- remote debugging is enabled in that browser's inspect page
- the browser showed and you accepted the attach consent prompt
- if Chrome was started with an explicit `--remote-debugging-port`, set
  `browser.profiles.<name>.cdpUrl` to that DevTools endpoint instead of relying
  on Chrome MCP auto-connect
- `openclaw doctor` migrates old extension-based browser config and checks that
  Chrome is installed locally for default auto-connect profiles, but it cannot
  enable browser-side remote debugging for you

For startup failures, check the `browser/chrome-mcp` logs for a bounded, redacted
tail of subprocess stderr when available.

Agent use:

- 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.
- Only choose this mode when the user is at the computer to approve the attach
  prompt.
- The Gateway or node host starts the packaged Chrome DevTools MCP server on its own runtime, Node or Bun.

Notes:

- This path is higher-risk than the isolated `openclaw` profile because it can
  act inside your signed-in browser session.
- OpenClaw does not launch the browser for this driver; it only attaches.
- Stopping or failing an attach closes the owned MCP subprocess and its verified
  descendants, not the already-running browser. Replacement attaches wait for
  cleanup; if cleanup cannot be verified, OpenClaw reports an error instead of
  treating the session as closed.
- OpenClaw uses the official Chrome DevTools MCP `--autoConnect` flow here. If
  `userDataDir` is set, it is passed through to target that user data directory.
- Existing-session can attach on the selected host or through a connected
  browser node. If Chrome lives elsewhere and no browser node is connected, use
  remote CDP or a node host instead.
- Chrome MCP targets and snapshot refs are scoped to one MCP subprocess. After
  that process restarts, run `browser tabs` again, explicitly select a fresh
  target before target-specific work, and take a new snapshot before using refs.
  Each ref is valid only for its target and latest snapshot. Old aliases are not
  transferred to a replacement tab, even when its URL matches.
- Starting a snapshot refresh invalidates that tab's earlier refs, even if the
  refresh fails. Condition waits reuse the current document snapshot and preserve
  its refs. A stale-document error retires only that tab's snapshot; a later poll
  captures the replacement document. Take a fresh snapshot after navigation before
  performing another ref-based action.
- Labeled screenshots can include controls in multiple frames. Successful
  captures remove their temporary labels from each frame before returning.
- Chrome DevTools MCP currently routes page tools by a process-local numeric page
  ID. Process-scoped handles prevent reuse across subprocess replacement, but an
  in-process browser-context replacement between adjacent tool calls can still
  retarget an action. Fully atomic routing requires upstream page-tool support
  for stable target IDs.

### Custom Chrome MCP launch

OpenClaw includes an exact-pinned Chrome DevTools MCP 1.10.1 dependency with a
temporary document-identity patch and starts its CLI directly with the runtime
running OpenClaw, Node or Bun.
The npm package carries the patched dependency; source checkouts obtain it through
`pnpm install`. This keeps the server used at runtime aligned with OpenClaw's
browser contract tests. The patch is tracked in
[the upstream repair](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/2788).

Override the server per profile for a custom executable or version. Custom servers
are operator-managed and must preserve Chrome MCP's connection arguments and
document-bound element identity.

| Field        | What it does                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `mcpCommand` | Custom server executable. Absolute paths are honored; omitted or explicit `npx` selects OpenClaw's packaged server.             |
| `mcpArgs`    | Extra arguments passed unchanged to `mcpCommand`. Connection options override the generated endpoint or auto-connect arguments. |

`mcpArgs` extends the selected server's arguments. Existing configurations that set
`mcpCommand: "npx"` continue to select the built-in pinned server.
The default launcher enables `--experimentalVision` for native coordinate clicks.
A custom `mcpCommand` must expose the `click_at` tool to support `click-coords`;
pass the server's corresponding feature flag in `mcpArgs` when required.

When `mcpArgs` does not set a connection option, OpenClaw forwards a configured
`cdpUrl` to Chrome MCP instead of generating `--autoConnect`:

- `http(s)://...` → `--browserUrl <url>` (DevTools HTTP discovery endpoint).
- `ws(s)://...` → `--wsEndpoint <url>` (direct CDP WebSocket).

Explicit endpoint arguments in `mcpArgs` override `cdpUrl`; adding
`--autoConnect` alongside an endpoint does not hide it. OpenClaw uses the selected
endpoint for CDP control and checks Browser CDP policy before starting Chrome MCP.
A matching `blockedHostnames` entry denies attachment even when private-network
access is trusted. Unrelated blocklist entries do not prevent attachment, and
the default strict-policy restrictions still apply.

Invalid, empty, duplicate, or conflicting endpoint arguments fail with an error
before launch. Supply one valid endpoint, or omit `cdpUrl` and endpoint arguments
to use host-local attachment.

When an endpoint is selected, `userDataDir` is ignored: Chrome MCP attaches to the
running browser behind that endpoint rather than opening a profile directory.

<Accordion title="Existing-session feature limitations">

Compared to the managed `openclaw` profile, existing-session drivers are more constrained:

- **Ambiguous iframe refs** - The packaged server scopes element IDs to their frame and document. If a custom server returns the same ID for different documents, OpenClaw discards the snapshot and invalidates its refs. Ref-free page screenshots remain available; update the custom server or use a managed browser profile for ref-based work.
- **Screenshots** - page captures and `--ref` element captures work; CSS `--element` selectors do not. Playwright is not required for page or ref-based element screenshots. (`--full-page` cannot combine with `--ref` or `--element` on any profile, not just existing-session.)
- **Actions** - `click`, `type`, `hover`, `scrollIntoView`, `drag`, and `select` require snapshot refs (no CSS selectors). `click-coords` sends native input at visible viewport coordinates without a snapshot ref, supporting left clicks and double clicks. Right/middle buttons and nonzero delays return an unsupported-operation error. `click` is left-button only (no button overrides or modifiers). `type` does not support `slowly=true`; use `fill` or `press`. `press` does not support `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, and `fill` do not support per-call `timeoutMs` overrides; `evaluate` does. `select` accepts one exact HTML option value, including empty or whitespace values; duplicate display labels do not change which value is selected. `batch` is not supported; send actions individually.
- **Wait / upload / dialog** - `wait --url` supports exact, substring, and glob patterns (same as managed); `wait --load networkidle` is not supported on existing-session profiles (it works on managed and raw/remote CDP profiles). Upload hooks require `ref` or `inputRef` and do not support CSS `element`; pass multiple paths when the page's file input accepts multiple files. Dialog hooks do not support timeout overrides or `dialogId`.
- **Dialog visibility** - Managed browser action responses include `blockedByDialog` and `browserState.dialogs.pending` when an action opens a modal dialog; snapshots also include pending dialog state. Respond with `browser dialog --accept/--dismiss --dialog-id <id>` while a dialog is pending. Dialogs handled outside OpenClaw appear under `browserState.dialogs.recent`.
- **Playwright-only features** - PDF export, download interception, `responsebody`, and the agent actions `requests`, `errors`, `text`, and `emulate` require a Playwright-backed profile, such as the managed `openclaw` profile. Use `snapshot` to inspect an existing-session page.

</Accordion>