Browser Use WebUI 是一款基于 Gradio 构建的AI 浏览器自动化工具，旨在通过大语言模型（LLM）驱动浏览器完成复杂交互任务（如表单填写、信息查询、数据抓取等），支持多模型集成、自定义浏览器配置及持久会话等功能。以下是从安装到使用的完整入门指南。
一、环境准备
Browser Use WebUI 对系统环境要求较低，但需满足以下基础条件：
- 操作系统：支持 Windows 10/11、macOS 或 Linux（推荐 Windows 11 或 macOS）。
- Python 版本：需 Python 3.11 或更高版本（项目依赖 Python 3.11+ 的新特性）。
- 依赖工具：需安装
git（用于克隆仓库）和uv（Python 虚拟环境管理工具，推荐使用）。
二、安装步骤
Browser Use WebUI 提供本地安装和Docker 安装两种方式，推荐使用 Docker 安装（更便捷，无需处理环境依赖）。
1. 本地安装（适合有 Python 经验的用户）
步骤 1：克隆项目仓库
打开终端（Windows 用 PowerShell 或 Command Prompt，macOS/Linux 用 Terminal），执行以下命令克隆项目：
git clone https://github.com/browser-use/web-ui.git
cd web-ui
步骤 2：创建 Python 虚拟环境
使用 uv创建并激活 Python 3.11 虚拟环境（避免与系统 Python 冲突）：
# 创建虚拟环境
uv venv --python 3.11
# 激活虚拟环境
# Windows（Command Prompt）：
.venv\Scripts\activate
# Windows（PowerShell）：
..venv\Scripts\Activate.ps1
# macOS/Linux：
source .venv/bin/activate
步骤 3：安装依赖
安装项目所需依赖（包括 Gradio、Playwright 等）：
uv pip install -r requirements.txt
步骤 4：安装 Playwright 浏览器
Playwright 是 Browser Use WebUI 的底层浏览器自动化工具，需安装 Chromium 浏览器及驱动：
playwright install --with-deps chromium
2. Docker 安装（推荐，适合新手）
Docker 安装无需处理环境依赖，直接运行容器即可。执行以下命令：
# 克隆项目仓库
git clone https://github.com/browser-use/web-ui.git
cd web-ui
# 使用 Docker Compose 构建并启动容器（默认设置：AI 任务完成后关闭浏览器）
docker compose up --build
# 若需保持浏览器会话（任务间保留状态），添加环境变量：
CHROME_PERSISTENT_SESSION=true docker compose up --build
三、配置环境变量
Browser Use WebUI 的配置通过 .env文件管理，需在项目根目录创建 .env文件（复制 .env.example并修改）：
# 复制 .env.example 到 .env（Windows 用 copy，macOS/Linux 用 cp）
# Windows：
copy .env.example .env
# macOS/Linux：
cp .env.example .env
关键配置项说明
-
LLM 配置（必填）：
-
选择 LLM 提供商（如 DeepSeek、OpenAI、Gemini 等），并填写 API 密钥。
-
示例（DeepSeek）：
DEEPSEEK_API_KEY=your_deepseek_api_key DEEPSEEK_API_BASE=https://api.deepseek.com/v1 -
示例（OpenAI）：
OPENAI_API_KEY=your_openai_api_key OPENAI_ENDPOINT=https://api.openai.com/v1
-
-
浏览器配置（可选）：
-
若使用自有浏览器（如 Chrome、Edge），需设置浏览器路径和用户数据目录（保留登录状态）：
# Windows 示例（Chrome）： CHROME_PATH="C:\Program Files\Google Chrome\Application\chrome.exe" CHROME_USER_DATA="C:\Users\YourUsername\AppData\Local\Google Chrome\User Data" # macOS 示例（Chrome）： CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" CHROME_USER_DATA="~/Library/Application Support/Google/Chrome/Default" -
若需保持浏览器会话（任务间保留历史），添加：
CHROME_PERSISTENT_SESSION=true
-
-
其他配置（可选）：
-
调整任务超时时间（默认 300 秒）：
TASK_TIMEOUT=300 -
启用 VNC 监控（查看浏览器操作，需设置密码）：
VNC_PASSWORD=your_vnc_password
-
四、启动 WebUI
1. 本地安装启动
在终端中执行以下命令启动 WebUI（默认监听 127.0.0.1:7788）：
python webui.py --ip 127.0.0.1 --port 7788
2. Docker 安装启动
若使用 Docker 安装，直接运行 docker compose up --build即可，WebUI 会自动启动。
五、访问 WebUI
启动成功后，打开浏览器访问以下地址：
- WebUI 界面：http://127.0.0.1:7788（本地安装）或 http://localhost:7788（Docker 安装）。
- VNC 监控界面（若启用）：http://127.0.0.1:6080/vnc.html（默认密码为
youvncpassword，可在.env中修改）。
六、使用指南
1. 界面概览
WebUI 界面采用标签式设计，主要包含以下功能区域：
- Agent Settings：代理设置，这里应该是配置AI代理的参数、系统提示等，比如修改系统指令（Override/Extend system prompt）。
- Browser Settings：浏览器设置，可能调整浏览器本身的选项，如页面加载、权限等。
- Run Agent：运行代理，启动AI代理执行任务，比如自动操作浏览器流程。
- Agent Marketplace：代理市场，获取或分享预制的AI代理，类似应用商店。
- Load & Save Config：加载和保存配置，方便备份或迁移设置。
2. 运行第一个任务
以“搜索‘AI 浏览器自动化’并返回前 5 条结果”为例，步骤如下：
步骤 1：配置代理参数（可选）
在Agent Settings中选择 LLM 模型（如 gpt-4o）、调整温度（Temperature，控制输出随机性，默认 0.7）等参数。
步骤 2：点击 Run Agent，输入任务指令
在“Your Task or Response”输入框中填写任务描述（需清晰、具体）：
打开百度，搜索“AI 浏览器自动化”，返回前 5 条结果的标题和链接。
步骤 3：启动任务
点击“Submit Task”按钮，WebUI 会自动启动浏览器并执行任务。执行过程中，可实时查看：
- 步骤截图：每一步操作的浏览器截图。
- 日志输出：LLM 的思考过程及执行日志。
- 结果展示：任务完成后，返回前 5 条结果的标题和链接。
3. 常用功能
（1）使用自有浏览器
若需保留登录状态（如登录后的淘宝、微信），需勾选Browser Settings中的“Use Own Browser”，并填写浏览器路径和用户数据目录（参考“环境配置”部分）。
（2）持久会话
勾选“CHROME_PERSISTENT_SESSION”（.env中）或“Use Own Browser”后，任务间浏览器会保持打开状态，可查看之前的操作历史。
（3）任务库
在任务库标签页中，可保存常用任务（如“每日新闻查询”），下次直接加载执行，无需重复输入指令。
七、常见问题排查
1. 启动失败
- 症状：执行
python webui.py后报错“Port 7788 is already in use”（端口冲突）。 - 解决：修改启动端口（如
--port 7789）或关闭占用端口的进程。
2. 浏览器无法启动
-
症状：点击“Run Agent”后，浏览器未弹出。
-
解决：
- 检查
.env中的浏览器路径是否正确（如 Chrome 路径是否为C:\Program Files\Google Chrome\Application\chrome.exe）。 - 关闭所有 Chrome 窗口后重试（避免进程冲突）。
- 检查
3. LLM 调用失败
-
症状：任务执行时报错“API key not found”（API 密钥缺失）。
-
解决：
- 检查
.env中的 API 密钥是否正确（如 DeepSeek 的DEEPSEEK_API_KEY）。 - 确认 LLM 提供商的 API 是否可用（如 OpenAI 的 API 是否被封禁）。
- 检查
4. 任务执行超时
-
症状：任务执行时间过长，提示“Task timed out”（任务超时）。
-
解决：
- 增加
.env中的TASK_TIMEOUT（如设置为 600 秒）。 - 优化任务指令（如将“搜索‘AI 浏览器自动化’并返回前 100 条结果”改为“返回前 5 条”）。
- 增加
八、高级技巧
1. 自定义提示词
若需优化 LLM 的输出，可在任务指令中添加自定义提示词（如“请用简洁的语言返回结果，避免冗余”），引导 LLM 生成更符合需求的输出。
2. 结合函数调用
Browser Use WebUI 支持函数调用（如调用天气 API 获取实时天气），需在任务指令中定义函数，并让 LLM 决定是否调用。例如：
# 定义天气函数
def get_weather(city: str) -> str:
# 调用天气 API 的代码
return f"{city}的天气是晴天，温度 25℃"
# 任务指令
"请告诉我北京的天气，若需要调用函数，请说明。"
3. 使用插件
Browser Use WebUI 支持插件扩展（如 PDF 阅读、文件上传），需在项目中安装插件并配置。例如，安装 browser-use-pdf插件后，可让 LLM 读取 PDF 文件中的内容。
九、资源与社区
- 官方 GitHub 仓库：github.com/browser-use…（获取最新代码、提交 issue）。
- 官方文档：browser-use.com/（详细的功能说明、API 文档）。
- 社区支持：Discord 频道（discord.gg/browser-use）或 GitHub Discussions（github.com/browser-use…）（与其他用户交流经验）。
总结
Browser Use WebUI 是一款功能强大、易用的 AI 浏览器自动化工具，通过简单的安装和配置，即可实现复杂网页任务的自动化。本指南覆盖了从安装到使用的全流程，包括环境准备、安装步骤、配置方法、使用技巧及常见问题排查。若需更深入的功能，建议参考官方文档或社区资源。
