browser-harness 实战：让 LLM 操控浏览器实现自修复自动化

browser-harness 实战：让 LLM 操控浏览器实现自修复自动化

每天定时去三个平台抓取公开数据汇总到表格——上个月接了这个需求。一开始用 Selenium 写了一套脚本，两周后某个平台页面结构微调，脚本当场罢工。定位、修改、调试，折腾了两小时。

做过浏览器自动化的同学都经历过这种痛：页面一有变动，脚本就报废。

如果有一种方案，让大语言模型直接操控真实浏览器，遇到搞不定的操作时自己能写 helper 函数补足能力，下次再遇到类似场景自动就会用——这听起来靠谱多了。

这篇教程带你体验 browser-harness 这个 17K+ 星的开源项目。学完本篇，你能在自己的电脑上搭好整套环境，给 AI 下达自然语言指令（比如「帮我打开某网站、登录、找到最新 20 条视频并下载」），让它在真实浏览器里一步步完成任务。

前置条件

动手之前，确认满足以下几点：

• Python 3.12：项目推荐版本，建议用 uv 或 venv 隔离环境。
• Chrome / Edge 浏览器：需要启动时开启远程调试端口。
• LLM 环境：可以是 Claude Code、Codex 等编程 agent，也可以是你能调用的 LLM API。
• 基础认知：了解 Chrome DevTools Protocol（CDP）的基本概念——browser-harness 就是通过一个可编辑的 CDP WebSocket 把 LLM 和浏览器连起来的。

推荐使用 uv 管理 Python 虚拟环境，速度比 pip 快不少，下面的步骤以它为例。

第一步：安装 browser-harness

用 uv 创建虚拟环境并安装最新稳定版：

## 如果还没装 uv，先装一个
curl -LsSf https://astral.sh/uv/install.sh | sh

## 创建并进入项目目录
mkdir browser-auto-demo && cd browser-auto-demo

## 用 uv 创建 Python 3.12 环境并安装 browser-harness
uv init -p 3.12
uv pip install -e git+https://github.com/browser-use/browser-harness.git

为什么用 -e 可编辑安装？ browser-harness 的源码会被 agent 读取和引用，可编辑安装保证 agent 能找到 src/browser_harness/ 下的模块，同时你也能查看官方 skill 文件来理解 agent 的工作流程。

第二步：开启 Chrome 远程调试

很多人第一次在这步踩坑——必须先让浏览器暴露 CDP 端口，agent 才能连进来。

关闭所有 Chrome 窗口后，用命令行启动：

## macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

## Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

启动后在浏览器地址栏输入 chrome://inspect/#remote-debugging，你会看到一个复选框，勾选它，允许 agent 通过 CDP 连接你的浏览器。

这步的本质是打开 Chrome 的 DevTools Protocol 远程调试端口，browser-harness 的 agent 就通过 ws://localhost:9222 的 WebSocket 来控制页面。不勾选的话，agent 连都连不进来。

第三步：给 Coding Agent 发 Setup Prompt

browser-harness 的巧妙之处在于你不需要自己写大量胶水代码——只需要把下面这段 prompt 粘贴到 Claude Code / Codex / 你的编程 agent 里：

Install or upgrade browser-harness to the latest stable version with uv using Python 3.12,
register the skill from `browser-harness skill`, and connect it to my browser.
Ask whether I want local browser recordings enabled;
default to no and preserve my existing preference on upgrades.
Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails.

这段 prompt 会让 agent 自动完成以下几件事：

1. 确认 browser-harness 已正确安装
2. 注册它的 SKILL（SKILL.md 定义了浏览器自动化工作流）
3. 建立到 Chrome 远程调试端口的连接
4. 确认你是否需要本地浏览器录制（默认不开启）

agent 跑完后，你就有了一个「活」的浏览器自动化环境。

实战：让 Agent 自动下载 X 平台最新视频

环境就绪，我们来做点真正有用的事。

给 agent 发一条任务指令：

打开我的 X 个人主页，找到最新的 20 条视频帖子，把它们全部下载到本地 videos/ 目录下。

这时你会观察到整个流程：

1. agent 打开浏览器，通过 CDP 操控页面导航到你的 X Profile。
2. agent 滚动页面找到视频帖子，检查每个帖子是否有视频。
3. 遇到没有现成下载方法的场景，agent 会在你的 workspace 里自动生成一个 helper——比如 agent_helpers.py，里面包含提取视频 URL、用 curl 或 requests 下载的逻辑。
4. 下次再遇到相同操作，agent 会直接调用这个 helper，不再重复走弯路。

这就是 browser-harness 的核心卖点——Self-healing（自修复）。agent 不会在遇到能力缺口时傻等，而是自己编写工具函数来补齐。你的 workspace 会随着任务越来越多而越来越强。

踩坑提醒

• Chrome 必须以调试模式启动：如果你平时习惯直接双击图标打开 Chrome，记得在调试模式下操作，否则 agent 连不到浏览器。
• 端口冲突：9222 是默认的远程调试端口，如果被其他进程占用，换一个端口并让 agent 知道即可。
• 登录态问题：agent 操控的是你的真实浏览器，所以你的登录态直接可用。如果要跑大规模自动化，建议用 Browser Use Cloud 提供的隔离浏览器，避免账号风险。
• Agent 写的 helper 存哪：默认在 agent-workspace/agent_helpers.py，建议定期审查和整理，别让它变成一团乱麻。

总结

今天完整走了一遍 browser-harness 的搭建和使用流程：

1. 用 uv 安装 browser-harness
2. 启动 Chrome 远程调试并授权 CDP 连接
3. 给 coding agent 发送 setup prompt 建立自动化环境
4. 下达自然语言任务指令，观察 agent 自修复式完成操作

与传统 Selenium / Playwright 方案相比，browser-harness 最大的区别在于：你告诉它目标，它自己拆解步骤、自己补能力、自己执行。 你从「写脚本的人」变成了「下指令的人」。

下一步可以试试让它做一些更复杂的流程化任务，比如「帮我填完表单 A 后截图，把截图里的数据录入到表单 B 并提交」。处理多步骤、跨页面的场景时，agent 特别管用。

动手试试吧，遇到问题随时交流。