代理浏览器

基于云的无头浏览器，内置自适应安全、CAPTCHA 管理和住宅代理。使用代码示例进行测试，并通过高级功能进行自定义。

Agent Browser 让您无需在本地管理远程实例，即可运行和控制用于基于浏览器的自动化、测试和网页抓取的远程实例。它提供内置自适应安全、自动 CAPTCHA 处理、地理定位、集成式住宅代理、会话录制、粘性会话和持久化配置文件。

支持的库

Agent Browser 可与任何支持以下协议的库配合使用 Chrome DevTools Protocol (CDP)，包括：

• Playwright （Python 和 Node.js）
• Puppeteer （Node.js）
• 其他与 CDP 兼容的自动化框架

连接详情

注意： Agent Browser 正在迁移到新基础设施。请在 ubc.oxylabs.io 之前将您的连接字符串更新为 hb.oxylabs.io ，截止日期为 10 月 1 日。自 10 月 1 日起，发送到旧域名的流量将自动路由到新域名。

控制面板和会话检查工具也已从 headlesify.io 迁移至 hb.oxylabs.io。请参阅 会话检查和录制 了解详情。

字段	说明
协议	wss:// （安全 WebSocket）
主机（Chromium）	hb.oxylabs.io
身份验证	在 URL 中使用用户信息 – wss://USERNAME:PASSWORD@host。必须包含用户名后缀令牌（例如 user_ab12）。不支持基于请求头的身份验证。
传输方式	CDP – chromium.connectOverCDP （Playwright）/ puppeteer.connect （Puppeteer）。
域名	oxylabs.io – 用于连接端点（例如 hb.oxylabs.io）、控制面板（hb.oxylabs.io/dashboard）和会话检查（hb.oxylabs.io/novnc).
速率限制	100 个并发会话， 10 个会话每秒。 查看更多.

功能

Oxylabs Agent Browser 包含内置的云原生功能，设计为通过 WebSocket 连接 URL 的查询参数使用。

CAPTCHA 处理	自动、实时的 CAPTCHA 处理和监控（默认：关闭）。
代理和地理位置定位	通过特定国家、州或城市路由会话。
设备模拟	模拟特定设备的指纹和视口。
会话检查（VNC）	监控实时无头浏览器会话。
会话录制	以视频格式录制浏览器会话。
持久会话	创建和管理粘性浏览器实例。
持久化配置文件	跨会话保存和恢复 Cookie/localStorage。

传递参数

通过将查询参数直接附加到您的安全 WebSocket 端点来启用和配置所有功能，使用和号（&).

# 示例：连接到已启用美国地理位置定位和 CAPTCHA 处理的 Chrome
wss://USER:[e-mail]?p_cc=US&solve_captcha=true

代码示例

以下是初始化云托管浏览器会话的基本示例：

Python（Playwrigth）

from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()

JavaScript（Playwright）

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

JavaScript（Puppeteer）

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

注意： 示例仅使用 USERNAME 和 PASSWORD 以便于阅读。在实际项目中，请通过 process.env.OXYLABS_USERNAME / process.env.OXYLABS_PASSWORD从环境变量加载它们，例如通过 .env 文件。

JavaScript： 如果遇到 TLS/证书错误，请在 Node.js 中 require Playwright 前使用 NODE_TLS_REJECT_UNAUTHORIZED="0" 标志。仅适用于本地测试。在生产环境中，应将信任范围限定为特定连接，或将提供商的 CA 证书添加到您的信任存储中。

参数参考

参数	说明	类型
p_cc	国家地理位置，采用 ISO 3166-1 alpha-2 双字母代码（例如， US, DE).	字符串
p_state	小写的州地理位置（例如， texas）。若同时使用，将覆盖 p_cc 。 支持的州列表.	字符串
p_city	城市地理位置，小写， _ 空格使用 new_york). p_cc / p_state （例如）是必需的。	字符串
p_device	设置设备指纹、视口和用户代理。支持 desktop （默认）和 mobile.	字符串
solve_captcha	页面加载时自动实时解决 CAPTCHA。默认值： false.	布尔值
record	录制无头会话视频。默认值： false.	布尔值
record_name	为录制命名以便于查找（^[a-zA-Z0-9_-]{1,64}$).	字符串
session_name	粘性会话 – 重新连接到相同的实时远程浏览器（^[A-Za-z0-9-]{3,36}$，支持连字符，不支持下划线）。最大 TTL 为 24 小时。	字符串
keep_alive	设置为 true时，在客户端断开连接后保持远程浏览器实例运行。默认值： false.	布尔值
o_profile	持久化配置文件 – 使用命名配置文件（ localStorage 保存/恢复 Cookie 和^[A-Za-z0-9_-]{1,36}$).	字符串
o_profile_save	持久化配置文件 – 在会话期间或结束时强制保存配置文件。默认值： false.	布尔值
proxy_resi_ses_id	用于跨会话固定住宅出口 IP 的自定义会话 ID（^[A-Za-z0-9]{3,36}$).	字符串
proxy_resi_ses_time	以分钟为单位，保持固定住宅代理出口 IP 的持续时间。最小值 1，最大值 1440 （24 小时）。	整数

推荐设置

优化流量

抓取动态页面通常会导致浏览器下载不必要的资源，例如大型媒体文件、跟踪脚本、图片和字体。这会消耗带宽并减慢执行速度。

您可以在这些请求消耗资源前以编程方式拦截并中止它们：

Python（Playwright）

# Abort heavy assets to save bandwidth and improve speeds
def block_resources(route):
    if route.request.resource_type in ["image", "stylesheet", "media", "font"]:
        route.abort()
    else:
        route.continue_()

page.route("**/*", block_resources)

JavaScript（Playwright）

// Abort heavy assets to save bandwidth and improve speeds
await page.route("**/*", (route) => {
    const type = route.request().resourceType();
    if (["image", "stylesheet", "media", "font"].includes(type)) {
        return route.abort();
    }
    return route.continue();
});

错误处理和重试

网络波动和每秒 10 个会话的速率限制意味着单次 connectOverCDP 调用可能会暂时失败。请在连接外层加入 重试 并使用指数 退避，同时为每次尝试设置超时限制。以下示例使用标准 Playwright API：

const { chromium } = require("playwright");

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(endpoint, { maxRetries = MAX_RETRIES } = {}) {
    let lastError;
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            // Cap how long a single connection attempt may take.
            return await chromium.connectOverCDP(endpoint, { timeout: 60_000 });
        } catch (err) {
            lastError = err;
            // Exponential backoff with jitter — backs off when you hit the
            // 10-new-sessions/second rate limit instead of hammering the endpoint.
            const delay = BASE_DELAY_MS * 2 ** attempt + Math.random() * 250;
            console.warn(
                `connect attempt ${attempt + 1} failed: ${err.message}; ` +
                `retrying in ${Math.round(delay)}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, delay));
        }
    }
    throw lastError;
}

资源清理

完成后始终关闭浏览器，即使您的自动化流程在中途抛出异常。使用 try { ... } finally { ... } 代码块，以确保在所有路径上执行清理：

const browser = await connectWithRetry(endpoint);
try {
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    // ... your automation ...
} finally {
    // Runs even if the block above throws. Without this, a session left open
    // after an exception lingers and counts against your 100 concurrent-session limit.
    await browser.close();
}

如果在连接和关闭之间发生异常且未进行清理，远程会话将保持打开状态，并占用您的一个 100 个并发会话 配额，直至被回收。在高负载下泄漏会话可能会耗尽限制并阻止新连接。

需要启用某项功能？

某些 Agent Browser 功能默认受限。要调整限制，请联系 Oxylabs 支持（在线聊天 或 电子邮件）或您的专属客户经理：

• 更多持久化配置文件 – 将账户默认的 5 个已保存配置文件上限提高。
• 更多持久化会话 – 将账户默认的 5 个并发持久化会话上限提高。
• 受限目标 – 通过 KYC 流程解锁更多目标类别。
• 更高的速率限制 – 提高到超过 100 个并发会话 / 每秒 10 个。