1. Quick Start (The 2-Minute Installation)

If you just need to get the extension running on your local machine for testing, stick to this section. It works for Chrome, Brave, Edge, and all Chromium browsers.

1 Download & Extract

Download the latest release ZIP. Extract it to a permanent location like C:\Tools\OpenClaw\. Do not run it from your Downloads folder.

2 Enable Developer Mode

Go to your extensions page (chrome://extensions), toggle Developer mode ON in the top-right corner.

3 Load Unpacked

Click Load unpacked, browse to your extracted folder, and select it. The extension card should appear.

That's the basics. Now let's get into the real engineering.

Running OpenClaw on a VPS allows developers to deploy AI automation workflows that run 24/7 without relying on a local machine. By hosting OpenClaw on a server, you can create reliable AI agents, connect APIs, and automate complex tasks while maintaining better performance and uptime. Setting up OpenClaw on a VPS typically involves installing Node.js, configuring dependencies, and running the service using a process manager for continuous operation. If you want a complete step-by-step tutorial, check out this guide: How to Run OpenClaw on VPS (Complete Setup Guide) .

2. Advanced Configuration Deep Dive

Connecting to localhost:3000 is easy. Connecting to a secured, remote relay behind a corporate firewall requires a bit more finesse.

Authenticating with Secured Relays

If your relay is exposed publicly (or even on a shared internal network), you should be protecting it with an Authentication Token. Here is how to configure the extension to pass that token.

1. Open the extension settings.
2. In the Auth Token field, paste your API key.
3. This adds an Authorization: Bearer [YOUR_KEY] header to the initial WebSocket handshake.

// Example Header Configuration in Relay
{
  "relay_url": "wss://relay.production.com",
  "headers": {
    "X-Bot-ID": "scraper-01",
    "X-Custom-Auth": "secret-bypass-token"
  }
}

3. Automating Installation for CI/CD

Manually clicking "Load Unpacked" doesn't work when you're spinning up headless browsers in a GitHub Action or a Docker container. You need to load the extension programmatically.

Loading via Puppeteer / Playwright

Pass the --load-extension flag to your browser instance. Note that you also need --disable-extensions-except to ensure no other noise interferes with your tests.

Puppeteer Example

const puppeteer = require('puppeteer');

(async () => {
  const extensionPath = '/app/extensions/openclaw'; // Absolute path is safer
  
  const browser = await puppeteer.launch({
    headless: false, // Extensions don't work in 'new' headless mode for some versions
    args: [
      `--disable-extensions-except=${extensionPath}`,
      `--load-extension=${extensionPath}`,
      '--no-sandbox'
    ]
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  // OpenClaw is now active and connected
})();

Docker Persistency

If running in Docker, map the extension volume so you don't have to re-download it every build.

# docker-compose.yml
services:
  browser:
    image: node:20
    volumes:
      - ./extensions/openclaw:/app/extensions/openclaw

4. Security Hardening Guide

Method A: SSH Tunnels (Recommended for Dev)

Instead of opening port 3000 on your router, verify the connection using an SSH tunnel. This keeps the traffic encrypted and the port closed to the world.

# Forward local port 3000 to remote server's localhost:3000
ssh -L 3000:localhost:3000 user@your-server.com

Now configure your local extension to connect to localhost:3000, even though the relay is remote.

Method B: API Gateway / Reverse Proxy

If you must expose it (e.g., for a team), put it behind Nginx with Basic Auth or IP whitelisting.

# Nginx Snippet
location /ws {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    allow 192.168.1.0/24; # Allow only internal IP range
    deny all;
}

5. Integration: Sending Your First Command

You're installed. You're secured. Now let's use it.

OpenClaw exposes a REST API on the relay that forwards commands to the browser via the WebSocket connection we just set up.

The "Hello World" of Browser Automation

Open your browser (with the extension running) and a terminal side-by-side. Run this:

# 1. Check valid connection
curl http://localhost:3000/v1/browser/active
# Response: {"id": "chrome-001", "status": "idle"}

# 2. Navigate the browser
curl -X POST http://localhost:3000/v1/browser/navigate \
  -H "Content-Type: application/json" \
  -d '{"url": "https://news.ycombinator.com"}'

If your browser immediately redirects to Hacker News, congratulations. You have a working, remote-controlled browser node.

6. Advanced Troubleshooting

"WebSocket Connection Closed: 1006"

This generic error usually means a network-level block.

• Check CORS: If your relay is on a different domain, ensure your relay config allows the origin chrome-extension://[ID].
• Check Proxies: Corporate proxies often drop WebSocket connections. Try connecting via a mobile hotspot to rule this out.

"Extension ID Changes on Reload"

When loading unpacked extensions, Chrome may regenerate the ID if the `key` field is missing from `manifest.json`. To fix this for CI/CD consistency:

1. Pack the extension once manually (`chrome://extensions` > Pack extension).
2. This generates a `.pem` private key file.
3. Include this `.pem` file when loading the extension in future builds to keep the ID static.