如何在 Browser Use 中使用代理

为 Browser Use 1.0 智能体配置 HTTP 或 SOCKS5 代理:经过实测的 Playwright 启动方案,带密码的 SOCKS5 为什么不可用,任务之间如何轮换 IP,登录期间如何保持粘性会话,如何检查 DNS 和 WebRTC 泄露,并附上可直接运行的 Python 脚本与测试说明。

本页内容

Browser Use 1.0 没有为它在你电脑上启动的浏览器提供代理设置。要让智能体走你自己的代理,就自己带着代理启动 Chromium,再通过 CDP 把这个浏览器交给智能体。CDP 即 Chrome DevTools Protocol,Browser Use 内部的引擎 browser-harness 就用它控制 Chrome。用 Playwright 启动浏览器只需几行代码,而且支持需要用户名和密码的 HTTP 代理。

测试日期为 2026 年 11 月 18 日,环境为 browser-use 1.0.6、browser-harness 0.1.13、Playwright 1.65.2(自带 Chromium 159.0.8154.6)、Google Chrome 157.0.8103.79 和 Python 3.12.16,系统为 macOS 26.5.1。每个代码块下方都写明了哪些运行过、哪些没有。

简短回答

整个 Browser Use 代理设置只需两次调用:

python
context = await p.chromium.launch_persistent_context(
    profile,
    proxy={'server': 'http://HOST:PORT', 'username': 'USERNAME', 'password': 'PASSWORD'},
    args=['--remote-debugging-port=9242'],
)
agent = Agent(task, browser=Browser(cdp_url='http://127.0.0.1:9242'))

Playwright 通过你的代理启动 Chromium 并应答代理的登录要求,Browser(cdp_url=...) 再把这个浏览器交给智能体,所以智能体打开的每个页面都走代理。这是下文完整脚本的节选,不能单独运行。

为什么不用 Browser Use 的设置?在 1.0 中,旧的 proxy 选项只保留给云端浏览器;对本地浏览器,Browsers 页面写的是“Local: not yet”,而 ProxySettings 现在会报错“Browser('chromium') has no proxy yet”。用 cdp_url 连接是文档中控制任何带 CDP 端点的浏览器的方式,文档自己的 Playwright 示例也是这样做的。本指南只讲 1.0。

准备工作

  • Python 3.11 或更新版本,以及 uv,与 Browser Use 快速入门一致。
  • 一个代理:主机、端口、用户名和密码。下面的命令使用占位符。
  • 模型的密钥。Agent 默认使用 Browser Use 自己的模型并读取 BROWSER_USE_API_KEY;其他模型通过 llm= 传入。
sh
uv init --python 3.12 browser-use-proxy && cd browser-use-proxy
uv add 'browser-use==1.0.6' playwright
uv run playwright install chromium
sh
export PROXY_HOST=proxy.example.com
export PROXY_PORT=8080
export PROXY_USER=USERNAME
export PROXY_PASS=PASSWORD
export BROWSER_USE_API_KEY=YOUR_KEY

安装命令我们按原样运行过;第二个代码块里是占位符,请换成你自己的值。对于 ipvolt 的移动代理,这些值就是设备卡片上的主机、HTTP 端口、用户名和密码。对于住宅代理,主机是 res.ipvolt.com,HTTP 端口是 7000,用户名是控制台按你选择的网络和国家生成的那个,密码是你的密钥(住宅代理快速入门)。

完整可运行的示例

将下面的代码保存为 agent_proxy.py:

python
import asyncio
import json
import os
import tempfile
from pathlib import Path

from playwright.async_api import async_playwright

from browser_use import Agent, Browser

PROXY = {
    'server': f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}",
    'username': os.environ['PROXY_USER'],
    'password': os.environ['PROXY_PASS'],
}
CDP_PORT = 9242


def fresh_profile() -> str:
    """A new Chrome profile in which WebRTC cannot go around the proxy."""
    profile = tempfile.mkdtemp(prefix='agent-')
    prefs = Path(profile, 'Default', 'Preferences')
    prefs.parent.mkdir()
    prefs.write_text(json.dumps({'webrtc': {'ip_handling_policy': 'disable_non_proxied_udp'}}))
    return profile


async def main():
    async with async_playwright() as p:
        context = await p.chromium.launch_persistent_context(
            fresh_profile(),
            headless=True,
            proxy=PROXY,
            args=[f'--remote-debugging-port={CDP_PORT}'],
        )
        try:
            page = context.pages[0]
            await page.goto('https://api.ipify.org')
            print('Exit IP, checked by Playwright:', await page.inner_text('body'))

            agent = Agent(
                'Open https://api.ipify.org in the browser and return only the IP address it shows.',
                browser=Browser(cdp_url=f'http://127.0.0.1:{CDP_PORT}'),
            )
            result = await agent.run()
            print('Exit IP, reported by the agent:', result.final_result())
        finally:
            await context.close()


asyncio.run(main())

用 uv run agent_proxy.py 运行。第一行只来自 Playwright,所以在模型开始工作之前就能确认代理生效;第二行是智能体的回答。

code
Exit IP, checked by Playwright: 203.0.113.24
Exit IP, reported by the agent: 203.0.113.24

运行情况:正是这个文件,连接一个要求用户名和密码、从我们自己的服务器出口的测试代理。我们没有模型 API 密钥,所以运行时由一个脚本化的替身(Pydantic AI 的 FunctionModel)代替模型,返回页面文本;浏览器、代理、CDP 连接和智能体循环都是真实的。上面的输出用文档专用地址(RFC 5737)替换了我们服务器的地址。真实模型会用自己的话回答。

脚本中有三个细节值得注意:

  • fresh_profile() 写入一项 Chrome 偏好设置,防止 WebRTC 暴露你的真实地址;详见下文“故障排查”中的 WebRTC 泄露一项。
  • 调试端口对本机所有程序开放,文档也针对本地浏览器提醒过这一点;在共用的机器上请使用容器。
  • 通过 cdp_url 连接的智能体结束后不会关闭浏览器,所以由 context.close() 关闭它。

租用 1 天移动代理:德国,O2,$9

无需注册账号。用加密货币付款并保存账单 ID;订单页随后会显示脚本需要的主机、端口、用户名和密码。

认证:HTTP 与 SOCKS5

我们在 Google Chrome 157 和 Playwright 的 Chromium 159 中逐一测试了传递凭据的方式,两者结果相同:

配置结果
Playwright 的 proxy,带 username 和 password,HTTP 代理可用,智能体打开的标签页也可用
Playwright 的 proxy,带 username 和 password,SOCKS5 代理无法启动:Browser does not support socks5 proxy authentication
不带密码的 SOCKS5 代理,socks5://HOST:PORT可用
凭据写在 Chrome 参数里,--proxy-server=http://USER:PASS@HOST:PORTnet::ERR_NO_SUPPORTED_PROXIES
--proxy-server 不带凭据,而代理需要密码HTTP:net::ERR_INVALID_AUTH_CREDENTIALS;SOCKS5:net::ERR_SOCKS_CONNECTION_FAILED

Chromium 的代理文档说明了原因:Chrome“will not use any credentials embedded in the proxy settings”,并且“No authentication methods are supported for SOCKSv5 in Chrome”,尽管协议本身定义了用户名密码认证(RFC 1929)。HTTP 代理返回的 407 质询(RFC 9110)需要有人应答,Playwright 的启动器会应答;它的 proxy 选项只为 HTTP 代理说明了用户名和密码。Playwright 的其他代理选项见 Playwright 代理设置。

所以,代理需要密码时就用它的 HTTP 端点。如果必须用带密码的 SOCKS5,就运行一个本地转发器来添加凭据,并让浏览器连接这个转发器:

sh
uv run --with pproxy pproxy -l http://127.0.0.1:8899 -r "socks5://$PROXY_HOST:$PROXY_PORT#$PROXY_USER:$PROXY_PASS"

然后用 PROXY_HOST=127.0.0.1 和 PROXY_PORT=8899 运行示例;转发器不会要求密码。#user:password 是 pproxy 的语法,用于远端代理的登录;监听在 127.0.0.1 可以防止别人借它使用你的代理。运行情况:正是这条命令,连接我们带密码的测试 SOCKS5 代理,随后运行 agent_proxy.py,输出了测试出口地址。

自己运行还是用 Browser Use Cloud

  • 在你自己的电脑上(本指南):Chromium 接受的任何代理都可以,HTTP 或 SOCKS5,规则如上。代理由浏览器处理,Browser Use 不参与。
  • Browser Use Cloud:不带参数的 Browser() 是云端浏览器,默认开启住宅代理;cloud_proxy_country_code='de' 选择其他国家,None 关闭代理(Browsers: Cloud browser)。云端的 Proxies 页面把自定义代理列为由销售团队开通的企业功能(2026 年 11 月 13 日之前创建的项目保留使用权限),字段包括主机、端口、可选的用户名和密码,以及 http 或 https。它可以在不重启的情况下更换独立浏览器的代理,{"rotate": true} 会请求同一国家的新住宅 IP。

库里的 Browser() 只接受国家代码。自定义代理设置在通过 API 创建的浏览器上,这类浏览器用 Playwright 或其他 CDP 客户端控制;用 Browser(cdp_url=...) 连接它,做法与本指南相同。我们没有云端密钥,所以云端部分没有运行。

IP 轮换与会话

对大多数智能体,两条规则就够了:

  • 任务之间换新 IP:每个任务启动一个新浏览器,并在开始前更换出口。
  • 登录期间保持同一 IP:所有需要登录状态的任务共用一个浏览器和一个代理会话。多个智能体可以依次使用它。

Cookie 保存在浏览器配置文件里,出口由代理决定,所以智能体保持登录时两者都不能变(轮换代理与粘性代理)。

python
import asyncio
import json
import os
import secrets
import tempfile
import urllib.request

from playwright.async_api import async_playwright

from browser_use import Agent, Browser

SERVER = f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}"
CDP_PORT = 9242
CHECK = 'Open https://api.ipify.org in the browser and return only the IP address it shows.'


def rotate_mobile_ip():
    """Dedicated mobile proxy: ask the device for a new IP with its rotation link."""
    with urllib.request.urlopen(os.environ['ROTATION_LINK'], timeout=90) as response:
        print('rotation:', json.load(response))


def sticky_username(job: str) -> str:
    """Residential or mobile per GB: a session ID keeps one exit for the whole job."""
    return f"{os.environ['PROXY_USER']}-sid-{job}-rot-sticky-ttl-3600"


async def run_job(p, username, tasks):
    """One browser per job: one exit and one cookie jar for every task in it."""
    context = await p.chromium.launch_persistent_context(
        tempfile.mkdtemp(),
        headless=True,
        args=[f'--remote-debugging-port={CDP_PORT}'],
        proxy={'server': SERVER, 'username': username, 'password': os.environ['PROXY_PASS']},
    )
    try:
        for task in tasks:
            result = await Agent(task, browser=Browser(cdp_url=f'http://127.0.0.1:{CDP_PORT}')).run()
            print(username, '->', result.final_result())
    finally:
        await context.close()


async def main():
    mobile = os.environ.get('PROXY_KIND', 'mobile') == 'mobile'
    async with async_playwright() as p:
        for job in range(2):
            if mobile:
                if job:
                    rotate_mobile_ip()
                username = os.environ['PROXY_USER']
            else:
                username = sticky_username(f'job{job}_{secrets.token_hex(4)}')
            await run_job(p, username, [CHECK, CHECK])


asyncio.run(main())

对应到你使用的代理:

  • 独享移动代理,一台专用设备:同一时间只有一个 IP,已登录任务的所有连接共用它。任务之间,调用设备的轮换链接(ROTATION_LINK,设备支持时位于控制台的 More controls 中),或点击“轮换 IP”。任务保持登录期间请关闭自动轮换,并在轮换完成后再开始下一个任务。
  • 住宅代理或按 GB 计费的移动 IP:会话写在用户名里。没有会话 ID 时,每个连接都会重新选择出口,而浏览器加载一个页面会打开很多连接。加上会话 ID:-sid-NAME-rot-sticky-ttl-3600 请求网关在一小时内保持同一出口,换一个新 ID 就开始新会话。ID 只能包含小写字母、数字和下划线,最长 64 个字符(定位与会话)。

运行情况:rotate.py 按原样运行,使用脚本化模型,两种模式都跑过。移动代理模式连接我们自己的测试 HTTP 代理,轮换链接用本地替身代替;会话模式连接一个忽略用户名的测试代理。每个任务中有两个智能体在同一个浏览器里依次运行。真实的轮换和会话发生在代理端,这里没有测试。

智能体用移动代理还是住宅代理

按智能体要做的事来选,而不只看 IP 类型。移动代理与住宅代理提供了一份同时评估两者的评分表。

  • 独享移动代理适合在同一个账号里长时间保持登录的智能体,或需要指定国家和运营商的场景。租用期间没有其他人使用这台设备,它的地址是运营商地址,运营商常让许多用户共用同一个地址(RFC 6888)。
  • 住宅代理适合在多个国家运行的大量短小、独立的任务,按 GB 计费,每个任务用一个粘性会话。
  • 共享移动代理是来自运营商调制解调器共享池的地址,和住宅代理一样按 GB 计费,详见共享移动代理页面。

代理只改变地址,别的都不改变。如果拦截来自浏览器本身(无头模式或自动化指纹)、来自行为(速度、重复操作),或来自与账号绑定的登录墙或验证码,代理帮不上忙。可以这样检验:在你自己的网络上用普通浏览器执行同样的任务,如果那里也被拦截,原因就不在 IP。Cloudflare 拦截 AI 智能体:先修什么逐一分析了这些情况。

流量

浏览器会加载页面上的每张图片、每个字体、脚本和视频,Chrome 还会发出自己的请求。在我们的测试中,Google Chrome 在空白页上闲置 30 秒,一次通过代理打开了 21 个连接,另一次 22 个,大多指向 Google 服务;加上 --disable-background-networking 后为 13 个。Playwright 的 Chromium 打开了 4 或 5 个。

  • 按 GB 计费的套餐:这些全部计入流量。住宅代理每 GB $0.60 起,流量包 $5 起。在共享池覆盖的国家,按 GB 计费的移动 IP 每 GB $3 起。先用我需要多少 GB 代理流量估算,再按在 Playwright 中拦截图片和字体减少图片和字体。连接智能体时的拦截效果我们没有测量。
  • 按天租用移动代理:按时间计价,不限流量,每天 $9 起。页面再重也不影响价格;租用 1 天移动代理对比了它与 30 天的租期。

故障排查

  • 代理需要认证。使用 Playwright 启动器时,错误的密码在 Chromium 159 中表现为 Page.goto: Timeout 30000ms exceeded,在 Chrome 157 中表现为 net::ERR_HTTP_RESPONSE_CODE_FAILURE,而不是 407。先用一条 curl 请求检查凭据,再阅读如何修复代理错误 407。
  • net::ERR_NO_SUPPORTED_PROXIES。凭据写在了 --proxy-server 里。把它们交给 Playwright 的 proxy 选项,或使用上面的转发器。
  • 隧道连接失败。net::ERR_TUNNEL_CONNECTION_FAILED 表示代理拒绝了 CONNECT;修复 ERR_TUNNEL_CONNECTION_FAILED会解读它的应答。轮换刚结束时出现的 502 或 503,见隧道连接失败:502/503。
  • 超时。用诊断代理超时区分是代理慢还是页面慢。
  • 代理好像被忽略了。智能体自己的 Python 网络请求(http_get、requests)在你的电脑上运行:在我们的测试中,http_get 返回的是本机地址,而页面显示的是代理地址,文档对云端浏览器也是这样说的。请在任务里写明“在浏览器中”,并检查是否传入了 browser=Browser(cdp_url=...):没有它,Agent 会启动云端浏览器。对于读取代理环境变量的工具,请看代理环境变量。
  • DNS 泄露。我们的代理日志显示,无论 HTTP 还是 SOCKS5,Chrome 都把主机名交给代理,所以目标地址不会在本地解析;Chromium 文档对 SOCKS5 也这样写。socks5 与 socks5h 实测列出了行为不同的客户端。
  • WebRTC 泄露。默认情况下,在两个浏览器中页面都能通过 WebRTC 读到本机真实的公网 IPv4 和 IPv6 地址,而常被推荐的参数 --force-webrtc-ip-handling-policy=disable_non_proxied_udp 没有任何效果。把配置文件偏好 webrtc.ip_handling_policy 设为 disable_non_proxied_udp(fresh_profile() 写入的就是它)后,所有候选地址都消失了。它就是 Chrome WebRtcIPHandling 策略背后的设置,即 RFC 8828 中的“force proxy”模式。可以用 IP、DNS 与 WebRTC 泄露检测或我们的代理检测工具检查结果。

常见问题

如何在 Browser Use 中设置代理?

用 Playwright 的 proxy 选项和一个调试端口启动 Chromium,再把 Browser(cdp_url='http://127.0.0.1:9242') 传给智能体。1.0 版没有为本地浏览器提供代理选项。

Browser Use 支持 SOCKS5 代理吗?

支持不带密码的:socks5://HOST:PORT。Chromium 无法发送 SOCKS5 凭据,所以请使用 HTTP 端点或本地转发器。

可以在 Browser Use 中使用住宅代理吗?

可以。把网关写进 proxy 选项,把粘性会话 ID 写进用户名,这样智能体保持登录期间出口不变。

可以在 Browser Use 中使用移动代理吗?

可以。使用设备的 HTTP 端口、用户名和密码,并在任务之间轮换它的运营商 IP。

AI 智能体用哪种代理最好?

取决于任务:独享移动代理适合长时间登录的会话或指定运营商,住宅代理适合在多个国家运行的大量短任务。任何代理都解决不了浏览器指纹导致的拦截。

Browser Use Cloud 自带代理吗?

自带住宅代理,默认在美国,也可以选择其他国家。在那里使用自定义代理属于企业功能。

为什么智能体显示的还是我的真实 IP?

通常是因为请求不是从浏览器发出的:智能体的 Python 辅助函数在你的电脑上运行。请让它在浏览器中打开页面,并用 fresh_profile() 阻止 WebRTC 泄露。

让智能体用上运营商 IP。ipvolt 独享移动代理每天 $9 起,不限流量,支持 HTTP 和 SOCKS5。免费的 Proxy Toolkit MCP 为 AI 编程助手提供代理配置、错误诊断和这些指南。按 GB 计费的住宅代理每 GB $0.60 起,流量包 $5 起。在价格页比较所有选项,并用代理检测工具测试任何代理。智能体也可以通过 API 自行租用,并用自己的 USDC 充值。

租用 1 天移动代理:德国,O2,$9

无需注册账号。

参考来源与延伸阅读

本指南参考的技术资料。请以你所安装版本的文档以及代理服务商支持的配置为准。