Principle:Openclaw Openclaw Browser CDP Relay
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Chrome_Extension, WebSocket_Relay |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
A relay bridge pattern that forwards Chrome DevTools Protocol (CDP) commands and events between a local Gateway server and browser tabs through a Chrome Extension service worker and WebSocket connection.
Description
The Browser CDP Relay principle enables remote browser automation without requiring a standalone Chromium instance (like Puppeteer's bundled browser). Instead, it leverages a Chrome Extension's privileged Debugger API access to attach to the user's existing browser tabs and relay CDP messages bidirectionally.
This solves two problems:
- Session reuse: Automation operates on the user's actual browser session with existing cookies, logins, and extensions, rather than a sterile headless instance.
- Resource efficiency: No need to launch a separate Chromium process; the extension attaches to existing tabs on demand.
The architecture consists of three layers:
- Gateway relay server: Listens on a local WebSocket port (default 18792) and dispatches CDP commands from the agent's browser tool.
- Extension service worker: Maintains the WebSocket connection to the relay and maps CDP sessions to browser tabs via the Chrome Debugger API.
- Options page: Provides user configuration for the relay port and connection status verification.
Usage
Use this principle when the Gateway's browser automation tool needs to control real browser tabs on the user's machine. The user installs the Chrome Extension, clicks the toolbar icon to attach a tab, and the Gateway can then send CDP commands (navigate, query DOM, evaluate JavaScript, take screenshots) through the relay.
Theoretical Basis
The relay follows a session-multiplexed bidirectional proxy pattern:
Protocol flow:
# Abstract message flow (NOT real implementation)
# Gateway → Relay WebSocket → Extension Service Worker → Chrome Debugger API → Tab
# 1. Gateway sends CDP command to relay
relay.send({ id: N, method: 'forwardCDPCommand',
params: { sessionId, method: 'Page.navigate', params: { url } } })
# 2. Extension dispatches to chrome.debugger.sendCommand(debuggee, method, params)
# 3. Chrome returns result
# 4. Extension sends result back: relay.send({ id: N, result: { ... } })
# Events flow in reverse:
# Tab emits CDP event → chrome.debugger.onEvent → Extension → relay.send({ method: 'forwardCDPEvent', ... })
Session management:
- Each attached tab gets a unique session ID (`cb-tab-{N}`).
- Child targets (iframes, workers) are tracked via `Target.attachedToTarget` events.
- Commands are routed by session ID, falling back to target ID, then to the first connected tab.