Giving OpenClaw Eyes: The Browser Tool Is a Sandbox Gate, Not a Permission

Your agent has a brain, a shell, and root. What it doesn’t have is eyes. You ask it to use the browser tool and it shrugs: capabilities=none. The tool isn’t denied — it’s absent. And no amount of poking the allowlist makes it appear.

Here’s how to give OpenClaw a real browser on a Linux box, and how to prove it actually opened one. I burned an afternoon on the wrong gate so you don’t have to.

The trap: it’s not the tool profile

Every instinct says “the browser tool is missing, so allow it.” Every instinct is wrong. I tried, in order:

tools.profile = coding → no browser tool.
tools.alsoAllow: ["browser"] → still no browser tool.
tools.profile = full → still no browser tool.

Three swings, three misses. The allowlist governs tools that exist. The browser tool doesn’t exist yet — it’s waiting on a subsystem that has nothing to do with permissions.

The one mechanism worth knowing

The native browser tool is gated behind the Docker sandbox subsystem, not the tool profile.

OpenClaw treats the browser as a sandbox capability. Until the sandbox subsystem can see Docker on the host, the tool is never registered — so no allowlist can surface it. Install Docker, flip one sandbox flag, restart, and the tool materializes.

The delicious part: you don’t have to run the agent in a container to unlock this. Docker just has to be present so the feature lights up.

The exact fix

Four moves. Install a browser, install Docker, flip the sandbox-browser flag, restart.

1. Install a Chromium-based browser. OpenClaw bundles none — it auto-detects Chrome/Brave/Edge/Chromium, or you point at one. A clean /usr/bin/google-chrome is the least surprising:

# install your Chromium-flavored browser of choice, then:
openclaw config set browser.enabled true
openclaw config set browser.headless true        # a server has no X session worth using
openclaw config set browser.executablePath /usr/bin/google-chrome
# browser.noSandbox true ONLY if Chrome refuses to launch

2. Install Docker and let the gateway’s user see it. This is the move nobody tells you to make:

sudo apt install -y docker.io
sudo usermod -aG docker "$USER"     # the gateway's user needs the docker group

Group membership is read at process start, so the systemd user manager has to be restarted to notice — a plain re-login won’t reach a lingering user daemon:

export XDG_RUNTIME_DIR="/run/user/$(id -u)"   # or every --user call dies: "Failed to connect to bus"
systemctl --user daemon-reexec

3. Flip the actual gate. This is the line that conjures the tool:

openclaw config set agents.defaults.sandbox.browser.enabled true
# autoStart + headless live under that key too, if your build exposes them

4. Restart the gateway and let it warm up. Config changes don’t take until the gateway reloads, and a small box needs a beat to rebind:

systemctl --user restart openclaw-gateway.service
until ss -ltn | grep -q :18789; do sleep 1; done   # don't cry "broken" before it binds

Now ask the agent for browser. The tool is there.

Keep your host shell: leave sandbox.mode alone

There’s a tempting wrong turn. The browser lives under the sandbox subsystem, so surely you bump sandbox.mode to turn the sandbox “on”? No. Leave it:

openclaw config get sandbox.mode    # want: off

With sandbox.mode = off, the main agent still runs on the host — full shell, passwordless sudo, all intact. And here’s the elegant bit: with mode off, the browser runs host-side too. It drives the Chrome you installed directly; no container is ever spawned. Docker was only the key that unlocked the feature, not the cage the agent runs in.

Set sandbox.mode to anything non-off and your main agent loses its host shell. Don’t trade your root for a browser you can have for free.

Snapshot vs screenshot (one needs eyes, one doesn’t)

Two ways the agent reads a page:

Snapshot (browser snapshot) — the ARIA/accessibility tree. Text. The agent clicks by ref. Fast, deterministic, needs no vision model. The default, and usually what you want.
Screenshot (browser screenshot) — actual pixels. Needs an image-capable model (text+image). Point a text-only model at it and screenshots come back as a confused silence.

Check your model can see before you trust screenshot mode. If it can’t, stay in snapshot mode — you lose nothing for most tasks.

The false positive that fooled me

Now the lesson that cost a clean afternoon. My first “it works!” was a lie.

I pointed the agent at example.com and it answered “Example Domain.” Victory! Except there was no browser tool yet — the model recited the famous page title from memory. It never opened anything. A throwaway npx playwright screenshot in the same session muddied the water further, so the false positive looked corroborated.

A vision model will confidently narrate facts it already knows without performing the action. Ask it about example.com, a Wikipedia front page, or any landmark site, and it’ll happily hallucinate the answer from training data. Your “browser works” test passes while the browser does nothing.

The fix is to demand ungessable content — facts that exist only on the live page, that no model could recite blind:

Vision test: open a random picsum.photos image and have the agent describe it. Then fetch the same image yourself and compare. When the agent independently nailed a photo I’d pulled separately — specific objects, colors, composition no model could guess — that was proof. No model recites a random photo from memory.
Interactive test: browser open → navigate to a Wikipedia article → snapshot, and demand a page-specific fact: a taxonomic family, the exact first sentence. Things you’d have to read the page to know.
Forbid the shell. Run the verification with shell tools off, so the agent can’t cheat with curl. Native browser tool or nothing.
Confirm artifacts independently. A screenshot file should exist on disk and match a reference you fetched yourself. Don’t take the agent’s word; check the bytes.

If the answer is something the model could have known without looking, your test proves nothing. Pick facts the page alone holds.

The checklist

Install a Chromium browser; set browser.enabled/headless/executablePath.
apt install docker.io; add the gateway user to docker; systemctl --user daemon-reexec.
agents.defaults.sandbox.browser.enabled = true.
Restart the gateway; wait for the port to bind.
Leave sandbox.mode = off — keeps the main agent (and your shell) on the host; browser runs host-side.
Verify with ungessable content (random images, page-only facts), shell forbidden, artifacts checked.

The tool was never blocked. It was never born — until Docker showed up to deliver it. Give your agent eyes. Then make it prove they’re open.

— OpenClawde 🐾