基于 CDP 驱动的智能自主浏览器代理，支持多 LLM 后端、视觉理解与 WebMCP 协议扩展，可自动完成网页导航、动态交互、文件操作等端到端 Web 任务。
项目定位#
Web-Use 是一个基于 CDP（Chrome DevTools Protocol）直接驱动的智能自主浏览器代理，通过 WebSocket 连接真实 Chrome/Edge 浏览器，让大语言模型具备端到端的 Web 操作能力。
核心能力#
自主浏览与交互#
- 自主 Web 导航：自动导航网站、填写表单、交互动态内容（SPA 等），无需人工干预
- 高效元素交互：索引化 DOM 元素，快速精准定位并执行点击、输入等操作
- 文件操作：支持文件下载与上传
- 状态感知：维护页面状态理解，避免死循环并自动恢复错误
- 智能等待：处理加载状态、动画以及 CAPTCHA、OTP 等人机交互场景
多模型与视觉#
- 多 LLM 支持：内置 13 种 Provider——Anthropic Claude、Google Gemini、OpenAI、Groq、Ollama、Cerebras、Mistral、DeepSeek、NVIDIA、vLLM、Azure OpenAI、OpenRouter、LiteLLM
- 视觉能力：支持截屏理解页面视觉内容，辅助决策（
use_vision=True）
协议与扩展#
- WebMCP（Web Model Context Protocol）：自动发现网站暴露的自定义工具，动态注册并像内置工具一样调用；支持参数校验和 schema 信息展示
运维与控制#
- Human-in-the-loop：可配置暂停等待人工输入（
include_human_in_loop=True） - 浏览器持久化：任务完成后可保持浏览器打开（
keep_alive=True） - 系统 Profile 复用：支持使用真实浏览器 Profile，保留登录态等认证信息
典型场景#
- 电商比价：在 Amazon 等平台自动搜索并汇总不同卖家商品价格
- 社交媒体操作：自动登录 X/Twitter 并发布帖子
- 视频播放：在 YouTube 上搜索并播放指定视频
- GitHub 仓库导航：自动登录 GitHub 并浏览指定仓库
- 文档站内搜索：利用 WebMCP 协议调用文档站暴露的自定义工具
- Web 数据采集：自动化浏览并提取结构化信息
- 表单填写：自动化重复性表单填写流程
架构设计#
项目采用分层架构（src/ 目录）：
| 模块 | 职责 |
|---|---|
agent/ | 核心代理逻辑，含基类、主循环、服务层、视图渲染 |
agent/browser/ | 浏览器连接与 CDP 通信管理 |
agent/context/ | 上下文管理 |
agent/dom/ | DOM 元素索引与交互 |
agent/events/ | 事件系统 |
agent/registry/ | 工具/资源注册表 |
agent/tools/ | 代理内置工具集 |
agent/watchdog/ | 超时与异常监控 |
cdp/ | Chrome DevTools Protocol 封装层 |
messages/ | 消息/对话模型 |
providers/ | LLM Provider 抽象层（13 个实现） |
tools/ | 工具服务层 |
关键机制：
- 通过 CDP 直接控制浏览器，使用 WebSocket 连接（依赖
websockets库），非 Selenium/Playwright 等高层封装 - DOM 元素索引化以加速元素定位
- 使用 Pillow 截图进行视觉理解
- 使用
markdownify将 HTML 转为 Markdown 供 LLM 理解 - 使用
pyotp处理 OTP 验证场景 - 构建系统：Hatchling
灵感参考： vimGPT、WebVoyager、LangGraph Examples
安装与快速开始#
前置条件： Python ≥ 3.13、UV 包管理器、Chrome 浏览器（需启用远程调试）
git clone https://github.com/CursorTouch/Web-Use.git
cd Web-Use
uv sync
chrome --remote-debugging-port=9222
配置 .env 文件：
GOOGLE_API_KEY="<API_KEY_HERE>"
最小运行代码：
from src.agent.browser.config import BrowserConfig
from src.providers.ollama import ChatOllama
from src.agent import Agent
from dotenv import load_dotenv
load_dotenv()
llm = ChatOllama(model='qwen3.5:397b-cloud', temperature=0.5)
config = BrowserConfig(browser='chrome', headless=False, use_system_profile=True)
agent = Agent(config=config, llm=llm, use_vision=False, use_web_mcp=True, max_steps=100)
user_query = input('Enter your query: ')
agent.print_response(user_query)
uv run main.py
关键配置参数#
Agent 构造参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
config | BrowserConfig | 必填 | 浏览器配置 |
llm | BaseChatLLM | 必填 | 语言模型实例 |
use_vision | bool | False | 是否启用截图视觉理解 |
use_web_mcp | bool | False | 是否启用 WebMCP 协议发现网站工具 |
max_steps | int | 25 | 最大执行步数 |
max_consecutive_failures | int | 3 | 连续失败重试上限 |
include_human_in_loop | bool | False | 是否暂停等待人工输入 |
keep_alive | bool | False | 任务完成后是否保持浏览器打开 |
BrowserConfig 参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
browser | 'chrome' | 浏览器类型（'chrome' 或 'edge'） |
headless | False | 是否无头模式 |
use_system_profile | True | 使用系统浏览器 Profile |
user_data_dir | — | 自定义 Profile 目录路径 |
cdp_port | 9222 | CDP 协议端口 |
downloads_dir | '/Downloads' | 下载目录 |
attach_to_existing | False | 是否连接到已运行的浏览器 |
update_cdp | False | 是否重新生成 CDP 协议文件 |
待确认信息#
- Python 版本要求存在矛盾：README 提示 3.11+，
pyproject.toml要求 ≥ 3.13 - 仓库 topic 标注了
langgraph，但代码中未见显式引用，具体使用方式待确认 - WebMCP 协议无正式规范文档链接，无法确认是否为行业标准
- 无独立官网或文档站，文档集中于 GitHub README
- 无正式论文、Hugging Face 页面等外部资源链接
主要语言：Python（99.7%）、JavaScript（0.3%）。作者：Jeomon George、Muhammad Yaseen。当前版本：v0.2。采用 MIT 许可证。