配置浏览器行为和上下文设置

浏览器使用（Browser Use）允许你通过两个主要的配置类——BrowserConfig 和 BrowserContextConfig 来自定义浏览器的行为。这些设置控制从无头模式到代理配置以及页面加载行为等各种选项。

我们目前正在改进浏览器上下文的管理方式。系统即将过渡到“1 代理（agent）、1 浏览器（browser）、1 上下文（context）”的模型，以提高稳定性和开发者体验。

浏览器配置

BrowserConfig 类用于控制浏览器的核心行为和连接设置。

代码示例

  1. from browser_use import BrowserConfig
  3. # 基本配置
  4. config = BrowserConfig(
  5.     headless=False,
  6.     disable_security=True
  7. )
  9. browser = Browser(config=config)
  11. agent = Agent(
  12.     browser=browser,
  13.     # ...
  14. )

核心设置

  • headless（默认值：False）：是否以无头模式运行浏览器（即无 UI 界面）。请注意，一些网站可能会检测到无头模式。
  • disable_security（默认值：True）：禁用浏览器的安全特性。这可以解决某些功能问题（例如跨站 iFrame 访问），但访问不受信任的网站时应谨慎使用。

其他设置

  • extra_chromium_args（默认值：[]）：启动浏览器时传递的额外参数。请参考完整参数列表。
  • proxy（默认值：None）：标准的 Playwright 代理设置，可用于外部代理服务。
  • new_context_config（默认值：BrowserContextConfig()）：新建浏览器上下文时的默认设置，具体配置见下文的“上下文配置”部分。

对于需要绕过自动化访问限制的网站，我们建议使用外部浏览器或代理服务，以提高可靠性。

替代初始化方式

这些设置允许你连接到外部浏览器提供商，或使用本地 Chrome 实例。

连接到外部浏览器提供商（wss）

可以连接到基于云的浏览器服务，以增强稳定性并支持代理功能。

代码示例

  1. config = BrowserConfig(
  2.     wss_url="wss://your-browser-provider.com/ws"
  3. )
  • wss_url（默认值：None）：用于连接外部浏览器提供商的 WebSocket URL，例如 anchorbrowser.com、steel.dev、browserbase.com、browserless.io。
  • 此配置会覆盖本地浏览器设置，并使用外部提供商的配置，具体配置请参考其官方文档。

连接到外部浏览器提供商（CDP）

可以使用 Chrome DevTools 协议（CDP）连接到云端或本地 Chrome 实例，适用于 headless-shell 或 browserless 等工具。

代码示例

  1. config = BrowserConfig(
  2.     cdp_url="http://localhost:9222"
  3. )
  • cdp_url（默认值：None）：用于通过 CDP 连接到 Chrome 实例，常用于调试或连接本地 Chrome。

连接到本地 Chrome 实例（Binary）

可以使用本地安装的 Chrome 以访问保存的状态和 Cookie。

代码示例

  1. config = BrowserConfig(
  2.     chrome_instance_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  3. )
  • chrome_instance_path（默认值：None）：指定 Chrome 安装路径，适用于需要保持登录状态或浏览器偏好的场景。
  • 此配置会覆盖其他浏览器设置。

上下文配置

BrowserContextConfig 类用于控制单个浏览器上下文的设置。

代码示例

  1. from browser_use.browser.context import BrowserContextConfig
  3. config = BrowserContextConfig(
  4.     cookies_file="path/to/cookies.json",
  5.     wait_for_network_idle_page_load_time=3.0,
  6.     browser_window_size={'width': 1280, 'height': 1100},
  7.     locale='en-US',
  8.     user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36',
  9.     highlight_elements=True,
  10.     viewport_expansion=500,
  11.     allowed_domains=['google.com', 'wikipedia.org'],
  12. )
  14. browser = Browser()
  15. context = BrowserContext(browser=browser, config=config)
  17. async def run_search():
  18.     agent = Agent(
  19.         browser_context=context,
  20.         task='Your task',
  21.         llm=llm
  22.     )

配置选项

页面加载设置

  • minimum_wait_page_load_time（默认值：0.5）：在捕获页面状态之前等待的最短时间。
  • wait_for_network_idle_page_load_time（默认值：1.0）：等待网络活动空闲的时间。对于较慢的网站，建议设为 3-5 秒。这只考虑主要内容的加载，而不包括动态元素（如视频）。
  • maximum_wait_page_load_time（默认值：5.0）：页面加载的最长等待时间，超过此时间会继续执行任务。

显示设置

  • browser_window_size（默认值：{'width': 1280, 'height': 1100}）：浏览器窗口尺寸。默认大小适用于一般情况，并优化与 UI 元素（如 Cookie 横幅）的交互。
  • locale（默认值：None）：指定用户的区域设置（如 en-GB、de-DE）。如果未提供，则默认为系统默认区域设置。
  • highlight_elements（默认值：True）：是否使用彩色边框高亮交互式元素。
  • viewport_expansion（默认值：500）：视口扩展的像素值。
    • -1：包含整个页面内容（会导致高 token 消耗）。
    • 0：仅包含当前视口内可见的元素。
    • 500（默认）：包含比视口稍大的区域，以提供更多上下文信息。

限制访问的 URL

  • allowed_domains（默认值：None）：限制代理（agent）可访问的域名列表。如果设置为 None，则允许访问所有域名。例如： 
  1. allowed_domains=['google.com', 'wikipedia.org']

在该示例中，代理仅能访问 Google 和 Wikipedia。

调试与记录

  • save_recording_path（默认值：None）：视频录制文件的保存目录。
  • trace_path（默认值：None）：跟踪文件的保存目录。文件将自动命名为 {trace_path}/{context_id}.zip。