# OpenClaw 浏览器控制完整教程

> 适用于新安装的 OpenClaw，解决浏览器无法使用的问题。

---

## 一、前置条件

### 1.1 必须安装 Chrome

OpenClaw 内置浏览器依赖 Google Chrome。

**Windows：**
```powershell
winget install Google.Chrome
```

**Mac：**
```bash
brew install --cask google-chrome
```

**验证：**
```powershell
# Windows
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
# 应返回 True

# Mac
ls "/Applications/Google Chrome.app"
```

### 1.2 安装浏览器相关 Skill（可选但推荐）

```bash
# AI 优化搜索（替代 web_search）
skillhub install tavily-search

# 复杂网页自动化
skillhub install autoglm-browser-agent
```

---

## 二、内置浏览器（默认，开箱即用）

OpenClaw 自带 `browser` 工具，**无需额外安装任何插件**，只要 Chrome 已安装就能用。

### 2.0 两种控制方式

OpenClaw 浏览器有两种控制方式：

| | 方式一：内置 `browser` 工具 | 方式二：HTTP API（18791） |
|--|---------------------------|--------------------------|
| 速度 | Gateway 忙时 timeout（3s） | <1s，稳定 |
| 使用 | `browser action=snapshot` | `curl / Invoke-RestMethod` |
| 适合 | 日常使用 | Gateway 负载高时、快速操作 |

**日常用方式一，timeout 或 Gateway 忙时切换方式二。**

### 2.1 方式一：内置 browser 工具

```
# 1. 启动浏览器
browser action=start

# 2. 打开网页（用 navigate 复用标签页，不要用 open）
browser action=navigate url="https://www.baidu.com"

# 3. 读取页面内容（用 snapshot，不要用截图）
browser action=snapshot refs=role

# 4. 点击元素（ref 从 snapshot 中获取，如 ref=e1）
browser action=act kind=click ref=e1

# 5. 输入文字
browser action=act kind=type ref=e5 text="搜索内容"

# 6. 关闭浏览器（操作完成后）
browser action=stop
```

### 2.2 方式二：HTTP API（Gateway 忙 / timeout 时用）

内置 browser 工具走 Gateway WebSocket，Gateway 忙时会 handshake timeout（3s 硬编码）。HTTP API 直连浏览器服务（18791 端口），响应 <1s，不受 Gateway 影响。

```powershell
# 获取认证 token（从 OpenClaw 配置中读取）
$config = Get-Content ~/.openclaw/openclaw.json | ConvertFrom-Json
$token = $config.auth.tokens[0]
$headers = @{ Authorization = "Bearer $token" }

# 打开网页
Invoke-RestMethod "http://localhost:18791/tabs/open" -Method Post -Headers $headers -ContentType "application/json" -Body '{"url":"https://www.baidu.com"}'

# 获取 AI 格式快照（结构化数据，可识别元素 ref）
$result = Invoke-RestMethod "http://localhost:18791/snapshot?format=interactive" -Headers $headers
# $result 中包含页面元素和对应的 ref

# 点击元素（用从快照中获取的 ref）
Invoke-RestMethod "http://localhost:18791/act" -Method Post -Headers $headers -ContentType "application/json" -Body '{"kind":"click","ref":"e5"}'

# 输入文字
Invoke-RestMethod "http://localhost:18791/act" -Method Post -Headers $headers -ContentType "application/json" -Body '{"kind":"type","ref":"e5","text":"搜索内容"}'

# 截图
Invoke-RestMethod "http://localhost:18791/screenshot" -Headers $headers -OutFile screenshot.png

# 查看标签页
Invoke-RestMethod "http://localhost:18791/tabs" -Headers $headers
```

**注意：**
- `/wait` 端点不可用，用 `Start-Sleep` 代替
- 每次操作后 ref 会变化，不要缓存旧 ref
- snapshot 中文字符在 PowerShell 可能乱码（GBK 编码），不影响 ref 识别

### 2.2 核心规则（必须遵守）

| 规则 | 说明 |
|------|------|
| ✅ 用 `snapshot` 读取页面 | 获取结构化数据（元素+文本），**不要用截图** |
| ✅ 用 `navigate` 打开网页 | 复用同一标签页，减少内存 |
| ✅ 用 `act kind=wait` 等待 | 不要用 evaluate 的 setTimeout |
| ❌ 禁止用 `screenshot` 读取内容 | 截图只是辅助，日常操作用 snapshot |
| ❌ 禁止用 `evaluate` 等 setTimeout | 超过 10 秒必定崩溃 |
| ❌ 禁止用 agent-browser skill | 和内置浏览器冲突 |
| ❌ 禁止用 `web_search` | Perplexity API 无额度，报 402 |

### 2.3 读取页面的正确方式

```
# ✅ 正确：获取结构化数据
browser action=snapshot refs=role

# 返回示例：
# heading "百度一下" [level=1]
# textbox "请输入搜索内容" [ref=e5]
# button "百度一下" [ref=e6]
# link "百度热搜" [ref=e10]

# ❌ 错误：截图
browser action=screenshot
# 截图是图片，AI 看不到里面的文字和可交互元素
```

### 2.4 常见问题排查

**问题：browser action=start 失败**
```
# 检查 Chrome 是否安装
where.exe chrome   # Windows
which chrome       # Mac

# 如果 Chrome 安装在非默认位置，设置环境变量
$env:CHROME_PATH="C:\你的路径\chrome.exe"
```

**问题：snapshot 返回空内容**
```
# 页面可能还在加载，等一下再 snapshot
Start-Sleep -Seconds 3
browser action=snapshot refs=role
```

**问题：tab not found / context destroyed**
```
# 标签页太多或浏览器崩溃了
browser action=tabs          # 查看标签数量
browser action=stop          # 关闭浏览器
browser action=start         # 重新启动
```

**问题：找不到元素（ref 无效）**
```
# 页面更新后 ref 会变，每次操作前重新获取 snapshot
browser action=snapshot refs=role
# 然后用新的 ref 操作
```

---

## 三、搜索的正确方式

### 3.1 首选：Tavily（如果已安装）

```bash
skillhub install tavily-search
```

安装后 AI 会自动使用，不需要手动调用。

### 3.2 备选：内置浏览器 + DuckDuckGo

```
browser action=start
browser action=navigate url="https://duckduckgo.com/?q=搜索关键词"
browser action=snapshot refs=role
# 从 snapshot 中读取搜索结果
```

### 3.3 备选：AutoGLM WebSearch（如果已安装）

```bash
skillhub install autoglm-websearch
```

### 3.4 禁止使用

```
❌ web_search — Perplexity API，无额度，必定报 402 错误
❌ web_fetch 抓搜索结果页 — JS 渲染的内容抓不到
```

---

## 四、反自动化网站（Boss直聘、小红书、抖音）

这些网站会检测 Playwright/CDP（内置浏览器用的），直接用会被封号。

### 4.1 用 DrissionPage

```powershell
pip install DrissionPage
```

```python
from DrissionPage import ChromiumPage
page = ChromiumPage()
page.get('https://www.zhipin.com')
# 自动绕过反检测
```

需要写 Python 脚本，通过 `exec` 工具执行。

### 4.2 用 AutoGLM Browser Agent

```bash
skillhub install autoglm-browser-agent
```

需要先安装 AutoGLM 客户端，Token 自动获取。

---

## 五、场景速查表

| 你想做什么 | 用什么 | 命令 |
|-----------|--------|------|
| 打开网页看内容 | 内置 browser | `browser action=navigate url="..."` → `snapshot` |
| 搜索信息 | Tavily 或 browser+DuckDuckGo | 见 3.1 / 3.2 |
| 点击按钮/链接 | 内置 browser | `snapshot` 获取 ref → `act kind=click ref=e1` |
| 填写表单 | 内置 browser | `act kind=type ref=e5 text="内容"` |
| 截图看效果 | 内置 browser | `browser action=screenshot`（仅看效果，不要用来读内容） |
| 操作反爬网站 | DrissionPage | 写 Python 脚本 |
| 复杂网页自动化 | AutoGLM | `skillhub install autoglm-browser-agent` |

---

## 六、完整示例：用百度搜索

```
# 1. 启动浏览器
browser action=start

# 2. 打开百度
browser action=navigate url="https://www.baidu.com"

# 3. 读取页面，找到搜索框
browser action=snapshot refs=role
# 返回：textbox "请输入搜索内容" [ref=e5]
#       button "百度一下" [ref=e6]

# 4. 在搜索框输入
browser action=act kind=fill ref=e5 text="OpenClaw AI"

# 5. 点击搜索按钮
browser action=act kind=click ref=e6

# 6. 等待结果加载
Start-Sleep -Seconds 2

# 7. 读取搜索结果（不是截图！）
browser action=snapshot refs=role
# 从返回的结构化数据中提取搜索结果

# 8. 点击某个结果
browser action=act kind=click ref=e25

# 9. 完成后关闭
browser action=stop
```

---

> 文档更新：2026-03-20
> 下载地址：https://www.wubug.cc/downloads/OpenClaw浏览器控制教程.txt