浏览器自动化

本指南介绍如何在 ZeroClaw 中设置浏览器自动化功能，包括无头自动化和通过 VNC 的 GUI 访问。

概述

ZeroClaw 支持多种浏览器访问方式：

方法	用例	要求
agent-browser CLI	无头自动化，AI 代理	npm、Chrome
VNC + noVNC	GUI 访问、调试	Xvfb、x11vnc、noVNC
Chrome 远程桌面	通过 Google 实现远程 GUI	XFCE，Google 账户

快速入门：无头自动化

1. 安装 agent-browser

Linux

# 安装 CLI
npm install -g agent-browser

# 下载 Chrome for Testing（包含系统依赖项）
agent-browser install --with-deps

macOS / Windows

# 安装 CLI
npm install -g agent-browser

# 下载 Chrome for Testing
agent-browser install

2. 验证 ZeroClaw 配置

浏览器工具默认启用，并设置 allowed_domains = ["*"]。您可以通过 zeroclaw config set 限制域名或禁用该工具：

sh

zeroclaw config set browser.allowed_domains '["example.com", "docs.example.com"]'
zeroclaw config set browser.enabled false

zerocode

在 Config 窗格中，Browser 下方。

URL 方案策略。 browser_open 同时接受 http:// 和 https:// URL（与 web_fetch、http_request 以及 browser 工具一致，它们已经接受明文 HTTP）。本地/私有主机阻止规则和 allowed_domains 白名单对 http:// 的适用方式与 https:// 完全相同。由于 allowed_domains 默认是 ["*"]，因此随附的默认配置允许通过明文 HTTP 打开任何公共主机。为减少明文 HTTP 暴露，请用你信任的具体公共主机替换通配白名单。注意，这不会强制 HTTPS 适用于这些主机：白名单限制的是来源，而不是协议；对允许主机的仅 HTTPS 行为，需要该主机自身重定向/拒绝明文 HTTP（HSTS、服务端 308），或采用未来支持按协议感知的浏览器策略。

对于 agent_browser 后端，设置 browser.headed = true 可在有界面模式下启动浏览器，用于调试或首次登录设置；或设置 browser.headed = false 以强制使用无界面模式。当 browser.headed 未设置时，Zeroclaw 会保留继承的 AGENT_BROWSER_HEADED 环境行为。rust-native 后端仍使用 browser.native_headless。

有关所有浏览器字段和默认值的详细信息，请参阅配置参考。

3. 测试

sh

echo 打开 https://example.com 并告诉我它显示的内容 | zeroclaw agent -a assistant

VNC 设置（GUI 访问）

用于调试或需要浏览器可视化访问时：

安装依赖

Debian/Ubuntu

apt-get install -y xvfb x11vnc fluxbox novnc websockify

# 可选：Chrome 远程桌面的桌面环境
apt-get install -y xfce4 xfce4-goodies

启动 VNC 服务器

bash

```bash
#!/bin/bash
```
# Start virtual display with VNC access

DISPLAY_NUM=99
VNC_PORT=5900
NOVNC_PORT=6080
RESOLUTION=1920x1080x24

# 启动 Xvfb
Xvfb :$DISPLAY_NUM -screen 0 $RESOLUTION -ac &
sleep 1

# 启动窗口管理器
fluxbox -display :$DISPLAY_NUM &
sleep 1

# 启动 x11vnc
x11vnc -display :$DISPLAY_NUM -rfbport $VNC_PORT -forever -shared -nopw -bg
sleep 1

# 启动 noVNC（基于 Web 的 VNC）
websockify --web=/usr/share/novnc $NOVNC_PORT localhost:$VNC_PORT &

echo VNC 可用位置：
echo VNC 客户端：localhost:$VNC_PORT
echo Web 浏览器：http://localhost:$NOVNC_PORT/vnc.html

VNC 访问

VNC 客户端：连接到 localhost:5900
Web 浏览器：打开 http://localhost:6080/vnc.html

在 VNC 显示上启动浏览器

sh

DISPLAY=:99 google-chrome --no-sandbox https://example.com &

Chrome 远程桌面

安装

sh

# 下载和安装
wget https://dl.google.com/linux/direct/chrome-remote-desktop_current_amd64.deb
apt-get install -y ./chrome-remote-desktop_current_amd64.deb

# 配置会话
echo "xfce4-session" > ~/.chrome-remote-desktop-session
chmod +x ~/.chrome-remote-desktop-session

设置

访问 https://remotedesktop.google.com/headless
复制“Debian Linux”安装命令
在您的服务器上运行它
启动服务：systemctl --user start chrome-remote-desktop

远程访问

从任何设备访问 https://remotedesktop.google.com/access。

测试

CLI 测试

sh

# 基本打开和关闭
agent-browser open https://example.com
agent-browser get title
agent-browser close

# 带有引用的快照
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close

# 截图
agent-browser open https://example.com
agent-browser screenshot /tmp/test.png
agent-browser close

ZeroClaw 集成测试

sh

# 内容提取
echo 打开 https://example.com 并对其进行总结 | zeroclaw agent -a assistant

# 导航
echo 前往 https://github.com/trending 并列出前 3 个仓库 | zeroclaw agent -a assistant

# 表单交互
echo 前往维基百科，搜索“Rust 编程语言”，并总结 | zeroclaw agent -a assistant

故障排除

未找到元素

页面可能尚未完全加载。添加一个等待：

sh

agent-browser open https://slow-site.com
agent-browser wait --load networkidle
agent-browser snapshot -i

首先处理 Cookie 同意设置：

sh

agent-browser open https://site-with-cookies.com
agent-browser snapshot -i
agent-browser click @accept_cookies  # 点击接受按钮
agent-browser snapshot -i  # 现在获取实际内容

Docker 沙箱网络限制

如果 web_fetch 在 Docker 沙箱中失败，请改用 agent-browser：

sh

# 不要使用 web_fetch，改用：
agent-browser open https://example.com
agent-browser get text body

安全说明

agent-browser 在无头模式下运行 Chrome，并启用沙箱机制
对于敏感站点，请使用 --session-name 来持久化认证状态
--allowed-domains 配置项用于限制导航到特定的域名。
VNC 端口（5900、6080）应位于防火墙或 Tailscale 之后

ZeroClaw Docs