OpenClaw browser and Chrome extension: how to set them up

What the browser tool can do

The agent gets one tool, browser, and it covers the lot: open, switch and close tabs, navigate, click, type, hover, drag, select, fill and submit forms, wait for text to appear, read a page’s visible prose, take snapshots and screenshots, save a page as a PDF, download files and upload them into forms, answer dialogs, read the network log and console errors, and emulate a phone, a timezone or a locale. The tool reference lists the arguments. OpenClaw launches the first Chromium-family browser it finds (your system default if it is one, then Chrome, Brave, Edge, Chromium), gives it a data directory of its own, and drives it with Playwright over the DevTools protocol. On a desktop the window is visible, so you can watch the agent work; on a Linux machine with no display it runs headless on its own, as the configuration docs describe.

It is on because three defaults line up: the browser plugin ships enabled, browser.enabled is true, and local onboarding sets the full tool profile. If your agent says it has no browser tool, the setup docs name the usual causes: a coding tool profile, which has web search and fetch but not the browser (add "browser" to tools.alsoAllow), or a plugins.allow list that leaves the browser out. To check it from a terminal:

openclaw browser doctor
openclaw browser open https://example.com
openclaw browser snapshot

Its own browser or yours: three profiles

Which browser the agent drives, and so which logins it holds, is set by the profile. Three are built in, per the browser profiles docs:

For user, switch on remote debugging on Chrome’s inspect page, keep Chrome open, and click Allow when Chrome asks “Allow remote debugging?” the first time OpenClaw attaches. Brave and Edge attach the same way through a profile of your own pointed at their data directory, as the existing-session docs show.

chrome://inspect/#remote-debugging

On a Mac there is a middle way: import-profile copies cookies from one of your Chrome, Brave, Edge or Chromium profiles, optionally only for the sites you list, into a fresh profile the agent drives on its own. It takes one Keychain prompt and copies cookies only, and the CLI reference warns that some Google sessions are tied to the device and ask you to sign in again.

Every route to your logins hands the agent your accounts. OpenClaw’s browser security docs put it plainly: if a profile has logged-in sessions, “the model can access those accounts and data,” and attaching to your running Chrome “can act as you in whatever that host Chrome profile can reach.” Keep the agent on its own profile and give it accounts of its own where you can. Where the account has to be yours, as with the YouTube channel or TikTok your videos go out on, your signed-in browser is one of two ways an agent can post for you.

The OpenClaw Chrome extension

The extension is OpenClaw’s way into your everyday Chrome without the remote-debugging prompt, which is why it keeps working while you are away from the desk and messaging the agent from your phone, as long as the computer and Chrome stay on. It is a relay, not an assistant: no chat box and no sidebar, just a popup showing whether it is connected, with a Pause or Allow button for the current tab. It is listed in the Chrome Web Store as OpenClaw, from the OpenClaw Foundation. Per the extension docs, automatic pairing needs OpenClaw, or an OpenClaw node, on the same computer as Chrome (pairing by hand to a Gateway elsewhere is covered further down). Chrome, Chromium and Chrome for Testing are supported on macOS and Linux; Windows needs the bootstrap helper that ships with OpenClaw’s packaged CLI or its Windows companion app.

On the computer with Chrome, run the installer and leave it running while Chrome finishes:

openclaw browser extension install

On macOS it registers OpenClaw’s local helper and asks Chrome to install the Store extension, which Chrome picks up the next time it starts: quit Chrome fully, reopen it, and approve OpenClaw. On Linux, add the extension from the Chrome Web Store once the command has registered the helper. Pairing then happens by itself, with no code to copy, as long as the Gateway is running. The macOS app runs the same setup on its own. To make the extension the agent’s default browser:

openclaw config set browser.defaultProfile chrome

Or leave the default alone and ask the agent to use the chrome profile for the jobs that need your logins. What it can reach then is the extension’s access mode, set on its Settings page:

• All tabs: every ordinary tab in that Chrome profile, except tabs you pause from the popup. A new automatic pairing starts here.
• Selected tabs: only tabs in the OpenClaw tab group. Drag a tab in to grant access, drag it out to revoke it. An extension paired before All tabs existed stays in this mode.

Either way, tabs the agent opens itself land in the OpenClaw group, and incognito windows and Chrome’s internal pages are never reachable. The extension asks Chrome for the debugger, tabs, tab groups, storage, alarms and native messaging permissions; the debugger permission is the one that drives pages, and the rest find tabs, enforce the access mode and keep the pairing. In Settings, “Disconnect and disable automatic setup” revokes the pairing at once.

If it never connects, the usual cause is Chrome having looked for the helper before it was installed: Chrome remembers the miss until the whole browser restarts, so quit it once and reopen it. If you removed the extension at some point, Chrome remembers that too; add it again from the Store. Then check from the terminal:

openclaw browser extension status
openclaw browser --browser-profile chrome tabs

An empty tab list does not mean a broken connection: in Selected tabs mode it can just mean nothing is in the group yet.

Running it on a server

In Docker, use an image with a browser in it. The plain image has none; the -browser tags ship Chromium:

ghcr.io/openclaw/openclaw:latest-browser

For a deployment you keep, the Docker docs point to a release’s own -browser tag instead of that moving one, and a build from source gets Chromium and the Xvfb virtual display with OPENCLAW_INSTALL_BROWSER=1. The Docker image variants have their own guide. Without Docker, OpenClaw finds a Chrome or Chromium installed in the usual places; on Ubuntu, the Linux troubleshooting docs recommend Google’s own Chrome package over the snap Chromium that apt installs, whose confinement interferes with how OpenClaw starts the browser.

A server has no display, so the browser runs headless, and a headless Chrome announces itself to every site as HeadlessChrome. In a test of 83 URLs on September 3, 2026, twelve sites refused a cloud server’s headless browser and opened when the same browser ran with a display on the same server; the site-by-site results name them. OpenClaw only falls back to headless when no display is present, so with Xvfb running and DISPLAY exported before the Gateway starts, it runs the browser headed unless you have set it headless yourself. If Chromium will not start in a container at all, with “No usable sandbox”, the fix that keeps Chrome’s sandbox has its own guide.

At rest the weight is modest: in July 2026, OpenClaw 2026.6.11’s browser image unpacked to about 3 GB, and the container idled at about 540 MiB on a 2 vCPU, 4 GB server. Browsing is what costs memory: a Chromium renderer for every open tab, and a small server with no swap can run out of it. For agents that only read pages, OpenClaw can attach to Lightpanda, an opt-in lighter engine you run beside it for text and DOM work, with no rendered screenshots or PDFs (Lightpanda is AGPL-licensed, unlike OpenClaw). Cloudflare’s Kitesurf is a hosted engine built on the same premise, that an agent does not need all of Chromium.

Two other arrangements are documented. A profile with a cdpUrl attaches to a Chromium running somewhere else, and the remote browser docs give the settings for the hosted services Browserless, Browserbase and Notte. And with the Docker sandbox on, a sandboxed session can have a browser container of its own, on a dedicated Docker network called openclaw-sandbox-browser, once the browser tool is allowed in the sandbox’s tool policy, which denies it by default; it cannot drive the host’s browser unless you set allowHostControl.

Logging in when the agent is on a server

An agent on a server begins with none of your logins, which is the safer default. There are three ways to give it some.

Sign its own browser in yourself. The dashboard’s Browser panel shows the agent’s browser live in any web browser and passes your clicks, scrolling and typing through to it, pastes into password fields included; it needs an admin connection to the Gateway (more on opening the dashboard). OpenClaw’s login docs recommend signing in by hand, because automated logins “often trigger anti-bot defenses and can lock the account.” Google accounts can be the exception: Google says it may stop sign-ins from browsers “being controlled through software automation rather than a human”, which describes the agent’s browser even when you do the typing.

Copy cookies from a Mac. cookie-sync decrypts your Mac’s cookies for the sites you list and pushes them into a profile on the remote Gateway; --domains is required, so it never sends the whole cookie jar, and --watch keeps them current. The same device-bound Google caveat applies.

openclaw browser --url wss://gateway.example.com \
  cookie-sync --domains github.com --into work --watch

Drive the browser on your own computer. Run a node host there (openclaw node run, paired to your Gateway) and the Gateway routes browser calls to it, the user and chrome profiles included. If the server has a browser of its own, OpenClaw prefers that one; point the agent at the node, or pin it with gateway.nodes.browser.node. Without a node, the extension can pair straight to the remote Gateway. Generate a pairing string on the server:

openclaw browser extension pair --gateway-url wss://gateway.example.com

Paste it into the extension’s Settings, under Advanced manual pairing, and treat it as a password. That route needs the Gateway’s /browser/extension path reachable over wss://. Either way, your computer and Chrome have to be on whenever the agent needs them, and the security docs ask you to treat a node’s pairing like admin access and keep the Gateway and the node on the same private network, such as a tailnet.

What it hands back to you, and what it blocks

When a page needs a login, a two-factor code, a CAPTCHA, or permission for the camera or microphone, the browser skill that ships with OpenClaw tells the agent to stop and tell you exactly what is needed rather than guess. OpenClaw has no CAPTCHA solver of its own, and that is the right position, because the open web increasingly challenges automated browsers on sight, and an agent that hits a bot wall should say so. For a task you authorize, the login docs let the agent type in credentials you supply, kept out of the chat and its replies.

Navigation is guarded too: private and internal addresses, such as your router or other services on the same machine, stay blocked unless you opt in with dangerouslyAllowPrivateNetwork or list exact hosts in allowedHostnames. The policy’s own docs are clear that it guards what the browser navigates to and is not a firewall: redirects, a pop-up’s first request and service workers can get past it.

And every page the agent reads is untrusted input. OpenClaw’s prompt injection docs name browser pages among the content that can carry instructions to the model, which is one more reason to keep the browser on the agent’s own profile and the agent on a machine you don’t mind it owning. If your agent never needs to run its own JavaScript inside pages, setting browser.evaluateEnabled to false removes that ability, which the docs warn prompt injection can steer.