openbrowser-ai

OpenBrowser

由代码驱动的 AI 浏览器自动化。

---

托管版本提供用于保存 Cookie 和计划任务的云端控制面板。加入候补名单，抢先体验：https://openbrowser.me ：

https://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b

自动抓取 Walmart 商品信息：

https://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094

OpenBrowserAI 自动预订航班：

https://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f

OpenBrowserAI 自动填写表单：

https://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7

使用 CodeAgent 和 CDP（Chrome DevTools Protocol）实现 AI 驱动的浏览器自动化

OpenBrowser 是一个用于智能浏览器自动化的框架。它将直接 CDP 通信与 CodeAgent 架构相结合：大模型在持久化命名空间中编写并执行 Python 代码，从而自主浏览网页、与网页交互并提取信息。

目录

• 文档
• 主要功能
• 安装
• 快速开始
• 配置
• 支持的大模型提供商
• Claude Code 插件
• Codex
• OpenCode
• OpenClaw
• MCP 服务
• 基准测试：Token 效率
• CLI 用法
• 项目结构
• 后端和前端部署
• 测试
• 研究：面向浏览器 Agent 的强化微调
• 参与贡献
• 许可证
• 联系方式

文档

完整文档：https://docs.openbrowser.me

主要功能

• CodeAgent 架构 - 大模型在类似 Jupyter 的持久化命名空间中编写 Python 代码，以实现浏览器自动化
• 原始 CDP 通信 - 直接使用 Chrome DevTools Protocol，实现最高程度的控制和速度
• 视觉支持 - 分析屏幕截图，以直观理解页面
• 15 家大模型提供商 - OpenAI、Anthropic、Google、Groq、AWS Bedrock、Azure、Ollama、DeepSeek、Cerebras、OpenRouter、OCI 等
• MCP 服务 - Model Context Protocol，适用于 Claude Desktop、Claude Code、Codex、OpenCode 和其他 AI 助手，并支持可重复使用的已保存登录会话
• CLI 守护进程 - 持久化浏览器守护进程，支持使用 -c 标志直接从 Bash 执行代码、保存登录状态，并在 10 分钟后自动关闭
• 工作流录制 - 录制、回放并将浏览器会话导出为 Jupyter 笔记本或 API 爬虫代码
• 视频录制 - 使用 ffmpeg 将浏览器会话录制为视频文件
• 云平台 - 全栈 Web UI，支持实时 VNC 流式传输、已保存登录信息（由 KMS 加密）、计划工作流（EventBridge + SQS）和电子邮件通知（SES）
• 插件系统 - Claude Code 插件，提供 7 种引导式技能（深度研究、网页抓取、表单填写、端到端测试、页面分析、无障碍审计、文件下载）

安装

快速安装（macOS / Linux）

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

快速安装（Windows PowerShell）

irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

自动检测 uv、pipx 或 pip，并安装 OpenBrowser。

安装到 ~/.local/bin，无需 sudo：

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local

Homebrew（macOS / Linux）

brew tap billy-enrizky/openbrowser
brew install openbrowser-ai

pip

pip install openbrowser-ai

uv（推荐）

uv pip install openbrowser-ai

uvx（无需安装）

无需安装即可直接运行——uvx 会自动下载并缓存软件包：

# MCP server mode
uvx openbrowser-ai --mcp

# CLI daemon mode
uvx openbrowser-ai -c "await navigate('https://example.com')"

pipx

pipx install openbrowser-ai

从源代码安装

git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser-ai
uv pip install -e ".[agent]"

可选依赖项

pip install openbrowser-ai[agent]      # LLM agent support (langgraph, langchain, litellm)
pip install openbrowser-ai[all]        # All LLM providers
pip install openbrowser-ai[anthropic]  # Anthropic Claude
pip install openbrowser-ai[groq]       # Groq
pip install openbrowser-ai[ollama]     # Ollama (local models)
pip install openbrowser-ai[aws]        # AWS Bedrock
pip install openbrowser-ai[azure]      # Azure OpenAI
pip install openbrowser-ai[video]      # Video recording support

无需单独安装浏览器。 OpenBrowser 会自动检测已安装的任何基于 Chromium 的浏览器（Chrome、Edge、Brave、Chromium），并直接使用。如果未找到浏览器且可用 uvx，则会在首次运行时自动安装 Chromium。若要预先手动安装（需要 uvx）：openbrowser-ai install

快速开始

基本用法

import asyncio
from openbrowser import CodeAgent, ChatGoogle

async def main():
    agent = CodeAgent(
        task="Go to google.com and search for 'Python tutorials'",
        llm=ChatGoogle(model="gemini-3-flash"),
    )

    result = await agent.run()
    print(f"Result: {result}")

asyncio.run(main())

使用不同的大模型提供商

from openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle

# OpenAI
agent = CodeAgent(task="...", llm=ChatOpenAI(model="gpt-5.2"))

# Anthropic
agent = CodeAgent(task="...", llm=ChatAnthropic(model="claude-sonnet-4-6"))

# Google Gemini
agent = CodeAgent(task="...", llm=ChatGoogle(model="gemini-3-flash"))

直接使用浏览器会话

import asyncio
from openbrowser import BrowserSession, BrowserProfile

async def main():
    profile = BrowserProfile(
        headless=True,
        viewport_width=1920,
        viewport_height=1080,
    )
    
    session = BrowserSession(browser_profile=profile)
    await session.start()
    
    await session.navigate_to("https://example.com")
    screenshot = await session.screenshot()
    
    await session.stop()

asyncio.run(main())

配置

环境变量

# Google (recommended)
export GOOGLE_API_KEY="..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Groq
export GROQ_API_KEY="gsk_..."

# AWS Bedrock
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-west-2"

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

BrowserProfile 选项

from openbrowser import BrowserProfile

profile = BrowserProfile(
    headless=True,
    viewport_width=1280,
    viewport_height=720,
    disable_security=False,
    extra_chromium_args=["--disable-gpu"],
    record_video_dir="./recordings",
    proxy={
        "server": "http://proxy.example.com:8080",
        "username": "user",
        "password": "pass",
    },
)

支持的大模型提供商

提供商	类	模型
Google	ChatGoogle	gemini-3-flash、gemini-3-pro
OpenAI	ChatOpenAI	gpt-5.2、o4-mini、o3
Anthropic	ChatAnthropic	claude-sonnet-4-6、claude-opus-4-6
Groq	ChatGroq	llama-4-scout、qwen3-32b
AWS Bedrock	ChatAWSBedrock	anthropic.claude-sonnet-4-6、amazon.nova-pro
AWS Bedrock（Anthropic）	ChatAnthropicBedrock	通过 Anthropic Bedrock SDK 使用 Claude 模型
Azure OpenAI	ChatAzureOpenAI	Azure 部署的任意模型
OpenRouter	ChatOpenRouter	openrouter.ai 上的任意模型
DeepSeek	ChatDeepSeek	deepseek-chat、deepseek-r1
Cerebras	ChatCerebras	llama-4-scout、qwen-3-235b
Ollama	ChatOllama	llama-4-scout、deepseek-r1（本地）
OCI	ChatOCIRaw	Oracle Cloud GenAI 模型
Browser-Use	ChatBrowserUse	外部大模型服务

Claude Code 插件

将 OpenBrowser 安装为 Claude Code 插件：

# Add the marketplace (one-time)
claude plugin marketplace add billy-enrizky/openbrowser-ai

# Install the plugin
claude plugin install openbrowser@openbrowser-ai

此操作会安装 MCP 服务和 7 个内置技能：

技能	描述
deep-research	开展带引用的多来源网络调研，并生成 Markdown 和 JSON 报告
web-scraping	提取结构化数据、处理分页
form-filling	填写表单、处理登录流程和多步骤向导
e2e-testing	通过模拟用户交互测试 Web 应用
page-analysis	分析页面内容、结构和元数据
accessibility-audit	审查页面是否符合 WCAG 标准
file-download	使用浏览器会话下载文件（PDF、CSV）

工具参数的详细说明请参见 plugin/README.md。

Codex

OpenBrowser 通过原生技能发现机制与 OpenAI Codex 配合使用。

快速安装

告诉 Codex：

Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md

手动安装

# Clone the repository
git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser

# Symlink skills for native discovery
mkdir -p ~/.agents/skills
ln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser

# Restart Codex

然后在项目中配置 MCP 服务（见下文的 MCP 服务）。

详细文档：.codex/INSTALL.md

OpenCode

OpenBrowser 通过插件和技能符号链接与 OpenCode.ai 配合使用。

快速安装

告诉 OpenCode：

Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md

手动安装

# Clone the repository
git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser

# Create directories
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# Symlink plugin and skills
ln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js
ln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser

# Restart OpenCode

然后在项目中配置 MCP 服务（见下文的 MCP 服务）。

详细文档：.opencode/INSTALL.md

OpenClaw

OpenClaw 通过命令行守护进程支持 OpenBrowser。安装 OpenBrowser 后， 通过 Bash 工具运行 openbrowser-ai -c：

openbrowser-ai -c "await navigate('https://example.com')"
openbrowser-ai -c "print(await evaluate('document.title'))"

守护进程会在首次使用时自动启动，并在多次调用之间保留变量。

OpenClaw 插件文档请参见 docs.openclaw.ai/tools/plugin。

MCP 服务

OpenBrowser 内置 MCP（Model Context Protocol）服务，可将浏览器自动化作为工具提供给 Claude 等 AI 助手。该服务已在 MCP 注册表中列出，名称为 me.openbrowser/openbrowser-ai。无需外部大模型 API 密钥——智能能力由 MCP 客户端提供。

默认情况下，每个 MCP 服务进程都会在 ~/.config/openbrowser/profiles/mcp-<instance-id> 下使用独立的配置文件。其 storage_state.json 会从 ~/.config/openbrowser/profiles/default/storage_state.json 初始化一次，因此无需让多个 MCP 服务并发运行时互相终止或损坏浏览器，即可使用现有登录状态。每个进程的配置文件会保留在磁盘上，但后续的 MCP 进程不会自动复用它。若要使用重启后仍保留的配置文件，请设置 OPENBROWSER_USER_DATA_DIR；OPENBROWSER_STORAGE_STATE 仅用于初始化受管理的配置文件，后续更改会保存到当前进程的副本中，而不会自动复制回去。OpenBrowser 还会自动清理受管理配置文件中可丢弃的 Chromium 缓存，从而减少磁盘占用，同时保留 Cookie 和登录状态。如果你为多个服务显式配置了相同的 OPENBROWSER_USER_DATA_DIR，配置文件租约会拒绝第二个所有者，并给出明确错误。

快速设置

Claude Code：添加到项目的 .mcp.json：

{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"]
    }
  }
}

Claude Desktop：添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}

直接运行：

uvx openbrowser-ai --mcp

工具

MCP 服务提供一个 execute_code 工具，可在持久化命名空间中运行 Python 代码，并提供浏览器自动化函数。大模型编写 Python 代码以进行导航、交互和提取数据，并且只返回明确请求的内容。

可用函数（除非另有说明，均使用 await）：

类别	函数
导航	navigate(url, new_tab)、go_back()、wait(seconds)
交互	click(index)、input_text(index, text, clear)、scroll(down, pages, index)、send_keys(keys)、upload_file(index, path)
坐标交互	click_xy(x, y, button, click_count)、hover_xy(x, y)、scroll_xy(x, y, delta_x, delta_y)，用于无索引的画布、PDF、嵌入式内容和原生渲染目标
下拉菜单	select_dropdown(index, text)、dropdown_options(index)
标签页	switch(tab_id)、close(tab_id)
JavaScript	evaluate(code)：在页面上下文中运行 JS，并返回 Python 对象
下载	download_file(url, filename)：使用浏览器 Cookie 下载文件；list_downloads()：列出已下载的文件（同步，无需 await）
状态	browser.get_browser_state_summary()：获取页面元数据和交互元素
CSS	get_selector_from_index(index)：获取元素的 CSS 选择器
完成	done(text, success)：表示任务已完成

只要存在元素索引，就优先使用索引操作。坐标操作使用 CSS 视口像素，而非截图像素。如果截图的 devicePixelRatio 不等于 1，请在调用 *_xy 函数前，将坐标除以 window.devicePixelRatio。

预导入的库：json、csv、re、datetime、asyncio、Path、requests、numpy、pandas、matplotlib、BeautifulSoup

配置

环境变量	说明	默认值
OPENBROWSER_HEADLESS	无 GUI 运行浏览器	true
OPENBROWSER_ALLOWED_DOMAINS	以逗号分隔的域名白名单	（无）
OPENBROWSER_USER_DATA_DIR	可选的 Chrome 配置文件目录。省略时，每个 MCP 服务实例使用独立配置文件	（自动：~/.config/openbrowser/profiles/mcp-<instance-id>）
OPENBROWSER_STORAGE_STATE	可选的 JSON 文件，用作托管 MCP 配置文件中 Cookie 和 localStorage 的一次性种子	（自动：每个进程使用一个副本，从 profiles/default 初始化）
OPENBROWSER_COMPACT_DESCRIPTION	精简版工具描述（约 500 个令牌）	false
OPENBROWSER_MAX_OUTPUT	每次执行的最大输出字符数	10000

基准测试：令牌效率

CLI 基准测试：四方对比（6 项任务，N=3 次运行）

对比四种 CLI 工具，每种工具均使用一个 Bash 工具。Claude Sonnet 4.6 运行于 Bedrock。顺序随机。所有工具的准确率均为 100%。

CLI 工具	耗时（平均值 +/- 标准差）	工具调用次数	Bedrock API 令牌数	响应字符数
openbrowser-ai	84.8 +/- 10.9s	15.3 +/- 2.3	36,010 +/- 6,063	9,452 +/- 472
browser-use	106.0 +/- 9.5s	20.7 +/- 6.4	77,123 +/- 33,354	36,241 +/- 12,940
agent-browser	99.0 +/- 6.8s	25.0 +/- 4.0	90,107 +/- 3,698	56,009 +/- 39,733
playwright-cli	118.3 +/- 21.4s	25.7 +/- 8.1	94,130 +/- 35,982	84,065 +/- 49,713

openbrowser-ai 通过 Python 代码批处理和精简的 DOM 表示，使用的令牌比所有竞品少 2.1 至 2.6 倍。

#### 每项任务的令牌用量

任务	openbrowser-ai	browser-use	playwright-cli	agent-browser
fact_lookup	2,504	4,710	16,857	9,676
form_fill	7,887	15,811	31,757	19,226
multi_page_extract	2,354	2,405	8,886	8,117
search_navigate	16,539	47,936	27,779	44,367
deep_navigation	2,178	3,747	4,705	5,534
content_analysis	4,548	2,515	4,147	3,189

openbrowser-ai 在 6 项任务中赢得了 5 项。在复杂页面上优势最大（search_navigate：令牌数比 browser-use 少 2.9 倍），因为代码批处理避免了重复导出页面状态。

每次基准测试运行的成本（6 项任务）

模型	openbrowser-ai	browser-use	playwright-cli	agent-browser
Claude Sonnet 4.6（每 M 个令牌 $3/$15）	$0.12	$0.24	$0.29	$0.27
Claude Opus 4.6（每 M 个令牌 $5/$25）	$0.24	$0.45	$0.56	$0.51

原始结果见 benchmarks/e2e_4way_cli_results.json。查看包含方法说明的完整四方对比。

E2E 大模型基准测试：MCP 服务对比（6 项任务，N=5 次运行）

MCP 服务	通过率	时长（均值 +/- 标准差）	工具调用次数	Bedrock API 令牌数
Playwright MCP（Microsoft）	100%	62.7 +/- 4.8s	9.4 +/- 0.9	158,787
Chrome DevTools MCP（Google）	100%	103.4 +/- 2.7s	19.4 +/- 0.5	299,486
OpenBrowser MCP	100%	77.0 +/- 6.7s	13.8 +/- 2.0	50,195

OpenBrowser 使用的令牌比 Playwright 少 3.2 倍，比 Chrome DevTools 少 6.0 倍。MCP 响应大小：Playwright 为 1,132,173 个字符，Chrome DevTools 为 1,147,244 个字符，OpenBrowser 为 7,853 个字符——相差 144 倍。

查看包含方法说明的完整 MCP 对比

CLI 用法

# Run a browser automation task with an LLM agent
uvx openbrowser-ai -p "Search for Python tutorials on Google"

# Execute code directly via persistent daemon
uvx openbrowser-ai -c "await navigate('https://example.com')"
uvx openbrowser-ai -c "print(await evaluate('document.title'))"

# Daemon management
uvx openbrowser-ai daemon start     # Start daemon (auto-starts on first -c call)
uvx openbrowser-ai daemon stop      # Stop daemon and browser
uvx openbrowser-ai daemon status    # Show daemon info
uvx openbrowser-ai daemon restart   # Restart daemon

# Install browser
uvx openbrowser-ai install

# Run MCP server
uvx openbrowser-ai --mcp

-c 标志通过 Unix 套接字连接到持久运行的浏览器守护进程（Windows 上使用 localhost TCP）。守护进程运行期间，变量会在调用之间保留。首次使用时会自动启动守护进程，并在闲置 10 分钟后关闭。

CLI 守护进程将浏览器配置文件存储在 ~/.config/openbrowser/profiles/daemon，并在该目录下写入 storage_state.json，因此 Cookie 和登录会话在守护进程重启后仍会保留。单次运行的 -p 使用 ~/.config/openbrowser/profiles/cli，并具有相同的存储状态行为。托管配置文件会在启动和关闭时自动清除临时浏览器缓存，同时保留身份验证状态。

项目结构

openbrowser-ai/
├── .claude-plugin/            # Claude Code marketplace config
├── .codex/                    # Codex integration
│   └── INSTALL.md
├── .opencode/                 # OpenCode integration
│   ├── INSTALL.md
│   └── plugins/openbrowser.js
├── plugin/                    # Plugin package (skills + MCP config)
│   ├── .claude-plugin/
│   ├── .mcp.json
│   └── skills/                # 7 browser automation skills
├── src/openbrowser/
│   ├── __init__.py            # Main exports
│   ├── cli.py                 # CLI commands
│   ├── config.py              # Configuration
│   ├── actor/                 # Element interaction
│   ├── agent/                 # LangGraph agent
│   ├── browser/               # CDP browser control
│   ├── code_use/              # Code agent + shared executor
│   ├── daemon/                # Persistent browser daemon (Unix socket)
│   ├── dom/                   # DOM extraction
│   ├── llm/                   # LLM providers
│   ├── mcp/                   # MCP server
│   └── tools/                 # Action registry
├── benchmarks/                # MCP benchmarks and E2E tests
│   ├── playwright_benchmark.py
│   ├── cdp_benchmark.py
│   ├── openbrowser_benchmark.py
│   └── e2e_published_test.py
└── tests/                     # Test suite

测试

# Run unit tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# E2E test the MCP server against the published PyPI package
uv run python benchmarks/e2e_published_test.py

基准测试

运行单个 MCP 服务基准测试（JSON-RPC stdio，5 步 Wikipedia 工作流）：

uv run python benchmarks/openbrowser_benchmark.py   # OpenBrowser MCP
uv run python benchmarks/playwright_benchmark.py     # Playwright MCP
uv run python benchmarks/cdp_benchmark.py            # Chrome DevTools MCP

原始结果见 benchmarks/e2e_4way_cli_results.json。有关方法说明，请参阅完整对比。

后端和前端部署

该项目包含一个 FastAPI 后端和一个 Next.js 前端，两者均使用 Docker 容器化。

先决条件

• Docker 和 Docker Compose
• 项目根目录下的 .env 文件，其中包含 POSTGRES_PASSWORD 和任意 LLM API 密钥（参见 backend/env.example）

本地开发（Docker Compose）

# Start backend + PostgreSQL (frontend runs locally)
docker-compose -f docker-compose.dev.yml up --build

# In a separate terminal, start the frontend
cd frontend && npm install && npm run dev

服务	URL	描述
后端	http://localhost:8000	FastAPI + WebSocket + VNC
前端	http://localhost:3000	Next.js 开发服务器
PostgreSQL	localhost:5432	聊天记录持久化
VNC	ws://localhost:6080	实时浏览器视图

开发用 compose 会将 backend/app/ 和 src/ 挂载为卷，以支持热重载。API 密钥通过 env_file 从 backend/.env 加载。POSTGRES_PASSWORD 从根目录的 .env 文件中读取。

完整技术栈（Docker Compose）

# Start all services (backend + frontend + PostgreSQL)
docker-compose up --build

此配置会构建并运行后端和前端容器，以及 PostgreSQL。

后端

后端是位于 backend/ 中的 FastAPI 应用，Dockerfile 位于 backend/Dockerfile。它包括：

• 运行在 8000 端口的 REST API
• 位于 /ws 的 WebSocket 端点，用于 Agent 实时通信
• VNC 支持（Xvfb + x11vnc + websockify），用于在 6080-6090 端口实时查看浏览器
• 信息亭安全机制：Openbox 窗口管理器、Chromium 企业策略、X11 按键抓取守护进程
• 位于 /health 的健康检查

# Build the backend image
docker build -f backend/Dockerfile -t openbrowser-backend .

# Run standalone
docker run -p 8000:8000 -p 6080:6080 \
  --env-file backend/.env \
  -e VNC_ENABLED=true \
  -e AUTH_ENABLED=false \
  --shm-size=2g \
  openbrowser-backend

前端

前端是位于 frontend/ 中的 Next.js 应用，Dockerfile 位于 frontend/Dockerfile。

# Build the frontend image
cd frontend && docker build -t openbrowser-frontend .

# Run standalone
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://localhost:8000 \
  -e NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws \
  openbrowser-frontend

环境变量

后端的关键环境变量（完整列表请参阅 backend/env.example）：

变量	描述	默认值
GOOGLE_API_KEY	Google/Gemini API 密钥	（必填）
DEFAULT_LLM_MODEL	Agent 的默认模型	gemini-3-flash-preview
AUTH_ENABLED	启用 Cognito JWT 身份验证	false
VNC_ENABLED	启用 VNC 浏览器查看	true
DATABASE_URL	PostgreSQL 连接字符串	（可选）
POSTGRES_PASSWORD	PostgreSQL 密码（根目录 .env）	（compose 必填）

研究：面向浏览器 Agent 的强化微调

除了框架之外，我们还开展了两项独立研究，探索如何通过强化学习改进浏览器 Agent。两项研究均使用 FormFactory 基准（涵盖 8 个领域的 1,250 项表单填写任务）和 OpenBrowser 的浏览器执行环境。

研究 1：浏览器在环（自回归强化学习）

我们研究了强化学习能否进一步提升大模型填写网页表单的能力，超越监督学习的效果。

• 方法：两阶段流程——先使用 QLoRA 在 Qwen3-8B 上进行监督微调（SFT，992 条演示数据），再通过实时浏览器执行奖励进行在线 GRPO 训练（复合奖励：40% 提交成功率 + 40% 字段准确率 + 20% 执行完整度）
• 结果：在留出验证集上，GRPO 的平均奖励比单独使用 SFT 高 9.1%（p=0.007，Wilcoxon 符号秩检验）。提升主要来自更好的表单提交能力，而非字段填写。
• 主要发现：SFT 是必要前提——如果没有 SFT，基础模型会生成无结构文本，所有尝试均无法获得奖励。
• 论文：Browser-in-the-Loop: Reinforcement Fine-Tuning LLM Agents for Web Form Filling
• 模型：Qwen3-8B-FormFactory-SFT-LoRA、Qwen3-8B-FormFactory-GRPO-LoRA

研究 2：用于 Web 操作规划的扩散语言模型

我们研究了扩散语言模型是否能学会 Web 操作规划。这类模型通过对整个序列并行迭代去噪来生成文本，而不是从左到右生成。

• 测试模型：ReFusion 8B（以因果 LM 为主干的掩码扩散模型）和 FS-DFM 1.3B（纯离散流匹配）
• 结果：经过 SFT 后，扩散模型解决了 60-69% 的任务，而 AR 基线为 100%。基于 token 的 RL 普遍不稳定（16 项对比中仅有 2 项有所改善，且均不显著）。基于序列的 RL 则取得成功：MDPO 将 ReFusion 提升至 91.9%（+31.4pp），ESPO 将 FS-DFM 提升至 87.1%（+18.6pp）。
• 关键发现：合适的 RL 方案取决于模型架构。基于 ELBO 的优化（ESPO）能在不同架构中生成集中的分布，而逐步轨迹方法会生成多模态分布。
• 论文：集中还是崩溃：强化学习遇上用于 Web 规划的扩散语言模型时会发生什么
• 模型：HuggingFace 上的 10 个训练模型，包括 ReFusion-8B-MDPO、FS-DFM-1.3B-ESPO-mu8 等

复现实验中的 RL

所有训练代码都位于 infra/training/。训练通过 Anyscale 在单张 NVIDIA A10G GPU（24GB VRAM）上运行。

# Study 1: Autoregressive RL (Qwen3-8B)
# SFT phase -- QLoRA fine-tuning on 992 FormFactory demonstrations (2-4 hours)
python infra/training/finetuning/sft_trainer.py

# Online GRPO phase -- browser-in-the-loop reward (4-8 hours per epoch)
# Requires headless Chromium + FormFactory forms server
python infra/training/shared/formfactory_server.py &   # Start form server
python infra/training/finetuning/online_grpo_trainer.py

# Evaluate SFT and GRPO checkpoints on val/test splits
python infra/training/finetuning/eval_sft.py

# Study 2: Diffusion LM RL (ReFusion 8B, FS-DFM 1.3B)
# SFT phase
python infra/training/flow_matching/fsdfm_sft_trainer.py    # FS-DFM SFT
python infra/training/flow_matching/flow_sft_trainer.py      # ReFusion SFT

# Sequence-level RL (best results)
python infra/training/flow_matching/espo_fsdfm_trainer.py    # ESPO on FS-DFM
python infra/training/flow_matching/espo_refusion_trainer.py # ESPO on ReFusion
python infra/training/flow_matching/mdpo_fsdfm_trainer.py    # MDPO on FS-DFM
python infra/training/flow_matching/mdpo_refusion_trainer.py # MDPO on ReFusion

# Submit jobs to Anyscale cloud
python infra/training/anyscale/submit_job.py --config infra/training/anyscale/online_grpo_job.yaml

# Push trained checkpoints to HuggingFace
python infra/training/anyscale/push_checkpoints_to_hf.py

# Serve trained model locally via vLLM or Ollama
python infra/training/serving/serve_vllm.py
python infra/training/serving/export_gguf.py   # Export to GGUF for Ollama

奖励函数（位于 infra/training/shared/reward_functions.py）：综合得分 = 0.4 * 任务完成度 + 0.4 * 字段准确率 + 0.2 * 执行完整度。在线奖励（online_reward.py）会启动无头 Chromium、执行模型的操作计划，并根据实时浏览器状态计算得分。

参与贡献

欢迎贡献！请：

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

联系方式

• 电子邮件：[email protected]
• GitHub：@billy-enrizky
• 代码库：github.com/billy-enrizky/openbrowser-ai
• 文档：https://docs.openbrowser.me

---

满怀热爱，为 AI 自动化社区打造