OpenClaw Browser Relay

What Is the Browser Relay?

The OpenClaw browser relay is a bridge between your AI agent and a web browser instance. It allows OpenClaw to browse the web on your behalf — navigating websites, reading content, interacting with page elements, and taking screenshots.

Under the hood, the relay uses the Chrome DevTools Protocol (CDP) to communicate with a browser. CDP is the same protocol that Chrome DevTools, Playwright, and Puppeteer use to control browsers programmatically. The relay abstracts all this complexity so your agent can simply receive natural language instructions like “go to reddit.com and summarize the front page.”

Without the browser relay, your OpenClaw agent can still use built-in web search to fetch and read web pages. But the relay unlocks interactive capabilities — clicking, scrolling, form filling, handling JavaScript-rendered content, and working with single-page applications (SPAs) that basic HTTP fetching cannot handle.

How the Browser Relay Works

The browser relay architecture has three components that work together:

  +------------------+       CDP/WebSocket       +--------------------+
  |                  | ----------------------->  |                    |
  |  OpenClaw Agent  |                           |  Headless Browser  |
  |  (your instance) | <-----------------------  |  (Chromium)        |
  |                  |       page data, DOM       |                    |
  +------------------+                           +--------------------+
         |                                               |
         |  natural language                              |  renders pages
         |  commands from you                             |  executes JS
         v                                               v
  +------------------+                           +--------------------+
  |  Telegram /      |                           |  Any website on    |
  |  Discord / Web   |                           |  the internet      |
  +------------------+                           +--------------------+

1. Your agent receives a natural language command from you via Telegram, Discord, or the web gateway (e.g., “search for flights to Tokyo”).
2. The relay translates the agent's actions into CDP commands and sends them to the headless browser over a WebSocket connection.
3. The headless browser (Chromium) executes the commands — navigating to URLs, clicking elements, reading the DOM — and sends results back through the relay to the agent.

The relay maintains a persistent WebSocket connection to the browser, so actions happen in real time. Your agent can chain multiple actions together: navigate to a page, wait for it to load, click a button, fill a form, and read the result — all in a single conversation turn.

Setting Up the Browser Relay (Self-Hosted)

If you are running OpenClaw on your own server, follow these steps to set up the browser relay:

Step 1: Install a Headless Browser

The relay needs a Chromium-based browser to connect to. On most Linux servers:

# Ubuntu / Debian
sudo apt update
sudo apt install -y chromium-browser

# Or use Google Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install

Step 2: Launch the Browser with Remote Debugging

Start the browser in headless mode with CDP remote debugging enabled:

chromium-browser --headless --no-sandbox \
  --remote-debugging-port=9222 \
  --remote-debugging-address=127.0.0.1

This starts a headless Chromium instance listening for CDP connections on port 9222. Using 127.0.0.1 ensures the debugging port is only accessible locally (not exposed to the internet).

Step 3: Configure OpenClaw to Use the Relay

In your OpenClaw configuration (~/.openclaw/openclaw.json), enable the browser relay skill and point it to your headless browser:

{
  "tools": {
    "media": {
      "browser": {
        "enabled": true,
        "cdpEndpoint": "ws://127.0.0.1:9222"
      }
    }
  }
}

Step 4: Verify the Connection

Send a message to your agent asking it to browse a website:

"Go to https://example.com and tell me what's on the page."

If the relay is working, the agent will navigate to the page and describe its content. If you see an error, check the troubleshooting section below.

Running with Docker

If OpenClaw runs in Docker, you can either run the headless browser in the same container or in a separate container. For a separate container:

# Run a headless Chrome container
docker run -d --name chrome-headless \
  --network openclaw-net \
  -p 9222:9222 \
  browserless/chromium

# Point OpenClaw to it
# cdpEndpoint: "ws://chrome-headless:9222"

Using Browser Relay on OpenClaw Launch

If you use OpenClaw Launch to deploy your agent, the browser relay is pre-configured and ready to use. Each instance gets a dedicated headless browser with the relay already connected.

You do not need to:

• Install or configure a headless browser
• Set up CDP endpoints or WebSocket connections
• Manage browser containers or processes
• Handle port mapping or network configuration

Simply enable the browser skill from your dashboard and start sending browsing commands to your agent. For more details on what your agent can do with browser automation, see our OpenClaw Browser Automation guide.

Common Issues & Fixes

“Relay Not Reachable” Error

This is the most common browser relay issue. It means your OpenClaw agent cannot establish a WebSocket connection to the headless browser. Common causes:

• The headless browser is not running or crashed
• The CDP endpoint URL is incorrect in your configuration
• A firewall is blocking the connection on port 9222
• Docker networking is preventing container-to-container communication

For a complete walkthrough of fixes, see our dedicated “Relay Not Reachable” troubleshooting guide.

Connection Timeouts

If the relay connects but then times out during browsing:

• Increase timeout settings — Some pages take longer to load. Check your OpenClaw configuration for browser timeout values and increase them.
• Check browser memory — Headless browsers can consume significant memory. Ensure your server has at least 1–2 GB of RAM available for the browser process.
• Reduce concurrent tabs — Each open tab consumes memory. If your agent opens many tabs, the browser may slow down or crash.
• Restart the headless browser — Long-running browser processes can accumulate memory leaks. Periodically restarting clears them.

Firewall & Port Issues

The CDP connection uses WebSockets on a specific port (default 9222). If you have a firewall:

• Local connections only: If OpenClaw and the browser are on the same machine, bind to 127.0.0.1 and ensure port 9222 is open for localhost.
• Docker networking: Use a shared Docker network (docker network create openclaw-net) so containers can reach each other by name.
• Remote servers: If the browser runs on a different server, use an SSH tunnel instead of exposing port 9222 publicly: ssh -L 9222:127.0.0.1:9222 user@browser-server
• Never expose CDP publicly: The CDP debugging port gives full control over the browser. Always keep it behind a firewall or bind to localhost.

Browser Relay vs. Browser Automation Skill

These two terms are related but refer to different things:

You need both for web browsing to work: the relay provides the connection, and the automation skill provides the commands. On OpenClaw Launch, both are pre-configured for you.

Frequently Asked Questions

What is the OpenClaw browser relay?

The OpenClaw browser relay is a CDP-based bridge that connects your AI agent to a headless Chromium browser. It lets the agent browse the web, click buttons, fill forms, read page content, and take screenshots — all through natural language commands you send via Telegram, Discord, or the web gateway.

Do I need to install the browser relay myself?

It depends on your setup. If you self-host OpenClaw, you need to install a headless browser and configure the CDP endpoint. If you use OpenClaw Launch, the browser relay is pre-configured and ready to use — no setup required.

Can the browser relay access websites behind a login?

Yes. Since the relay controls a real browser session, it can log in to websites, maintain cookies and sessions, and access authenticated content. Your agent can fill in login forms and navigate authenticated pages just like you would manually.

Is the browser relay secure?

The relay runs on your server (or on OpenClaw Launch's infrastructure) and communicates over a local WebSocket connection. The CDP port should never be exposed to the public internet. On OpenClaw Launch, each instance gets an isolated browser with no shared state between users.

What's Next?

• OpenClaw Browser Automation — Full guide to browser automation capabilities and use cases
• OpenClaw Skills — Browse all available skills including browser, search, and more
• OpenClaw MCP Integration — Connect external tools and servers to your agent
• Fix “Relay Not Reachable” — Troubleshoot browser relay connection errors