Browser Harness：592行Python让AI直接操控浏览器

你有没有遇到过这样的情况？

每天上班第一件事，打开十几个网页：看看GitHub的PR有没有人review、查查Jira上的需求更新、去内网系统提个审批、再刷刷Reddit有没有新的技术讨论……这些操作重复了无数次，明明每一步都是点击、输入、等待，但就是没有好办法让AI帮你做。你试过Selenium，写脚本太麻烦；试过Playwright，还得装一堆依赖；更别提让Claude Code这种AI编程Agent直接帮你操作浏览器了——它们连看到你屏幕上打开的网页都做不到。

Browser Harness 就是来解决这个问题的。它是最简单、最轻量的自愈式浏览器控制工具，让AI编程Agent（Claude Code、Codex等）直接控制你的Chrome浏览器完成任何任务。一周内拿下5900+星，全Python实现，总共只有592行代码。

一、Browser Harness 是什么？

一句话：通过Chrome DevTools Protocol直接连接你的浏览器，让AI Agent像人一样操作网页。

它不是Selenium那种重型框架，不是Playwright那种完整测试工具，而是一个极简的"桥梁"——一端是你的Chrome浏览器（通过CDP WebSocket连接），另一端是你的AI编程Agent（Claude Code、Codex等）。Agent写Python代码，Browser Harness执行，浏览器就动起来了。

最创新的设计是自愈机制：当Agent发现缺少某个操作函数时，它会自己写代码补充到helpers.py里，下次就能直接用了。这意味着你的浏览器控制能力会越用越强，而不是被框架写死的API限制住。

二、核心功能一览

三、安装步骤（手把手教程）

前提条件

• Python >= 3.11
• Chrome浏览器（必须开启远程调试端口）
• 推荐使用 uv 管理Python工具

第1步：克隆仓库

git clone https://github.com/browser-use/browser-harness
cd browser-harness

第2步：全局安装

推荐使用 uv tool install 安装，这样可以全局使用 browser-harness 命令：

# 可编辑模式安装（推荐，方便后续修改helpers.py）
uv tool install -e .

如果你没有 uv，也可以用 pip：

pip install -e .

第3步：验证安装

command -v browser-harness

如果输出类似 /home/yourname/.local/bin/browser-harness，说明安装成功。

第4步：连接Chrome浏览器

这是最关键的一步！你需要让Chrome开启远程调试端口：

Mac系统：

# 方法1：用browser-harness自带的setup命令
browser-harness --setup

# 方法2：手动启动Chrome（如果--setup不好使）
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Windows系统：

# 方法1：使用setup命令
browser-harness --setup

# 方法2：手动启动（以PowerShell运行）
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Linux系统：

# 方法1
browser-harness --setup

# 方法2
google-chrome --remote-debugging-port=9222

⚠️ 重要：如果你已经有Chrome在运行，需要先关掉所有Chrome窗口，再用上面的命令启动。否则--remote-debugging-port参数不会生效。browser-harness --setup命令会自动帮你处理这个问题。

第5步：运行诊断（确认一切正常）

browser-harness --doctor

这个命令会自动检查：

• 安装是否正确
• daemon进程是否在运行
• Chrome浏览器是否已连接
• CDP WebSocket连接是否正常

如果全部通过，你就可以开始使用了！

四、使用方法（从简单到进阶）

用法1：最简单的命令行用法

browser-harness 接受标准输入的Python代码，直接执行：

# 获取当前页面的基本信息
browser-harness <<'PY'
print(page_info())
PY

这会输出当前浏览器中活动标签页的标题、URL、页面摘要等信息。

# 打开新标签页
browser-harness <<'PY'
new_tab("https://docs.browser-use.com")
wait_for_load()
print(page_info())
PY

# 截图保存
browser-harness <<'PY'
screenshot("/tmp/page.png")
PY

用法2：配合Claude Code使用

这是Browser Harness最核心的使用场景——让Claude Code直接操控你的浏览器。

只需要在Claude Code中粘贴这段prompt：

Set up https://github.com/browser-use/browser-harness for me.
Read `install.md` first to install and connect this repo to my real browser.

Claude Code会自动：

1. 读取install.md文档
2. 安装browser-harness
3. 连接你的Chrome浏览器
4. 读取SKILL.md了解可用技能
5. 之后你就可以让它帮你操作浏览器了

你也可以在 ~/.claude/CLAUDE.md 中添加一行，让所有会话都能使用browser-harness：

@~/src/browser-harness/SKILL.md

这样Claude Code在每次对话时都会自动加载browser-harness的技能文档。

用法3：配合Codex使用

对于OpenAI的Codex Agent，可以通过注册全局skill的方式集成：

# 创建skill目录并链接SKILL.md
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness"
ln -sf "$PWD/SKILL.md" "${CODEX_HOME:-$HOME/.codex}/skills/browser-harness/SKILL.md"

之后Codex就能自动识别browser-harness的技能，帮你操作浏览器了。

用法4：使用远程浏览器

没有本地Chrome？或者在服务器上运行？Browser Harness支持远程浏览器：

browser-harness <<'PY'
# 启动远程浏览器（免费Tier支持3个并发）
start_remote_daemon("work")
new_tab("https://example.com")
wait_for_load()
print(page_info())
PY

远程浏览器自带代理和验证码识别功能，适合做数据采集等场景。

五、自愈机制：最核心的创新

这是Browser Harness最让人兴奋的设计。用一个实际场景来说明：

场景：Agent需要上传文件

 ● agent: 用户要我上传一个文件
 │
 ● 检查helpers.py → upload_file() 函数不存在
 │
 ● agent 自己动手，写代码！
 │  helpers.py 从 192 行变成 199 行
 │  新增了 upload_file() 函数
 │
 ✓ 文件上传成功！

这个过程意味着什么？

传统的浏览器自动化框架（Selenium、Playwright等）把所有操作函数都写死了。如果你需要一个新的操作，你得自己查文档、写代码、调试。

但Browser Harness走了一条完全不同的路：

1. Agent想干什么，就检查helpers.py里有没有对应的函数
2. 如果没有，Agent自己写一个，保存到helpers.py
3. 下次再遇到同样的操作，直接调用就行

你的浏览器控制能力只会越来越强。 使用一周后，你的helpers.py里会积累出大量定制化的操作函数，而且每一行都是Agent根据你的实际需求写的——比任何通用框架都更贴合你的场景。

这就像一个实习生，第一天什么都不会，但每次遇到不会的事就学会，一周后已经变成了熟手。

六、60+个Domain Skills：开箱即用的网站操作

Browser Harness内置了60多个网站的预设操作技能，以下是部分示例：

加上17个Interaction Skills（处理cookies、iframe、文件上传、Shadow DOM、拖拽、对话框等），基本上你日常会用到的浏览器操作，都有预设方案。

七、实际场景举例

八、跟同类工具对比

核心区别：Browser Harness不是一个通用浏览器自动化框架，它是专为AI Agent设计的浏览器控制桥梁。它的用户不是人类程序员，而是Claude Code、Codex这类AI编程Agent。所以它能做到极致精简——592行就够了，因为Agent不需要复杂的API包装，它们会自己写代码。

九、诊断和更新命令速查

遇到问题时，先跑 --doctor，80%的问题都能定位。

十、小结

Browser Harness用592行Python实现了一个极为优雅的设计：让AI Agent成为浏览器的真正主人。自愈式机制让Agent的能力越用越强，60+个预设Domain Skills让常用网站开箱即用，而极简的CDP直连设计让一切快到几乎没有延迟。如果你正在用Claude Code或Codex，又想让它们帮你操作浏览器——这就是你需要的工具。

🔗 项目地址：https://github.com/browser-use/browser-harness

⭐ 5900+ Stars | MIT License | Python 100%