<!-- source: https://deepwiki.com/openclaw/openclaw/3.4.4-browser-automation -->

# Browser Automation

- docs/tools/browser.md
- extensions/browser/src/browser/cdp-proxy-bypass.test.ts
- extensions/browser/src/browser/cdp-proxy-bypass.ts
- extensions/browser/src/browser/cdp.helpers.fuzz.test.ts
- extensions/browser/src/browser/chrome-mcp.test.ts
- extensions/browser/src/browser/chrome-mcp.ts
- extensions/browser/src/browser/chrome.internal.test.ts
- extensions/browser/src/browser/chrome.test.ts
- extensions/browser/src/browser/chrome.ts
- extensions/browser/src/browser/client-fetch.loopback-auth.test.ts
- extensions/browser/src/browser/client-fetch.ts
- extensions/browser/src/browser/profiles.test.ts
- extensions/browser/src/browser/profiles.ts
- extensions/discord/src/monitor/typing.test.ts
- extensions/microsoft-foundry/auth.ts
- extensions/microsoft-foundry/cli.ts
- extensions/microsoft-foundry/index.test.ts
- extensions/microsoft-foundry/provider.ts
- extensions/microsoft-foundry/runtime.ts
- extensions/microsoft-foundry/shared.ts
- extensions/telegram/src/polling-liveness.test.ts
- extensions/telegram/src/polling-liveness.ts
- extensions/telegram/src/polling-session.test.ts
- extensions/telegram/src/polling-session.ts
- extensions/telegram/src/polling-status.ts
- extensions/telegram/src/request-timeouts.test.ts
- extensions/telegram/src/request-timeouts.ts
- extensions/telegram/src/sequential-key.test.ts
- extensions/telegram/src/sequential-key.ts
- extensions/telegram/src/status-issues.ts
- extensions/telegram/src/status.test.ts
- extensions/telegram/src/telegram-ingress-spool.test.ts
- extensions/telegram/src/telegram-ingress-spool.ts
- extensions/telegram/src/telegram-ingress-worker.runtime.ts
- extensions/telegram/src/telegram-ingress-worker.ts
- extensions/telegram/src/telegram-reply-fence.test.ts
- extensions/telegram/src/telegram-reply-fence.ts
- extensions/tlon/src/security.test.ts
- src/config/bundled-channel-config-runtime.test.ts
- src/config/config-misc.test.ts
- src/config/gateway-control-ui-origins.test.ts
- src/config/io.clobber-snapshot.test.ts
- src/config/io.clobber-snapshot.ts
- src/config/io.eacces.test.ts
- src/config/io.observe-recovery.test.ts
- src/config/io.observe-recovery.ts
- src/config/sessions.test.ts
- src/config/sessions/store.session-key-normalization.test.ts
- src/config/talk.normalize.test.ts
- src/config/zod-schema.cron-retention.test.ts
- src/plugin-sdk/browser-cdp.ts
- src/plugin-sdk/browser-subpaths.test.ts
- ui/src/ui/views/overview-log-tail.ts

This section documents OpenClaw's integrated **Browser Automation** subsystem, which enables agent-driven control of Chromium-based browsers (Chrome, Brave, Edge, Chromium). It covers the architecture and implementation of the browser control service, the management of isolated browser profiles, tab lifecycle and CDP (Chrome DevTools Protocol) based tab control, supported browser actions invoked by agents, and the Chrome extension relay.

## 1. Purpose and Scope

OpenClaw embeds a dedicated browser control service to allow agent automation within fully isolated Chromium browser sessions. This system supports multi-profile management, deterministic tab control, user-like agent actions (click, type, drag, snapshot), and interaction with real user sessions via Chrome MCP (Model Context Protocol).

This subsystem is designed to provide a "safe lane" for agents that does not interfere with the user's daily browsing. Unlike lightweight HTTP tools like `web_search` or `web_fetch`, the browser tool handles JS-heavy sites and authenticated sessions.

## 2. Architecture Overview

### 2.1 Browser Profiles and Isolation

- Profiles: OpenClaw manages multiple browser profiles, isolated from the user's personal browser profiles. The main agent profile is openclaw , which uses a dedicated Chromium profile directory extensions/browser/src/browser/chrome.ts 62-64
- Managed vs Existing Session: Driver modes define lifecycle management: Managed: OpenClaw launches and manages the browser instance (default for openclaw profile). This includes "decorating" the profile with a custom theme color and download settings extensions/browser/src/browser/chrome.ts 97-101 Existing Session: Attaches to an existing real browser session (e.g., user's logged in Chrome) via MCP transport extensions/browser/src/browser/chrome-mcp.ts 44-49
- Profile Configuration: Profiles are declared in openclaw.json . Each profile has its own CDP port, user data directory, and assigned UI color extensions/browser/src/browser/chrome.ts 56-62

### 2.2 Browser Control Service (Bundled Plugin)

The browser automation logic is implemented as a **bundled plugin**.

- It runs as a local control service inside the Gateway.
- Controls profile launch, tab lifecycle (list/open/focus/close), and dispatches agent browser commands.
- Enforces SSRF (Server Side Request Forgery) guards to validate navigation targets extensions/browser/src/browser/chrome.ts 7-9
- Node Host Invoke: Commands can be executed via runBrowserProxyCommand , which manages the lifecycle of the browser control context and dispatches requests to the appropriate route.

### 2.3 CDP and MCP Transports

- CDP (Chrome DevTools Protocol): The main control channel using WebSocket and REST APIs. Discovery of WebSocket URLs typically happens via the /json/version endpoint extensions/browser/src/browser/chrome.ts 31-33
- Playwright Integration: For advanced actions (click, type, drag, snapshot), OpenClaw uses Playwright on top of CDP. This provides a high-level API for interacting with the DOM. Evaluations can be aborted using AbortController signals to prevent hanging processes.
- Chrome MCP: For existing-session profiles, communication uses the chrome-devtools-mcp package via a StdioClientTransport relay extensions/browser/src/browser/chrome-mcp.ts 8-9 This allows the agent to interact with a user's real browser session by wrapping MCP tool calls like list_pages , new_page , and take_screenshot extensions/browser/src/browser/chrome-mcp.ts 44-49

Sources:
[extensions/browser/src/browser/chrome.ts7-101](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.ts#L7-L101)
[extensions/browser/src/browser/chrome-mcp.ts8-49](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.ts#L8-L49)

## 3. Key Components and Implementation

### 3.1 CDP Communication and Discovery

The `chrome.ts` and `cdp.ts` files provide the transport for interacting with Chromium.

- WebSocket Normalization: The normalizeCdpWsUrl function ensures that WebSocket URLs are correctly formatted for the DevTools protocol extensions/browser/src/browser/cdp.ts 35
- Diagnostic Probes: diagnoseChromeCdp is used to verify if a browser instance is reachable and healthy before attempting actions extensions/browser/src/browser/chrome.ts 85-90
- Profile Decoration: Before launching a managed profile, decorateOpenClawProfile writes Chrome Preferences to set the profile name and theme color extensions/browser/src/browser/chrome.ts 97-101

### 3.2 Chrome MCP Integration

The MCP integration allows OpenClaw to control external browsers via a standardized protocol.

- Session Management: Sessions are cached in a Map and managed by a ChromeMcpSessionFactory extensions/browser/src/browser/chrome-mcp.ts 141-143
- Tool Mapping: MCP tool results are parsed into internal BrowserTab structures. The extractStructuredPages function handles both structured JSON and legacy text-based page lists from the MCP server extensions/browser/src/browser/chrome-mcp.ts 226-227
- Command Construction: buildChromeMcpArgs dynamically generates the npx or direct command arguments needed to launch the MCP bridge, including --userDataDir and --browserUrl extensions/browser/src/browser/chrome-mcp.test.ts 168-179

### 3.3 Security and SSRF Protection

Browser automation enforces strict security boundaries to prevent SSRF via the browser.

- Loopback Bypass: When a proxy is configured, CDP connections to localhost or 127.0.0.1 are protected by a managed proxy bypass, which ensures local browser control traffic does not exit the machine extensions/browser/src/browser/chrome.internal.test.ts 28-30
- Direct Agents: The system uses fetchWithSsrFGuard to validate CDP endpoint URLs against configured policies before connection extensions/browser/src/browser/client-fetch.loopback-auth.test.ts 12-18
- Redaction: Sensitive information like CDP tokens or credentials in URLs are redacted in logs via redactCdpUrl and redactToolPayloadText extensions/browser/src/browser/chrome-mcp.ts 21-25
- Navigation Guard: Target URLs are checked against navigation boundaries before allowing Playwright or MCP to navigate.

Sources:
[extensions/browser/src/browser/chrome.ts85-101](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.ts#L85-L101)
[extensions/browser/src/browser/chrome-mcp.ts21-227](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.ts#L21-L227)
[extensions/browser/src/browser/chrome-mcp.test.ts168-179](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.test.ts#L168-L179)
[extensions/browser/src/browser/chrome.internal.test.ts28-30](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.internal.test.ts#L28-L30)
[extensions/browser/src/browser/client-fetch.loopback-auth.test.ts12-18](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/client-fetch.loopback-auth.test.ts#L12-L18)

## 4. Data Flow: Gateway to Browser Node

### Browser Logic Entity Mapping

The following diagram bridges natural language concepts to the code entities that implement them.

Title: "Browser Logic Entity Mapping"

```

```

Sources:
[extensions/browser/src/browser/chrome.ts1-46](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.ts#L1-L46)
[extensions/browser/src/browser/chrome-mcp.ts1-49](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.ts#L1-L49)

### Physical Data Flow

The Gateway routes agent requests through the `Browser Plugin`. Depending on the profile configuration, it uses direct CDP calls or the MCP relay for existing sessions.

Title: "Browser Data Flow Architecture"

```

```

Sources:
[extensions/browser/src/browser/chrome-mcp.ts44-49](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.ts#L44-L49)
[extensions/browser/src/browser/chrome.ts1-28](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.ts#L1-L28)

## 5. Agent Browser Actions Reference

Agent interactions are executed via the `browser-tool.actions.ts` handler.

## 6. Troubleshooting

- Profile Locks: If Chromium reports the profile is in use, clearStaleChromeSingletonLocks attempts to remove SingletonLock , SingletonSocket , and SingletonCookie files extensions/browser/src/browser/chrome.ts 136-144
- Process Cleanup: terminateChromeForRetry sends SIGKILL to hanging browser processes and waits for exit before retrying extensions/browser/src/browser/chrome.ts 192-200
- Stale MCP Pages: If a selected page is closed, the system detects STALE_SELECTED_PAGE_ERROR and informs the agent to refresh the page list extensions/browser/src/browser/chrome-mcp.ts 137-138
- Launch Failures: chromeLaunchHints provides specific advice for Linux sandbox issues or missing DISPLAY servers extensions/browser/src/browser/chrome.ts 202-221

Sources:
[extensions/browser/src/browser/chrome.ts136-221](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome.ts#L136-L221)
[extensions/browser/src/browser/chrome-mcp.ts137-138](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/browser/src/browser/chrome-mcp.ts#L137-L138)
