# openclaw-browser-relay

**Repository Path**: maclee2009/openclaw-browser-relay

## Basic Information

- **Project Name**: openclaw-browser-relay
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw Browser Relay — Chrome Extension

A Chrome extension that automatically attaches [OpenClaw](https://github.com/anthropics/claude-code) to **all** browser tabs via a local CDP (Chrome DevTools Protocol) relay server. No manual toggle needed — every tab is always under OpenClaw control.

## Features

- **Auto-attach all tabs** — every open tab is automatically attached when the relay connects
- **New tabs auto-attach** — tabs opened after startup are attached as they finish loading
- **Resilient reconnection** — exponential backoff reconnect with automatic re-attach on relay recovery
- **Navigation survival** — debugger sessions re-attach seamlessly after in-page navigations
- **MV3 service worker** — state persisted across Chrome service worker restarts
- **Periodic keepalive** — alarm-based health checks ensure tabs stay attached

## Installation

1. Build/run OpenClaw Gateway with browser control enabled.
2. Ensure the relay server is reachable at `http://127.0.0.1:18792/` (default).
3. Install the extension to a stable path:

   ```bash
   openclaw browser extension install
   openclaw browser extension path
   ```

4. Open Chrome and navigate to `chrome://extensions`.
5. Enable **Developer mode** (toggle in the top-right).
6. Click **Load unpacked** and select the extension directory path printed above.
7. Pin the extension icon in the toolbar.

## Configuration (Options Page)

Right-click the extension icon → **Options**, or go to `chrome://extensions` → OpenClaw Browser Relay → Details → Extension options.

| Setting           | Description                                                                 | Default   |
|-------------------|-----------------------------------------------------------------------------|-----------|
| **Relay port**    | Port the local CDP relay server listens on                                  | `18792`   |
| **Gateway token** | Required. Set to your `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`)    | —         |

## How It Works

1. On startup (or reconnect), the extension connects to the local relay WebSocket server.
2. It queries all open tabs and attaches the Chrome debugger to each eligible tab (skipping `chrome://`, `chrome-extension://`, and `devtools://` URLs).
3. New tabs are automatically attached via `chrome.tabs.onUpdated` when they finish loading.
4. CDP commands from the relay are forwarded to the correct tab's debugger session; CDP events from tabs are forwarded back to the relay.
5. If the relay disconnects, the extension retries with exponential backoff and re-attaches all tabs on reconnect.
6. Clicking the extension icon manually triggers a reconnect + attach-all (useful for recovery).

## Permissions

| Permission        | Reason                                                    |
|-------------------|-----------------------------------------------------------|
| `debugger`        | Attach Chrome DevTools Protocol to tabs                   |
| `tabs`            | Query and monitor tab lifecycle                           |
| `activeTab`       | Access the active tab on icon click                       |
| `storage`         | Persist relay port, gateway token, and session state      |
| `alarms`          | MV3 keepalive timer for relay health checks               |
| `webNavigation`   | Refresh badges after navigation completes                 |

## License

MIT