OpenClaw 浏览器配置完全指南

从零开始配置 Managed Browser，让 AI Agent 自主打开网页、截图、点击和输入。

核心概念：两种浏览器模式
OpenClaw 支持两种浏览器控制模式。选错模式是新手遇到的第一个坑——理解它们的区别至关重要。

🟢 Managed Browser（托管浏览器）- 推荐
✅ 完全独立隔离的 Chromium 实例
✅ Agent 专用，不影响个人浏览器
✅ 支持无头模式 / VPS / Docker
✅ 启动即用，无需安装扩展
❌ 需要在 managed browser 中重新登录网站

🔵 Extension Relay（扩展中继）
✅ 可复用你已登录的网站
✅ 用 Chrome 扩展桥接现有标签页
❌ 需要安装扩展并手动附加 Tab
❌ 可能访问你的个人数据
❌ macOS 上可能不稳定

Managed Browser 架构流程
OpenClaw Agent → Gateway (localhost) → Managed Chromium → 目标网页
常见报错与原因分析
直接运行 openclaw browser start 时，你很可能遇到以下报错：

Error: Error: Chrome extension relay is running, but no tab is connected.
Click the OpenClaw Chrome extension icon on a tab to attach it (profile "chrome").

🔴 错误原因
OpenClaw 的默认 profile 是 chrome（Extension Relay 模式）。它期望你已安装 Chrome 扩展并点击附加了一个标签页——但你并没有这样做。

💡 根本原因
在 OpenClaw 内部，ensureDefaultChromeExtensionProfile() 函数会自动创建一个 driver: "extension" 的 chrome profile。即使你想用 managed browser，ensureBrowserAvailable() 也会检查所有 profile 的状态，导致 extension relay 报错。

解决方案很简单：将默认 profile 切换为 openclaw（Managed Browser 模式），详见下一节。

配置 Managed Browser（推荐方案）
步骤 1：编辑配置文件
打开或创建 ~/.openclaw/openclaw.json，写入以下内容：

{
browser: {
enabled: true,
defaultProfile: "openclaw"
// 可选：手动指定浏览器路径（通常自动检测即可）
// executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
}

⚠️ 关键设置：defaultProfile: "openclaw" 是核心配置项。设置后，所有未指定 profile 的浏览器命令都会使用 Managed Browser，不再走 Extension Relay。

步骤 2：安装 Playwright（推荐）
高级功能（点击 / 输入 / AI 快照 / PDF 导出）依赖 Playwright。如果未安装，这些功能会返回 501 错误。

npx playwright install chromium

步骤 3：（可选）安装 agent-browser
Vercel Labs 的 agent-browser 返回紧凑的元素引用，而非原始 DOM 树，可减少 60-93% 的 token 消耗。

npm install -g agent-browser

步骤 4：重启 Gateway 并启动浏览器

# 重启 gateway 使配置生效
openclaw gateway restart

# 启动 managed browser
openclaw browser start --profile openclaw

✅ 预期结果：一个带有橙色主题的独立 Chromium 窗口将弹出。这是 Agent 专用的浏览器，它的用户数据目录与你个人浏览器完全隔离。

步骤 5：验证浏览器正常运行

# 打开一个网页
openclaw browser open https://example.com

# 获取页面快照
openclaw browser snapshot

# 截图
openclaw browser screenshot

步骤 6：（可选）手动登录需要的网站
在弹出的 managed browser 窗口中，手动登录你需要 Agent 访问的网站（如 GitHub 、Gmail 等）。登录态会持久保存在 ~/.openclaw/browser-data/ 中。

Extension Relay 模式（可选）
如果你希望 Agent 复用你已登录的网站（不想重新登录），可以使用 Extension Relay 模式。

配置步骤
安装 OpenClaw Browser Relay Chrome 扩展
在需要 Agent 控制的标签页上，点击扩展图标来附加
创建自定义 extension profile：

openclaw browser create-profile \
--name my-chrome \
--driver extension \
--cdp-url http://127.0.0.1:18792 \
--color "#00AA00"

⚠️ 注意：Extension Relay 不会自动附加标签页。你必须手动点击扩展图标来激活。否则就会出现本文开头的那个报错。

常用 CLI 命令速查

命令说明
openclaw browser start 启动浏览器
openclaw browser open <url> 打开指定网页
openclaw browser snapshot 获取页面 ARIA 快照（含交互元素引用）
openclaw browser snapshot --interactive --compact 仅显示可交互元素，紧凑格式
openclaw browser click e12 点击引用编号为 e12 的元素
openclaw browser type 1 "Hello" 在第 1 个输入框中输入文字
openclaw browser screenshot 截取当前页面
openclaw browser screenshot --full-page 全页面截图
openclaw browser screenshot --ref 12 截取特定元素