Openclaw Browser Relay: Connect Agents to Hosted Chromium

An Openclaw browser relay is the connection layer that lets an Openclaw agent drive a browser it does not own locally. Instead of launching Chromium on the same machine as the agent, the agent sends commands to a remote browser session and receives page state back. In practice, most relays are just Chrome DevTools Protocol (CDP) endpoints wrapped in session management: create a session, get a WebSocket URL, attach Playwright or Puppeteer, run the task, tear it down.

This guide covers what the Openclaw browser relay actually does, the trade-offs between local and hosted relays, and how to wire one up on Remote Browser without managing Chromium infrastructure yourself. If you are still deciding whether you need a hosted runtime at all, start with Remote browsers for AI agents and come back here for the wiring.

What an Openclaw browser relay actually is

The word "relay" gets used loosely. In an agent stack it usually means one of three things:

• A CDP proxy. A process that accepts a WebSocket connection from your agent and forwards it to a browser's debugging endpoint. This is the most literal meaning.
• A session broker. An API that provisions a browser, returns a connection URL, and handles lifecycle (timeouts, cleanup, isolation). The relay is the broker plus the endpoint.
• A tool bridge. A layer that exposes browser actions (click, type, navigate) as tool calls to an LLM-driven agent, translating them into CDP or Playwright calls underneath.

Openclaw-style agents typically need the second and third. The agent reasons about a task, calls browser tools, and the relay turns those calls into real browser operations on a remote session. The important architectural point: the relay is stateless from the agent's perspective. The agent holds a session handle; the browser lives elsewhere.

Why "relay" and not "browser"

A local browser is a process your code spawns. A relayed browser is a service your code connects to. That distinction drives everything downstream — isolation, scaling, persistence, and failure modes. When the browser is remote, a crashed agent does not take the browser with it, and a crashed browser does not corrupt the agent's host. You can also run many sessions in parallel without provisioning machines per task.

Local relay vs hosted relay: the trade-off

Most teams start with a local relay because it is free and fast to set up. The friction shows up at scale.

The local relay is not wrong. For a single developer iterating on a script, it is the fastest path. The hosted relay earns its keep when you need concurrency, session isolation, or persistent logins that survive redeploys. The decision is less about capability and more about who owns the failure modes.

Where local relays break down

Three failure patterns recur:

1. Version drift. The Chromium on your laptop, your CI runner, and your production worker are different builds. Selectors and CDP behavior shift between them.
2. Zombie processes. A crashed agent leaves a headless Chromium running. Multiply by a few hundred tasks and the host runs out of memory.
3. Shared state. Two agents writing cookies to the same profile directory corrupt each other's sessions.

A hosted relay addresses all three by making the browser a managed resource with an explicit lifecycle. You create it, you connect, you stop it. The provider handles cleanup.

How the relay connection works over CDP

CDP is the wire protocol. Chromium exposes a debugging endpoint, and clients like Playwright and Puppeteer speak CDP to it. A relay is a stable, authenticated endpoint in front of that debugging port.

The flow is consistent across providers:

1. Your agent requests a session from the relay API.
2. The API returns a CDP WebSocket URL (and often a session ID for lifecycle calls).
3. Your agent connects Playwright or Puppeteer to that URL.
4. The agent runs its task; the browser executes on the remote host.
5. The agent stops the session, or the relay times it out.

Playwright's connectOverCDP is the standard entry point. It attaches to an existing browser rather than launching one. The Playwright CDP documentation is the authoritative reference for the method signature and its Chromium-only constraint.

A minimal TypeScript relay client

The following example connects to a hosted session, opens a page, and extracts content. It assumes your relay returns a CDP endpoint and a session ID.

import { chromium, Browser, Page } from "playwright";

interface RelaySession {
  cdpUrl: string;
  sessionId: string;
}

async function createRelaySession(): Promise<RelaySession> {
  const res = await fetch(`${process.env.RELAY_BASE_URL}/sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.RELAY_API_KEY}`,
    },
    body: JSON.stringify({
      // Configurable browser settings: proxy, profile, viewport, etc.
      profile: "checkout-agent",
      timeoutSeconds: 600,
    }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return (await res.json()) as RelaySession;
}

async function runTask(session: RelaySession) {
  let browser: Browser | undefined;
  try {
    browser = await chromium.connectOverCDP(session.cdpUrl);
    const context = browser.contexts()[0] ?? (await browser.newContext());
    const page: Page = context.pages()[0] ?? (await context.newPage());

    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
    const title = await page.title();
    console.log("Page title:", title);

    // Agent logic goes here: locate elements, fill forms, read state.
    return title;
  } finally {
    // Closing the CDP connection does not always stop the remote browser.
    // Call the relay's stop endpoint to release the session explicitly.
    await browser?.close();
    await fetch(`${process.env.RELAY_BASE_URL}/sessions/${session.sessionId}`, {
      method: "DELETE",
      headers: { Authorization: `Bearer ${process.env.RELAY_API_KEY}` },
    });
  }
}

(async () => {
  const session = await createRelaySession();
  await runTask(session);
})();

Two details matter in production. First, browser.close() on a CDP connection may disconnect without terminating the remote browser — always call the relay's stop endpoint. Second, wrap the whole task in a timeout that is shorter than the session timeout, so a hung agent does not burn billable time. The documentation covers the session API surface in more detail.

Production criteria for choosing a relay

When you evaluate an Openclaw browser relay, test against the workloads you actually run, not a demo page. The criteria that separate usable relays from frustrating ones:

• Session isolation. Does each session get its own browser context and storage? Shared state across sessions is a correctness bug, not a performance trade-off.
• Persistent profiles. Can an agent log in once and reuse the session state on the next run? This is the difference between a demo and a workflow that touches authenticated sites.
• Live viewer. Can a human watch the session in real time when the agent gets stuck? Debugging blind is expensive.
• Proxy and network controls. Are proxy settings configurable per session? IP quality affects success rates on sites with bot defenses.
• CDP fidelity. Does the relay expose a real CDP endpoint, or a lossy abstraction? If Playwright's full API does not work, your tooling is constrained.
• Usage controls. Are there per-session timeouts, concurrency limits, and clear metering? Unbounded sessions are a cost incident waiting to happen.
• Cleanup guarantees. Does the relay terminate sessions on timeout, or do they linger?

Remote Browser provides hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, a live viewer, persistent profiles, configurable proxy and browser settings, and per-session isolation. Current limits and metering are on the pricing page; check there rather than assuming a concurrency ceiling.

What "configurable browser settings" means in practice

Be precise about what a relay controls. Configurable settings typically include viewport, user agent, locale, timezone, and proxy. Some providers go further with hardened Chromium builds. What you should not assume without documentation is automated fingerprint spoofing or guaranteed bypass of bot detection — those are claims that need evidence, and they vary by site and by provider. Treat stealth as a spectrum you test, not a checkbox you trust.

Wiring Openclaw agents to the relay

The agent side is where most integration bugs live. A few patterns that hold up:

Keep the relay client thin. The agent should call a small set of browser tools (navigate, click, type, read, screenshot). The relay client translates those to Playwright calls. Do not let the LLM generate raw CDP messages — the failure modes are opaque.

Snapshot before acting. After each navigation or significant DOM change, capture a compact representation of the page (accessibility tree or trimmed HTML). Agents that act on stale state click the wrong element.

Bound every step. Set per-action timeouts and a total task budget. A relay session that runs for an hour because the agent looped is a metering problem and a correctness problem.

Log the CDP endpoint and session ID. When something fails, you need to correlate the agent trace with the browser session. The live viewer plus the session ID is your debugging pair.

Reuse profiles deliberately. Persistent profiles are powerful for authenticated workflows and dangerous for isolation. Use a named profile per workflow, not a shared default.

If you are comparing relay options before committing, the remote browser online guide walks through what a hosted session gives you versus a local install, and remote control browser covers the control-plane side.

Common failure modes and how to handle them

Connection drops mid-task. CDP WebSocket connections are not guaranteed to survive network blips. Implement reconnect logic that re-attaches to the same session rather than creating a new one. If the session is gone, fail the task cleanly.

Session leaks. If your agent crashes before the stop call, the session lingers until timeout. Use a supervisor process or a finally block that always calls stop, and set session timeouts conservatively.

Selector drift. Sites change. Agents that hardcode selectors break silently. Prefer role- and text-based locators, and validate that the expected element exists before interacting.

Auth walls. Persistent profiles help, but expired sessions still fail. Detect login redirects and either refresh credentials or escalate to a human via the live viewer.

Cost surprises. Long-running sessions and high concurrency compound. Meter per task, alert on outliers, and review session duration distributions weekly.

When a relay is the right call

Use a hosted Openclaw browser relay when any of these are true: you need more concurrency than one host can provide, you need session isolation for correctness, you need persistent logins across deploys, or you need a human to watch sessions live. Stay local when you are prototyping a single script and the browser is incidental.

The relay is infrastructure, not a feature. Choose it the way you choose a database: based on failure modes, operational burden, and cost predictability — not on a benchmark you did not run yourself. Start with the documentation to see the session API, then run one real workflow end to end before you scale.