> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/cn/agent-browser/persistent-sessions-and-profiles.md).

# 持久会话和配置文件

了解 Oxylabs 代理浏览器上的持久（粘性）会话和持久配置文件。重新连接到进行中的会话，并在多个会话中复用您的 Cookie 或本地存储。

管理长时间运行的多阶段自动化工作流，或在不同连接序列中维护已登录的用户状态，需要持久化浏览器状态。Oxylabs Agent Browser 提供两种高级持久化系统：

<table data-header-hidden><thead><tr><th width="178"></th><th></th></tr></thead><tbody><tr><td><a href="#persistent-sessions-sticky-sessions"><strong>持久会话</strong></a></td><td>在客户端断开连接期间，保持远程浏览器环境持续运行。</td></tr><tr><td><a href="#persistent-profiles"><strong>持久配置文件</strong></a></td><td>保存和恢复 Cookie、本地存储和浏览器缓存。</td></tr></tbody></table>

## 持久会话

持久（粘性）会话通过定义自定义的 `session_name` 添加到你的连接 URL：

```bash
wss://USER:PASS@hb.oxylabs.io?session_name=checkout-flow-test
```

{% hint style="info" %}
持久会话已 **默认启用** 对所有用户可用，默认限制为 **5 个并发会话**. 如果你需要更高的限制，请联系 Oxylabs 支持（[在线聊天](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理。
{% endhint %}

<table><thead><tr><th width="127">参数</th><th width="534">说明</th><th width="98">类型</th></tr></thead><tbody><tr><td><code>session_name</code></td><td>定义后，会话可持续到最大存活时间（TTL）（最长 24 小时或直到停止）。使用相同的 <code>session_name</code> 以重新附加相同的会话 ID 和现有标签页。支持的格式： <code>^[A-Za-z0-9-]{3,36}$</code></td><td>字符串</td></tr><tr><td><code>keep_alive</code></td><td>当 <code>false</code> （默认），调用 <code>browser.close()</code> 会回收并关闭会话。<br>当 <code>true</code>，断开连接后会话仍保留在云端（最长 10 分钟）。<br>需要 <code>session_name</code>.</td><td>布尔值</td></tr></tbody></table>

### 重新连接到现有标签页

```javascript
// Reconnect to existing session
const browser = await chromium.connectOverCDP(endpoint);
const ctx = browser.contexts()[0];
const page = ctx.pages().find(p => p.url().includes("http://example.com"));
```

## 持久配置文件

持久配置文件上限为 **默认启用** 对所有用户可用，默认限制为 **5 个配置文件**. 可使用命名配置文件保存 Cookie 和 localStorage，并在全新会话中恢复。以下参数可让你在跨会话保持登录状态，而无需每次重新认证：

<table><thead><tr><th width="191">参数</th><th width="456">说明</th><th width="102">类型</th></tr></thead><tbody><tr><td><code>o_profile</code></td><td>使用命名配置文件保存/恢复 Cookie 和 localStorage（距上次使用起 14 天内）。支持的格式： <code>^[a-zA-Z0-9][a-zA-Z0-9_-]{2,35}$</code></td><td>字符串</td></tr><tr><td><code>o_profile_save</code></td><td>在会话期间或结束时强制保存配置文件。默认： <code>false</code>.</td><td>布尔值</td></tr><tr><td><code>proxy_resi_ses_id</code></td><td>用于在跨会话固定住宅出口 IP 的自定义会话 ID。支持的格式： <code>^[A-Za-z0-9]{3,36}$</code>.</td><td>字符串</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>以分钟为单位保持固定的住宅代理出口 IP 的时长。最小 <code>1</code>，最大 <code>1440</code> （24 小时）。</td><td>整数</td></tr></tbody></table>

{% hint style="info" %}
超过 `max_profiles` 限制 `5` 会返回 `403 配置文件限制已达上限（maximum）：配置文件限制已达上限` 错误。你可以直接在仪表板（`hb.oxylabs.io/dashboard`）中查看并删除已保存的配置文件（如果你达到限制），或者复用一个稳定的配置文件名称。联系 Oxylabs 支持（[在线聊天](https://oxylabs.io/) 或 [电子邮件](mailto:support@oxylabs.io)）或你的专属客户经理，如果需要更高的限制。
{% endhint %}

### 可靠的跨会话恢复 <a href="#reliable-cross-session-restore" id="reliable-cross-session-restore"></a>

对于具有严格机器人监测系统的网站，仅保存 Cookie 还不够。如果恢复的配置文件从不同的住宅出口 IP 连接，你的 Cookie 可能会失效，从而出现空白页面或安全验证页面。

为确保登录一致，请将配置文件与固定的住宅出口 IP 配对：

```javascript
// Session 1: Authenticate and back up state
const connectionOne = "wss://USER:PASS@hb.oxylabs.io?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";

// Session 2: Restore profile with the exact same IP session context
const connectionTwo = "wss://USER:PASS@hb.oxylabs.io?o_profile=my_user_profile&proxy_resi_ses_id=ip_session_abc&proxy_resi_ses_time=120";
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/cn/agent-browser/persistent-sessions-and-profiles.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.