# 云端浏览器 (/docs/cloud/services/browser)



云端浏览器是一个在云上运行的 Chrome，可以用 Playwright 或 Puppeteer 直接连接操控，也可以在 Console 实时观看与接管。

## 三种用法 [#三种用法]

以下示例在 Node.js 中运行。先设置 `PRAXIS_API_KEY`，将代码保存为 `.mjs` 文件，再用 `node` 执行。只需安装客户端包，无需下载本地 Chrome。

```bash
export PRAXIS_API_KEY="你的 API Key"
npm install playwright @browserbasehq/sdk
```

### 一步连接 [#一步连接]

连接 `wss://api-develop.deepraxis.ai/browser/v1/connect` 即可新开一个浏览器。`?session=<id>` 连接已有会话；`?name=<名称>` 有就连接，没有就创建。名称可用 1–128 个字母、数字或 `. _ : -`，不能同时传 `session` 和 `name`。

```javascript
import { chromium } from "playwright";

const headers = { Authorization: `Bearer ${process.env.PRAXIS_API_KEY}` };
const browser = await chromium.connectOverCDP(
  "wss://api-develop.deepraxis.ai/browser/v1/connect",
  { headers },
);
const cdp = await browser.newBrowserCDPSession();
const session = await cdp.send("Praxis.getSession");
console.log(session.sessionId, session.liveViewUrl, session.consoleUrl);
try {
  const page = await browser.contexts()[0].newPage();
  await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
  console.log(await page.textContent("body"));
} finally {
  await browser.close();
  // 用完立即释放，停止计费。
  const closed = await fetch(
    `https://api-develop.deepraxis.ai/browser/v1/sessions/${session.sessionId}`,
    { method: "POST", headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ status: "REQUEST_RELEASE" }) },
  );
  if (!closed.ok) throw new Error(await closed.text());
}
```

新建时还可带 `context`、`persist`、`timeout`（秒）、`idle`（毫秒）、`labels` 和 `viewport`。后两项用 `JSON.stringify` 配合 `URLSearchParams` 编码；连接已有会话时，这些新建参数不生效。创建会话返回的 `connectUrl` 自带凭证，连接时无需再带 API Key；不要公开此地址。

### Browserbase 官方 SDK [#browserbase-官方-sdk]

使用自己的 API Key，把官方 SDK 的 `baseURL` 设为 `https://api-develop.deepraxis.ai/browserbase`。SDK 自动发送 `X-BB-API-Key`。无需 Browserbase 项目，`projectId` 可省略。

```javascript
import Browserbase from "@browserbasehq/sdk";
import { chromium } from "playwright";

const bb = new Browserbase({
  apiKey: process.env.PRAXIS_API_KEY,
  baseURL: "https://api-develop.deepraxis.ai/browserbase",
});
const session = await bb.sessions.create({ timeout: 300, keepAlive: true });
try {
  const browser = await chromium.connectOverCDP(session.connectUrl);
  try {
    const page = await browser.contexts()[0].newPage();
    await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
    console.log(await page.textContent("body"));
  } finally {
    await browser.close();
  }
} finally {
  await bb.sessions.update(session.id, { status: "REQUEST_RELEASE" });
}
```

可调用的端点见 [Browserbase 兼容 API](/docs/api/compatible/browserbase)。代理、反检测、扩展和 Selenium 不可用；`region`、`solveCaptchas` 当前接受但忽略，不会选区域或代解验证码。

### REST 先创建再连接 [#rest-先创建再连接]

`POST /browser/v1/sessions` 返回的 `connectUrl` 包含连接凭证，有效期覆盖会话寿命。直接交给 Playwright 或 Puppeteer，无需再传 API Key。

```javascript
import { chromium } from "playwright";

const base = "https://api-develop.deepraxis.ai/browser/v1";
const headers = {
  Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`,
  "Content-Type": "application/json",
};
const response = await fetch(`${base}/sessions`, {
  method: "POST", headers, body: JSON.stringify({ timeout: 300, keepAlive: true }),
});
if (!response.ok) throw new Error(await response.text());
console.log("X-Request-Id:", response.headers.get("X-Request-Id"));
const session = await response.json();
try {
  const browser = await chromium.connectOverCDP(session.connectUrl);
  try {
    const page = await browser.contexts()[0].newPage();
    await page.goto("https://api-develop.deepraxis.ai/meta/v1/health");
    console.log(await page.textContent("body"));
  } finally {
    await browser.close();
  }
} finally {
  const closed = await fetch(`${base}/sessions/${session.id}`, {
    method: "POST", headers, body: JSON.stringify({ status: "REQUEST_RELEASE" }),
  });
  if (!closed.ok) throw new Error(await closed.text());
}
```

完整请求参数见[云端浏览器 API](/docs/api/native/browser)。Puppeteer 使用 `puppeteer.connect({ browserWSEndpoint: session.connectUrl })` 连接同一地址。

## 实时观看与接管 [#实时观看与接管]

打开 [Console](https://console-develop.deepraxis.ai) 的 **浏览器 › 会话**，选择会话即可观看并接管。程序也可通过 CDP 命令 `Praxis.getSession` 取得 `sessionId`、`liveViewUrl` 和 `consoleUrl`。需要用户完成登录或确认操作时，调用[请求人工接管](/docs/api/native/browser/browserRequestHandoff)，完成后调用[完成人工接管](/docs/api/native/browser/browserCompleteHandoff)。

会话状态为 `PENDING`、`RUNNING`、`ERROR`、`TIMED_OUT` 或 `COMPLETED`。API 创建且 `keepAlive=false` 的会话在客户端断开且无人观看后结束；一步连接和 Console 打开的会话默认在无人连接或观看 5 分钟后释放。单次最长 6 小时。没有暂停或休眠；下次继续使用登录态，需要 Context。

## 登录态 [#登录态]

先[创建 Context](/docs/api/native/browser/browserCreateContext)，再在创建会话时传 `browserSettings.context`。`persist: true` 会在会话关闭时保存 cookie 与 localStorage；不保存 IndexedDB。同一登录态正在被写入时，另一会话可能收到 `409 CONTEXT_LOCKED`。

```javascript
// 接上面的 REST 初始化代码；contextId 为创建 Context 返回的 id。
const response = await fetch(`${base}/sessions`, {
  method: "POST", headers,
  body: JSON.stringify({
    timeout: 300,
    browserSettings: { context: { id: contextId, persist: true } },
  }),
});
```

## 计费与限制 [#计费与限制]

* **$0.12 / 浏览器小时**，按秒计费，单会话 1 分钟起。平台原因导致的失败只按实际秒数计费；释放后不再计费。
* 每个账户默认最多同时 **10 个会话**，每个会话最长 **6 小时**。
* 不支持代理、验证码代解、反检测、选区域或扩展。代理、反检测和扩展等不支持的配置返回 `501`；`region`、`solveCaptchas` 当前接受但忽略。
* 部分网站（如 Google、百度）会把云端浏览器识别为机器人。
* 排查请求时保留响应头 `X-Request-Id`。