Note: macOS setup does NOT include VNC/noVNC. The user is expected to access the Mac via their own remote desktop solution (e.g. macOS Screen Sharing, Tailscale, or physical access). VNC takeover with noVNC links is only available on Linux.

Linux / Docker

# Install deps (once)
bash scripts/setup.sh

# Start browser + VNC environment
bash scripts/start.sh [password] [novnc_port] [cdp_port] [resolution]

start.sh outputs the noVNC URL, password, and CDP port. Safe to re-run.

OpenClaw Config

Setup scripts configure this automatically. Manual reference:

macOS:

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false,
    "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

Linux:

{
  "browser": {
    "enabled": true,
    "headless": false,
    "noSandbox": true,
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

Multi-Session Window Isolation

Multiple sessions share one Chrome (same cookies/logins) but each gets its own window.

Rules (MUST follow):

On session start — open your own tab, save the targetId:

browser action=open targetUrl="https://example.com" profile=openclaw
# Returns targetId — THIS IS YOURS, save it

ALL subsequent calls — always include your targetId:

browser action=snapshot profile=openclaw targetId="<your-targetId>"
browser action=navigate profile=openclaw targetId="<your-targetId>" targetUrl="..."
browser action=act profile=openclaw targetId="<your-targetId>" ...

On session end — close your tab:

browser action=close targetId="<your-targetId>"

NEVER operate without targetId — you'll land on another session's tab.
NEVER pick another session's tab from browser action=tabs.

Opening a new window (not tab) via CDP:

import json, asyncio, websockets, urllib.request

async def open_new_window(cdp_port, url):
    version = json.loads(urllib.request.urlopen(f"http://127.0.0.1:{cdp_port}/json/version").read())
    async with websockets.connect(version["webSocketDebuggerUrl"]) as ws:
        await ws.send(json.dumps({
            "id": 1, "method": "Target.createTarget",
            "params": {"url": url, "newWindow": True}
        }))
        resp = json.loads(await ws.recv())
        return resp["result"]["targetId"]

Architecture:

Chrome (one instance, one profile, shared cookies)
├── Window targetId=AAA → Session A
├── Window targetId=BBB → Session B
└── Window targetId=CCC → Session C

VNC Takeover (CRITICAL)

When hitting a CAPTCHA, login wall, or any blocker, send the user a noVNC link:

https://<IP>:<NOVNC_PORT>/vnc.html?password=<PASSWORD>&autoconnect=true&resize=scale

Constructing the link:

Linux/Docker (from start.sh output):

https://57.129.90.145:10150/vnc.html?password=e0GGP4xeMUL5ga&autoconnect=true&resize=scale

IP: server's public or Tailscale IP
Port + password: from start.sh output

macOS: VNC takeover is NOT available. The user must access the Mac directly (physical access, macOS Screen Sharing, or their own remote desktop solution).

Takeover flow:

Agent detects blocker (CAPTCHA, login, 2FA)
Agent sends noVNC link to user
User opens link → sees Chrome → solves the problem
User confirms done → agent continues

Anti-Detection

Headful Chrome — no HeadlessChrome in UA
--disable-blink-features=AutomationControlled — no navigator.webdriver=true

UA override via CDP if needed:

{"method": "Network.setUserAgentOverride", "params": {
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/131.0.0.0 Safari/537.36"
}}

Security

SSL/TLS on noVNC (self-signed cert)
Random 14-char password (Linux) or system auth (macOS)
CDP: localhost only, never exposed to network
Chrome Policy: file://, javascript:, data:text/html blocked; extensions blocked; DevTools disabled

Important: No Kiosk Mode

Do NOT use Chrome's --kiosk flag. It hides the tab bar and address bar, making multi-window unusable via VNC. Use --start-maximized instead.

anemone-browser

Anemone Browser — Managed Browser for OpenClaw Agents

Setup

macOS