跳转至

浏览器自动化（CDP）

推荐验证路径

在尝试复杂多步流程前，先做三件事：

  1. 运行 loopforge doctor
  2. 确认浏览器检查项正常
  3. 先跑一个简单的 navigate/read/screenshot 任务

当 web_fetch 不够用（JS 渲染页面、多步交互、表单填写、需要截图留证）时，使用 browser_* 工具更可靠。

更多可复制粘贴的配方见：浏览器案例。

默认后端：CDP（无需 Python）

LoopForge 默认会启动本机的 Chromium 系浏览器（Chrome / Chromium / Edge），并通过 Chrome DevTools Protocol（CDP） 进行自动化控制。

前置条件

  • 安装任意 Chromium 系浏览器（Chrome/Chromium/Edge）。
  • 如果 LoopForge 找不到可执行文件，可以设置 LOOPFORGE_BROWSER_CHROME_PATH 指向浏览器可执行文件路径。

远程 CDP（可选）

如果你已经有一个带远程调试端口的浏览器实例（或你在 Docker 里启动了一个），可以让 LoopForge 直接连接：

1
export LOOPFORGE_BROWSER_CDP_HTTP="http://127.0.0.1:9222"

默认情况下，LoopForge 只允许连接 loopback 的 CDP endpoint。若要连接非 loopback 的 CDP URL，你必须显式开启：

1
export LOOPFORGE_BROWSER_CDP_ALLOW_REMOTE=1

如果你想直接用 Docker 跑一个”带 GUI + noVNC 观察界面”的 Chromium 沙盒（CDP 暴露在 127.0.0.1:9222），见：百度天气。

Headless / 有界面

LoopForge 默认以 headless 模式启动浏览器。

如果你想看到浏览器窗口（本地调试 / 演示），在第一次 browser_navigate 时设置 headless=false：

1
{ "url": "https://www.baidu.com", "headless": false }

你也可以设置 LOOPFORGE_BROWSER_HEADLESS=0，让未显式传入 headless 时默认使用有界面模式。

可选后端：Playwright bridge（legacy）

如果你更习惯 Playwright（或你的环境 CDP 不方便），可以切换后端：

1
export LOOPFORGE_BROWSER_BACKEND=playwright

然后安装 Playwright（Python）：

1
2
python3 -m pip install playwright
python3 -m playwright install chromium

如果你的 Python 可执行文件不是 python3，可以通过环境变量 LOOPFORGE_BROWSER_PYTHON 指定（例如 python）。

工具集

  • browser_navigate：打开 URL（默认带 SSRF 防护）
  • browser_back：回退历史
  • browser_scroll：滚动页面
  • browser_click：按 CSS selector 点击（会做尽力的可见文本 fallback）
  • browser_type：填写输入框
  • browser_press_key：按键（例如用 Enter 提交表单）
  • browser_wait：等待 selector（兼容工具）
  • browser_wait_for：等待 selector/text 出现
  • browser_read_page：返回 {title,url,content}（content 会被截断）
  • browser_run_js：执行 JS 表达式并返回结果
  • browser_screenshot：把 PNG 写入 workspace 相对路径
  • browser_close：关闭 session（可重复调用）

推荐循环

  1. browser_navigate 打开入口页面
  2. browser_read_page 确认状态
  3. 每次只做一个小动作：browser_click 或 browser_type
  4. 需要提交表单时，用 browser_press_key 按 Enter。
  5. 如果页面是异步更新，用 browser_wait_for（selector/text）等待新状态出现
  6. 再次 browser_read_page 确认页面确实变化
  7. 直到完成，最后 browser_screenshot 留证并 browser_close

Selector 小技巧

尽量使用稳定属性，而不是容易变化的文案文本：

  • #id
  • [name="q"]
  • [data-testid="submit"]
  • button[type="submit"]

如果 CSS selector 失败，browser_click 会尝试 尽力的可见文本 fallback。尽量写得具体，避免“OK / 确定”这种歧义文本导致点错。

Prompt 模板（可直接复制）

1
2
3
4
5
6
7
你可以使用 LoopForge 的 browser 工具（browser_navigate/back/scroll/click/type/press_key/wait/wait_for/read_page/run_js/screenshot/close）。

规则：
- navigate/click/type/press_key 之后尽快 browser_read_page；如果页面异步更新，先 browser_wait_for 再 read_page。
- 动作尽量少且可回滚。selector 失败时先读页面内容，再调整 selector。
- 最后把截图保存到 .loopforge/browser/<topic>.png。
- 未经用户明确确认，不要输入账号密码，也不要进行任何付费/下单操作。

示例运行：

1
loopforge agent run --workspace . --prompt "使用 browser 工具打开 https://example.com，读取页面内容，把简短总结写到 notes/example.md，并把截图保存到 .loopforge/browser/example.png。"

安全说明

  • browser_navigate 默认拒绝 loopback/private 目标；只有本地/私网测试才建议显式开启 allow_private=true。
  • browser_read_page 与 browser_screenshot 也会做同样的 loopback/private 防护（除非你开启了 allow_private）。
  • Browser 工具只允许 http(s) URL（file: / data: / chrome: 等 scheme 会被拦截）。
  • browser_screenshot 只允许写到 workspace 相对路径（不允许绝对路径、不允许 ..、不允许通过 symlink 逃逸）。

故障排查

  • 报错提示找不到 Chrome/Chromium：安装浏览器或设置 LOOPFORGE_BROWSER_CHROME_PATH。
  • 如果在 Docker 里提示 sandbox 相关问题：设置 LOOPFORGE_BROWSER_NO_SANDBOX=1（仅限可信 sandbox 环境）。
  • 报错提示 Playwright 缺失：设置 LOOPFORGE_BROWSER_BACKEND=playwright 并安装 Playwright。
  • 报错提示找不到 python3（Playwright 后端）：设置 LOOPFORGE_BROWSER_PYTHON=python。
  • 看不到浏览器窗口：默认是 headless；用 headless=false（或设置 LOOPFORGE_BROWSER_HEADLESS=0）。
  • 报错提示 session 未启动：先调用 browser_navigate。