OpenClaw 可以运行一个专属的 Agent 浏览器，与你的日常浏览器完全隔离。Agent 通过这个安全通道打开标签页、阅读页面、点击和输入内容。
两种核心模式
| Profile | 说明 |
|---|---|
openclaw | 托管独立浏览器（无需扩展） |
chrome | 通过 Chrome 扩展中继控制你现有的 Chrome 标签页 |
快速开始
bash
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot如果看到「Browser disabled」，在配置中启用它并重启 Gateway：
json
{
"browser": {
"enabled": true,
"defaultProfile": "openclaw"
}
}完整配置示例
json
{
"browser": {
"enabled": true,
"defaultProfile": "chrome",
"color": "#FF4500",
"headless": false,
"executablePath": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
"profiles": {
"openclaw": { "cdpPort": 18800, "color": "#FF4500" },
"work": { "cdpPort": 18801, "color": "#0066CC" },
"remote": { "cdpUrl": "http://10.0.0.42:9222", "color": "#00AA00" }
},
"ssrfPolicy": {
"dangerouslyAllowPrivateNetwork": true
}
}
}使用 Brave / Chrome / Edge
如果系统默认浏览器是基于 Chromium 的，OpenClaw 会自动检测。也可以手动指定：
bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"不同平台路径：
json
{
"browser": {
"executablePath": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
}
}Chrome 扩展中继（控制现有 Chrome 标签页）
安装步骤：
bash
# 1. 安装扩展
openclaw browser extension install
# 2. 在 Chrome 中加载
# chrome://extensions → 启用「开发者模式」→「加载已解压的扩展」
# 选择 openclaw browser extension path 输出的目录
# 3. 固定扩展，点击想控制的标签页上的图标（徽章显示 ON）使用：
bash
# CLI
openclaw browser --browser-profile chrome tabs
# Agent 工具使用 profile="chrome"注意：如果 Agent 在沙箱中运行，需设置
agents.defaults.sandbox.browser.allowHostControl: true并在工具调用时传target="host"。
远程 CDP 配置
Browserless（托管 Chromium 服务）
json
{
"browser": {
"enabled": true,
"defaultProfile": "browserless",
"remoteCdpTimeoutMs": 2000,
"profiles": {
"browserless": {
"cdpUrl": "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
"color": "#00AA00"
}
}
}
}Browserbase（支持 CAPTCHA 破解和住宅 IP）
json
{
"browser": {
"enabled": true,
"defaultProfile": "browserbase",
"remoteCdpTimeoutMs": 3000,
"remoteCdpHandshakeTimeoutMs": 5000,
"profiles": {
"browserbase": {
"cdpUrl": "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
"color": "#F97316"
}
}
}
}常用 CLI 命令
基础操作
bash
openclaw browser status
openclaw browser start
openclaw browser open https://example.com
openclaw browser tabs
openclaw browser tab new
openclaw browser tab close 2页面检查
bash
# AI 快照（含数字 ref）
openclaw browser snapshot
# 交互元素列表（含 ref=e12 格式）
openclaw browser snapshot --interactive
# 截图
openclaw browser screenshot
openclaw browser screenshot --full-page
# 控制台错误
openclaw browser console --level error
openclaw browser errors --clear
# PDF
openclaw browser pdf页面操作
bash
openclaw browser navigate https://example.com
openclaw browser click 12 # 用数字 ref
openclaw browser click e12 # 用角色 ref
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser dialog --accept等待
bash
# 等待文本出现
openclaw browser wait --text "Done"
# 等待 URL 变化
openclaw browser wait --url "**/dash"
# 等待加载完成
openclaw browser wait --load networkidle
# 等待 JS 条件
openclaw browser wait --fn "window.ready===true"
# 组合等待
openclaw browser wait "#main" --url "**/dash" --load networkidle --timeout-ms 15000状态管理
bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set geo 39.9042 116.4074 --origin "https://example.com"
openclaw browser set timezone Asia/Shanghai
openclaw browser set device "iPhone 14"两种快照和 Ref 格式
| 快照类型 | 命令 | Ref 格式 | 操作示例 |
|---|---|---|---|
| AI 快照（默认） | snapshot | 数字 12 | click 12 |
| 角色快照 | snapshot --interactive | e12 | click e12 |
重要：Ref 在页面导航后失效，每次导航后需重新获取快照。
调试技巧
操作失败时（「not visible」「strict mode violation」「covered」）：
openclaw browser snapshot --interactive- 用
click <ref>/type <ref>重试 - 还是失败：
openclaw browser highlight <ref>看 Playwright 定位到哪里 - 页面异常：检查
openclaw browser errors --clear和openclaw browser requests --filter api - 深度调试：
openclaw browser trace start→ 复现问题 →openclaw browser trace stop
WSL2 跨命名空间配置
json
{
"browser": {
"enabled": true,
"relayBindHost": "0.0.0.0",
"defaultProfile": "chrome"
}
}安全配置
严格模式（仅允许特定域名）：
json
{
"browser": {
"ssrfPolicy": {
"dangerouslyAllowPrivateNetwork": false,
"hostnameAllowlist": ["*.example.com", "example.com"]
}
}
}原文：Browser - OpenClaw | 来源：OpenClaw 官方文档