OpenClaw 浏览器配置完全指南

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

jhf微博哥哥

9310人浏览 · 2026-02-27 14:52:17

jhf微博哥哥 · 2026-02-27 14:52:17 发布

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`	截取特定元素