OpenClaw Browser Relay

WebSocket relay that connects the OpenClaw bot to a Chrome extension, allowing remote browser control of FleetOS.

Architecture

Bot (EC2/local)  -->  Relay Server (Node.js)  -->  Chrome Extension (Manifest V3)
                       ws://localhost:9222                |
                                                    Chrome Browser
                                                  (FleetOS loaded)

Quick Start

1. Start the relay server

cd relay-server
npm install
node server.js
# or: RELAY_AUTH_TOKEN=my-secret-token node server.js

Server starts on ws://localhost:9222.

2. Load the Chrome extension

1. Generate icons (optional, placeholders work):

   cd extension/icons && node generate-icons.cjs

2. Open Chrome → chrome://extensions/

3. Enable Developer mode (top-right toggle)

4. Click Load unpacked → select the extension/ folder

5. Click the extension icon in the toolbar

6. Enter relay URL (ws://localhost:9222) and auth token

7. Click Save & Connect — status should show "Connected"

3. Run the bot client

cd client
npm install
RELAY_AUTH_TOKEN=changeme-openclaw-relay-token node examples/demo-fleetos.js

Supported Commands

Command	Params	Description
navigate	{ url }	Go to URL, wait for page load
click	{ selector } or { text }	Click by CSS selector or visible text
fill	{ selector, value }	Fill input (React-aware)
screenshot	{ quality? }	Capture visible tab as base64 PNG
extractText	{ selector? }	Get innerText (whole body if no selector)
extractData	{ selector }	Get text, html, attributes for all matches
evaluate	{ expression }	Run JS expression in page context
waitFor	{ selector?, text?, timeout? }	Poll for element/text appearance
getUrl	—	Get current tab URL
getTitle	—	Get current tab title

Bot Client SDK

const { BrowserRelay } = require('./relay-client');

const relay = new BrowserRelay({
  url: 'ws://localhost:9222',
  token: 'changeme-openclaw-relay-token',
});

await relay.connect();

// Navigate
await relay.navigate('https://fleetos.us');

// Interact
await relay.click('Login');
await relay.fill('input[name="email"]', '[e-mail]');

// Screenshot
const { dataUrl } = await relay.screenshot();

// Extract data
const { text } = await relay.extractText('.dashboard');

// Wait for elements
await relay.waitForSelector('.job-list', 10000);

// Convenience
await relay.navigateAndWait('https://fleetos.us/jobs', '.job-list');
await relay.fillForm([
  { selector: '#email', value: '[e-mail]' },
  { selector: '#password', value: 'secret' },
]);

relay.disconnect();

Remote Access (EC2)

For remote bot → local Chrome, use SSH tunneling:

# On your local machine (where Chrome runs):
ssh -R 9222:localhost:9222 ubuntu@your-ec2-ip

The bot on EC2 connects to ws://localhost:9222 which tunnels back to your local relay server.

Security Notes

• Auth token required for both extension and bot connections

• Default host permissions are scoped to fleetos.us and localhost:3000

• Use SSH tunneling for remote access rather than exposing the relay to the internet

• Change the default token in production

• The evaluate command can run arbitrary JS in the page — use with care

Troubleshooting

Extension shows "Disconnected"

• Verify relay server is running (node server.js)

• Check the token matches between server and extension popup

• Check Chrome DevTools → Extensions → service worker console for errors

Commands time out

• Ensure a FleetOS tab is open in Chrome

• Check the relay server logs for routing issues

• Default timeout is 60s (server-side stale cleanup)

React inputs not updating

• The extension uses native property setters to bypass React's synthetic event system

• If a specific input type doesn't work, use evaluate to set the value directly