Browser Use WebUI 完整部署与实战指南：在浏览器中运行你的 AI Agent

• 人工智能
• AI 应用
• 交互助手
• 浏览器控制

导读

本文以README.md为主体，结合本仓库的源码、配置文件与测试，系统讲解Browser Use WebUI的本地安装、Docker 部署、LLM 接入、自有浏览器复用、持久化会话与 Gradio 界面各标签页的使用方法。读完本文，你将能够从零搭建一套可运行的浏览器 Agent Web 界面，并把 OpenAI、Anthropic、Google、DeepSeek、Ollama 等多种模型接入其中，实现"用自然语言指令让 AI 操作浏览器"的完整闭环。

一、项目定位：为浏览器 AI Agent 打造的 Gradio WebUI

Browser Use WebUI 构建在开源浏览器 Agent 框架browser-use之上，其核心目标是把"让 AI Agent 操作浏览器"的能力包装成一个开箱即用的图形界面，而非命令行工具。仓库对自身的定位可以归纳为四点：

• WebUI 界面：基于 Gradio 构建，覆盖browser-use的大部分功能，界面友好，可轻松与浏览器 Agent 交互。界面默认深色主题，由 src/webui/interface.py 中的create_ui()函数负责组装，内置 8 套 Gradio 主题（Default、Soft、Monochrome、Glass、Origin、Citrus、Ocean、Base），默认使用Ocean。
• 扩展的 LLM 支持：集成了 Google、OpenAI、Azure OpenAI、Anthropic、DeepSeek、Ollama 等多个模型提供方，并计划持续扩充。
• 自定义浏览器支持：可以复用你自己日常使用的浏览器，避免重复登录站点或反复处理认证挑战，同时支持高清屏幕录制。
• 持久化浏览器会话：可选择在 AI 任务之间保持浏览器窗口打开，让你能看到 AI 交互的完整历史与状态。

从 requirements.txt 可以看到，项目以browser-use==0.1.48为核心依赖，并配套gradio==5.27.0、langgraph、langchain-mistralai、langchain-ibm、MainContentExtractor、json-repair等组件，用于支撑 Agent 调度、多模型接入与网页内容提取。

二、本地安装（Local Installation）

2.1 克隆仓库

git clone https://gitcode.com/GitHub_Trending/web/web-ui.git cd web-ui

2.2 创建 Python 环境

项目推荐使用uv管理 Python 环境（要求 Python 3.11）：

uv venv --python 3.11

激活虚拟环境：

• Windows（Command Prompt）：

.venv\Scripts\activate

• Windows（PowerShell）：

.\.venv\Scripts\Activate.ps1

• macOS / Linux：

source .venv/bin/activate

2.3 安装依赖与浏览器

安装 Python 依赖：

uv pip install -r requirements.txt

随后安装 Playwright 浏览器及系统依赖：

playwright install --with-deps

也可以只安装 Chromium：

playwright install chromium --with-deps

说明：requirements.txt中锁定了browser-use==0.1.48，Agent 的浏览器控制能力（页面导航、元素点击、表单填写、截图识别等）均由该版本框架提供，本文后续对浏览器参数的分析均以此版本为准。

2.4 配置环境变量

创建环境变量文件（二选一）：

• Windows（Command Prompt）：

copy .env.example .env

• macOS / Linux / Windows（PowerShell）：

cp .env.example .env

然后用文本编辑器打开.env，填入 API Key 与各项设置（详见下文第四节）。仓库根目录已提供完整模板 .env.example，其中包含了所有支持提供方的端点与密钥位、默认 LLM、遥测开关、日志级别、浏览器与显示相关变量。

2.5 启动 WebUI

python webui.py --ip 127.0.0.1 --port 7788

启动后，用浏览器访问http://127.0.0.1:7788即可进入界面。

webui.py 是入口文件，它先通过dotenv加载.env，再解析三个命令行参数：

对应源码（webui.py）：

parser.add_argument("--ip", type=str, default="127.0.0.1", help="IP address to bind to") parser.add_argument("--port", type=int, default=7788, help="Port to listen on") parser.add_argument("--theme", type=str, default="Ocean", choices=theme_map.keys(), help="Theme to use for the UI") ... demo = create_ui(theme_name=args.theme) demo.queue().launch(server_name=args.ip, server_port=args.port)

三、使用你自己的浏览器（可选，强烈推荐）

复用个人浏览器最大的好处是：免去在 AI 会话中反复登录、绕过各类认证的麻烦，同时项目支持高清屏幕录制。配置方法如下。

3.1 设置浏览器路径与用户数据目录

在.env中设置BROWSER_PATH（浏览器可执行文件路径）与BROWSER_USER_DATA（浏览器用户数据目录）。若希望使用本地默认用户数据，可留空BROWSER_USER_DATA。

Windows 示例：

BROWSER_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe" BROWSER_USER_DATA="C:\Users\YourUsername\AppData\Local\Google\Chrome\User Data"

注意：请将YourUsername替换为实际的 Windows 用户名。

Mac 示例：

BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" BROWSER_USER_DATA="/Users/YourUsername/Library/Application Support/Google/Chrome"

3.2 启用步骤

1. 关闭所有 Chrome 窗口；
2. 使用非 Chrome 浏览器（如 Firefox、Edge）打开 WebUI——这一点很重要，因为运行 Agent 时持久化浏览器上下文会使用 Chrome 的用户数据；
3. 在Browser Settings（浏览器设置）标签页勾选"Use Own Browser"。

3.3 源码层面的行为说明

从源码看，"使用自有浏览器"并非简单的通道切换，而是把用户的浏览器数据目录透传给 Playwright 启动参数：

• 在 src/webui/components/browser_use_agent_tab.py 的run_agent_task()中，当use_own_browser为真时，会读取环境变量BROWSER_PATH作为二进制路径，并在BROWSER_USER_DATA非空时追加--user-data-dir=<路径>到extra_browser_args；反之（不使用自有浏览器）时browser_binary_path会被置为None，交由内置浏览器逻辑处理。
• 这些参数最终通过 src/browser/custom_browser.py 的_setup_builtin_browser()组装进 Chrome 启动命令。该实现还做了两项额外处理：若本机 9222 调试端口已被占用，会自动移除--remote-debugging-port参数避免端口冲突；非 headless 模式下会按配置的窗口宽高与系统窗口边框偏移计算--window-size/--window-position，保证截图区域准确。
• 浏览器配置项还包括Headless Mode（无头模式，配合界面中的浏览器实时画面）、Disable Security（关闭浏览器安全限制）、Window Width/Window Height（默认 1280×1100）以及CDP URL/WSS URL（远程调试连接），这些都在 browser_settings_tab.py 中定义。其中任意一项发生变化时，会触发close_browser()关闭现有浏览器与上下文，以新配置重建。

四、Docker 安装与部署

4.1 前置条件

• 已安装 Docker 与 Docker Compose：Windows/macOS 使用 Docker Desktop；Linux 安装 Docker Engine 与 Docker Compose 插件。

4.2 配置环境变量

与本地安装相同，先执行：

• Windows（Command Prompt）：copy .env.example .env
• macOS / Linux / Windows（PowerShell）：cp .env.example .env

然后在.env中填入 API Keys 及其他设置。

4.3 构建并启动

docker compose up --build

ARM64 架构系统（如 Apple Silicon Mac）请使用：

TARGETPLATFORM=linux/arm64 docker compose up --build

4.4 访问 WebUI 与 VNC

• Web-UI：浏览器打开http://localhost:7788
• VNC Viewer（观看浏览器交互过程）：打开http://localhost:6080/vnc.html
  • 默认 VNC 密码：youvncpassword
  • 可通过.env中的VNC_PASSWORD修改

4.5 源码视角：容器里发生了什么

• docker-compose.yml 定义了browser-use-webui服务，映射了四个端口：7788（WebUI）、6080（noVNC 网页版 VNC 客户端）、5901（VNC 服务端口）、9222（浏览器远程调试端口），并通过环境变量把.env中的全部 LLM 端点/密钥、BROWSER_PATH、KEEP_BROWSER_OPEN、RESOLUTION、VNC_PASSWORD等注入容器。
• Dockerfile 基于python:3.11-slim-bookworm，安装了 Xvfb（虚拟显示）、x11vnc、noVNC、supervisor 与 Chromium（PLAYWRIGHT_BROWSERS_PATH=/ms-browsers），并把 Playwright 浏览器下载在构建期完成。
• supervisord.conf 则编排了容器内的多进程：Xvfb 虚拟屏幕（分辨率来自RESOLUTION）、VNC 密码初始化与 x11vnc 服务、noVNC 代理、以及python webui.py --ip 0.0.0.0 --port 7788的 WebUI 主进程。这也是为什么容器内 WebUI 监听 0.0.0.0，宿主机通过端口映射即可访问。

五、环境变量全量解析

以下变量均可在.env中配置（模板见 .env.example），Docker 场景下 docker-compose.yml 会原样透传：

5.1 LLM 服务配置

5.2 应用与日志

5.3 浏览器与显示

六、WebUI 界面结构：五个标签页

interface.py 中定义了完整的界面布局，共五个标签页：

1. ⚙️ Agent Settings（Agent 设置）：配置模型与运行参数；
2. 🌐 Browser Settings（浏览器设置）：配置浏览器与录制/下载路径；
3. 🤖 Run Agent（运行 Agent）：任务输入、聊天交互、控制按钮与任务输出；
4. 🎁 Agent Marketplace（Agent 市场）：内嵌 Deep Research 等基于 Browser-Use 构建的 Agent（仓库中对应 deep_research_agent_tab.py 与 deep_research_agent.py）；
5. 📁 Load & Save Config（配置导入导出）：把整套界面设置保存为 JSON 或从 JSON 恢复。

6.1 Agent Settings：模型与运行参数

该标签页（agent_settings_tab.py）提供的核心参数如下：

• Override / Extend system prompt：覆盖或追加系统提示词，可自定义 Agent 行为；
• MCP server json：上传 MCP 服务器配置（.json），上传后界面会展示解析出的配置内容；底层通过 custom_controller.py 的setup_mcp_client()建立 MCP 客户端，并把每个 MCP 工具注册为mcp.<server>.<tool>形式的新动作，扩展 Agent 的工具集；
• LLM Provider / LLM Model Name：模型提供方与模型名，模型下拉列表来自 src/utils/config.py 的model_names字典（如 OpenAI 的gpt-4o、DeepSeek 的deepseek-chat/deepseek-reasoner、Google 的gemini-2.x系列、Ollama 的qwen2.5:*/deepseek-r1:*、硅基流动的 DeepSeek/Qwen 系列等），也支持手动输入自定义模型名；
• LLM Temperature：0.0~2.0 滑动条，默认 0.6，控制模型输出随机性；
• Use Vision：默认开启，把高亮截图输入 LLM，使其具备"看"页面的能力；
• Ollama Context Length：选择 Ollama 时可见，默认 16000，控制模型上下文长度（越小越快）；
• Base URL / API Key：可覆盖.env中的端点与密钥；API Key 留空时自动回落到.env；
• Planner LLM 系列参数：可选的规划器模型（独立于主模型），用于 Deep Research 类任务规划；
• Max Run Steps：默认 100，Agent 最大执行步数（1~1000）；
• Max Number of Actions：默认 10，每步最多执行的动作数；
• Max Input Tokens：默认 128000，输入 Token 上限；
• Tool Calling Method：默认auto，可选function_calling、json_mode、raw、tools、None。

模型接入的源码佐证：src/utils/llm_provider.py 的get_llm_model()根据 provider 分发到不同的 LangChain 模型类——如 OpenAI/DeepSeek/Alibaba/Moonshot/Unbound/SiliconFlow 等走ChatOpenAI（OpenAI 兼容端点），Azure 走AzureChatOpenAI，Google 走ChatGoogleGenerativeAI，Ollama 走ChatOllama，IBM 走ChatWatsonx。其中 DeepSeek 的deepseek-reasoner与 Ollama 的deepseek-r1会使用项目自定义的DeepSeekR1ChatOpenAI/DeepSeekR1ChatOllama包装类，以透传模型返回的reasoning_content（思维链），从而实现类似 DeepSeek-R1 的深度思考能力。

6.2 Browser Settings：浏览器与录制

该标签页（browser_settings_tab.py）覆盖：

• Browser Binary Path / Browser User Data Dir：自有浏览器路径与用户数据目录；
• Use Own Browser：默认读取USE_OWN_BROWSER；
• Keep Browser Open：默认读取KEEP_BROWSER_OPEN=true，即任务间保持浏览器打开；
• Headless Mode：无头模式；开启后，Run Agent 页的Browser Live View会以流式截图展示浏览器实时画面；
• Disable Security：关闭浏览器安全限制；
• Window Width / Height：默认 1280×1100；
• CDP URL / WSS URL：通过 Chrome DevTools Protocol 或 WebSocket 连接已有浏览器实例；
• Recording Path / Trace Path：浏览器录制视频与 Agent Trace 的保存目录；
• Agent History Save Path：默认./tmp/agent_history，Agent 历史（JSON + GIF）保存目录；
• Save Directory for browser downloads：默认./tmp/downloads，浏览器下载文件保存目录。

6.3 Run Agent：任务执行流程

该标签页（browser_use_agent_tab.py）是核心交互区，包含：

• Agent Interaction 聊天区：实时展示任务状态与每一步的截图 + Agent 决策 JSON；
• Your Task or Response 输入框：输入任务；当 Agent 主动求助（遇到验证码、需要人工判断、需要凭据等）时，此框会变成人工应答输入；
• 控制按钮：▶️ Submit Task、⏹️ Stop、⏸️ Pause/Resume、🗑️ Clear；
• 任务输出区：Agent History JSON（完整执行历史，按任务 UUID 存为tmp/agent_history/<uuid>/<uuid>.json）与Task Recording GIF（任务过程 GIF）。

其执行流程（run_agent_task()）可概括为：读取任务 → 汇总 Agent/Browser 两页设置 → 初始化 LLM（含可选的 Planner LLM）→ 初始化CustomController（注册ask_for_assistant、upload_file等自定义动作，并按需接入 MCP 工具）→ 创建/复用CustomBrowser与CustomBrowserContext→ 初始化或复用BrowserUseAgent→ 以异步任务运行并轮询推送界面更新 → 结束后保存历史与 GIF、按KEEP_BROWSER_OPEN决定是否关闭浏览器。

几个值得注意的实现细节：

• 人工求助机制：CustomController中注册了ask_for_assistant动作，描述文本明确要求 Agent 在遇到无凭据、需主观判断、复杂验证码等"确定阻塞"时向人类求助；WebUI 通过asyncio.Event（bu_response_event）阻塞等待用户在输入框给出回复，最长等待 3600 秒，超时则告知 Agent 继续尝试其他方式。对应源码见 custom_controller.py 与_ask_assistant_callback。
• 暂停/停止/清空：Pause/Resume调用agent.pause()/agent.resume()；Stop置agent.state.stopped = True；Clear会先停止任务、关闭 MCP 客户端、清空聊天历史与浏览器视图。
• Agent 复用：当KEEP_BROWSER_OPEN=true时，同一浏览器、上下文与 Agent 实例会在多个任务间复用，add_new_task()只追加新任务而不重建整个链路，这正是"持久化浏览器会话"的底层实现，相关状态由 webui_manager.py 的WebuiManager统一持有（bu_agent、bu_browser、bu_browser_context、bu_chat_history等）。

6.4 Load & Save Config：配置持久化

该标签页（load_save_config_tab.py）提供两个按钮：

• Save UI Settings：把当前界面所有可交互控件的值（除按钮与文件组件外）保存为tmp/webui_settings/<时间戳>.json；
• Load Config：从 JSON 恢复全部控件状态，并在状态框显示加载结果。

底层的save_config()/load_config()实现在 webui_manager.py，加载时会跳过 Chatbot 等特殊组件，并对planner_llm_provider做分段更新以触发下拉回调联动。

七、常见场景速查

7.1 只想快速体验

uv venv --python 3.11 && source .venv/bin/activate uv pip install -r requirements.txt playwright install chromium --with-deps cp .env.example .env # 编辑 .env 填入任一 LLM 的 API Key python webui.py --ip 127.0.0.1 --port 7788

7.2 想要 AI 使用你登录过的 Chrome

1. .env中设置BROWSER_PATH与BROWSER_USER_DATA；
2. 完全关闭所有 Chrome 进程；
3. 用 Firefox/Edge 打开 WebUI；
4. 在 Browser Settings 勾选 "Use Own Browser" 后提交任务。

7.3 想要跨任务保持浏览器与登录状态

确保.env中KEEP_BROWSER_OPEN=true（默认值），任务结束后浏览器窗口不关闭，Agent 状态、已登录会话与页面上下文均保留到下一个任务。

7.4 想要在无头服务器上观看 Agent 操作

使用 Docker 部署，通过http://localhost:6080/vnc.html打开 noVNC 观看实时画面；或在本地开启 Headless Mode，在 Run Agent 页的 Browser Live View 查看流式截图。

八、版本演进（Changelog）

仓库README.md记录的演进历史如下：

• 2025/01/26：支持与 DeepSeek-R1 组合实现深度思考（配合deepseek-reasoner/deepseek-r1模型与思维链透传能力）；
• 2025/01/10：新增 Docker 部署方案，并支持任务之间保持浏览器打开；
• 2025/01/06：发布全新设计的 WebUI。

九、写在最后

本文从官方 README 出发，结合仓库源码把 Browser Use WebUI 的安装、配置、部署与使用链路完整展开：本地与 Docker 两种部署方式、13+ 个 LLM 提供方的接入方式、自有浏览器复用与持久化会话的实现原理、以及 Gradio 界面五大标签页背后的代码逻辑。若需深入某一部分，建议直接阅读以下关键文件：

• 入口与界面：webui.py、src/webui/interface.py
• 配置模板：.env.example、docker-compose.yml、Dockerfile、supervisord.conf
• 模型接入：src/utils/config.py、src/utils/llm_provider.py
• 浏览器适配：src/browser/custom_browser.py、src/browser/custom_context.py
• Agent 与控制器：src/agent/browser_use/browser_use_agent.py、src/controller/custom_controller.py
• 界面各页实现：src/webui/components/ 目录与 src/webui/webui_manager.py

按文中步骤操作即可在一台有 Python 3.11 或 Docker 的机器上，把"让 AI Agent 在浏览器里干活"这件事真正跑起来。

• 人工智能
• AI 应用
• 交互助手
• 浏览器控制