Mastering Browser Automation
OpenClaw drives a real Chromium browser: it opens tabs, reads pages, clicks and types. This page covers which browser profile to give it and how much of that capability to leave switched on.
Introduction
Beyond simple API integrations, OpenClaw possesses profound capabilities when interacting with graphical user interfaces. Using the Computer Use model standard (popularized by Claude 3.5 Sonnet), your local agent can take control of a Chromium instance to perform complex visual navigation.
This tutorial covers everything from setting up your local Chrome testing environment to writing resilient prompt flows for web scraping.
1. Prerequisites
- β’OpenClaw v1.3.0 or newer.
- β’An LLM that supports Vision + Computer Use tools (e.g., Anthropic models or specialized local models like Qwen2-VL).
- β’Google Chrome or Chromium installed on the host machine.
2. Enabling the Browser Tool
In your OpenClaw configuration file (~/.openclaw/config.json), ensure the browser capability is enabled.
3. The "Coordinate & Click" Workflow
Unlike traditional DOM-based scrapers (like Puppeteer or Playwright), OpenClaw "sees" the screen. It takes a screenshot, calculates the X/Y coordinates of the button you want, and moves the virtual mouse to click it.
Example: Form Filling
You can prompt the agent naturally:
4. Dealing with Captchas
Because OpenClaw acts through a real browser profile, it naturally avoids many basic bot-detection scripts. However, for visible CAPTCHAs, you have two options:
- 1.Human-in-the-loop: Add a prompt instruction
- 2.API Solvers: Integrate a third-party solver skill alongside the browser skill.
5. Extracting Data (Visual Scraping)
Instead of parsing complex HTML nested tables, you can ask OpenClaw to visually construct the data.
Troubleshooting
- β’Click misses the target: Ensure your display scaling is set to 100%. Fractional scaling (150%) can confuse coordinate mapping.
- β’"Cannot find executable": Verify the browser_path in your config exactly matches your system's Chrome installation.
Which profile, and what each one costs you
This is the decision that determines everything else about browser automation, and it is a security decision before it is a capability one. The managed profile is isolated and fully featured; attaching to your own Chrome gives the agent your logged-in sessions and takes capabilities away.
| Managed "openclaw" profile | Attached Chrome session | |
|---|---|---|
| Logins | None. You sign in inside the isolated profile. | Yours, already active on every site. |
| CSS selector actions | Available | Not available |
| PDF export, download capture | Available | Not available |
| Needs someone at the keyboard | No | Yes β Chrome shows a blocking "Allow remote debugging?" prompt |
| Blast radius of a bad instruction | Confined to a throwaway profile | Any site your real session can reach |
Use the managed profile unless you have a concrete reason not to. The attached-session mode exists for cases where re-authenticating is genuinely impractical, and it should be understood as handing the agent your signed-in browser rather than as a convenience setting.
Getting it running and confirming it actually is
The browser runs as a control service on loopback inside the gateway, driving a Chromium-family browser β Chrome, Brave, Edge or Chromium itself. Start with a visible window; headless is a good production setting and a bad first-run setting, because a failure and a success look identical.
{
browser: {
enabled: true,
headless: false,
defaultProfile: "openclaw",
},
}Watching the browser move is the fastest way to tell the difference between the agent choosing not to act and the browser service failing to start. Switch `headless` on once you trust it.
openclaw config patch --file ./browser.json5 openclaw gateway restart
The control service starts with the gateway. Config changes to the browser block do not take effect until it restarts, which accounts for a fair share of "I changed it and nothing happened".
# Then ask for something that requires a real page load, e.g. # "open example.com and tell me the heading" # # Watch the window. If nothing opens, the service did not start β # check the gateway log before changing any other setting.
Ask for something that cannot be answered from the model's own knowledge. A question it can answer without browsing will be answered without browsing, and you will learn nothing about whether the tool works.
Narrowing what it is allowed to do
Two settings do most of the useful hardening. Neither is on by default, because both trade capability for safety and the right balance depends on what you point the agent at.
{
browser: {
evaluateEnabled: false,
ssrfPolicy: "strict",
},
}`evaluateEnabled` permits the agent to run arbitrary JS in the page. That is genuinely useful for scraping awkward sites and it is also the widest capability in the browser tool. Turn it off and see whether anything you actually do breaks. `ssrfPolicy` restricts navigation to trusted hosts, which matters most when page content can influence where the agent goes next.
{
browser: {
profiles: {
work: { cdpPort: 9222 },
},
},
}A named profile with its own `cdpPort` at least confines the attachment to a browser instance you launched deliberately, rather than whatever Chrome window happens to be open.
Things that bite people with browser automation
- βPage content is untrusted input. A page can contain text addressed to the agent, and an agent that browses and then acts is one that can be instructed by a website.
- βAn attached session means the agent is a logged-in you. Anything your browser can do without re-authenticating, it can do.
- βHeadless is not more secure, only less visible. Use it once behaviour is verified, not while you are still finding out what the agent does.
- βSites that break under automation usually break silently β the page loads, the selector matches nothing, and the agent reports what it saw rather than that it failed.