Baizhi Cloud Browser

클라우드 브라우저 세션, 저장된 로그인 상태, 사람 개입 전환 및 다운로드를 관리합니다. 페이지 작업에는 자체 Baizhi API 키와 CDP 클라이언트를 사용하세요. 브라우저 런타임은 과금됩니다.

호스팅형 MCP 서버

npx add-mcp 'https://capybrowser.app.baizhi.cloud/mcp'

Claude Code, Codex, Cursor 등에 설치됩니다

문서

让当前 Agent 完成第一个网页任务

在原 Agent 对话提任务。服务 https://capybrowser.app.baizhi.cloud，MCP 加 /mcp。MCP/HTTP 管理运行，网页操作仍需兼容 CDP 客户端。参考、Skill按需查。

准备 API 密钥

可用本应用 API 密钥或百智云个人中心 API KEY；已有包含云浏览器的工具包接入可沿用。范围以实际配置为准，MCP 管理不等于具备 CDP 操作能力。

将说明和任务交给 Agent，按它的引导单独配置密钥；已有可用接入不重配。直接接入方式：

MCP：服务地址 https://capybrowser.app.baizhi.cloud/mcp，HTTP Header 为 Authorization: Bearer <API_KEY>。
HTTP：通过项目环境变量或秘密管理工具提供密钥，使用同一鉴权头。配置示例。

密钥不贴对话、代码或日志。配置、只读鉴权不收运行费，浏览器就绪后计费。

收费创建前准备

任务与工具：备齐目标、输入、成果标准和授权预算；缺页面操作能力先补齐，不先创建 Session。不强迫装插件、管理 SDK、本机 Chromium 或新工程。
入口与密钥：核对服务、环境和授权用途，符合才复用。获授权本服务 HTTP 密钥可直接调用，无需重配 MCP；不覆盖其他工具箱配置或向其发 Key。范围不明先确认，不合并资源/费用；不同 Key 不证明不同账号。密钥通过客户端配置、环境变量或秘密管理提供，不手填 X-Baizhiyun-*。
版本、身份、价格：公开 GET /version；GET /openapi/v1/me 或 browser_auth_check 验证凭据，缺字段按未知处理，不查余额。GET /openapi/v1/pricing 或 browser_pricing 读价格。均不创建运行或产生运行费。

Profile 对应“浏览器存档”，Session 是一次运行。临时任务可不带存档；需复用状态时创建前关联获授权存档，网页内另核对登录。指定线路先查目录；只有 default 即只有默认出口，不代表固定或独立 IP。未指定时沿用 Profile 偏好或默认出口；要求“以后都用”才保存偏好。存档与线路参考。

创建一次，连续完成任务

已有任务直接用现有工具，无需付费教学或另开发脚本；不为同一任务跨入口重复创建。

操作	已有 MCP	HTTP（路径相对 `/openapi/v1`）
创建、查询	`browser_create_session`、`browser_get_session`	`POST /browser/sessions`、`GET /browser/sessions/:id`
取得控制	`browser_control`	`POST /browser/sessions/:id/control`
结束	`browser_stop_session`	`DELETE /browser/sessions/:id`

为一次逻辑创建保存稳定幂等键（8–128 字符）：HTTP 传 Idempotency-Key，MCP 传 idempotency_key。按任务与预算设 max_seconds（秒），为下载、收尾留余量，无需跑满。记录 session_id；创建结果不明只用原键、原正文恢复，不换键重开。
starting 时有界等待，原 Session 为 ready 且未到期才取得 cdp_url；其他状态不操作网页。用 Playwright chromium.connectOverCDP(cdp_url) 或现有兼容客户端，复用默认 context 的页面。CDP 地址仅供一次建连，不是观看链接。
**用户停止条件优先；未触发且任务未完成、原运行仍 ready、未到期时，在同一 Session 连续观察、操作、核对。**不因读表头、见按钮、截图或可恢复的单步错误就结束重开。操作后核对页面与选中值，提交后确认条件和结果符合目标；部分完成说清缺口，读默认价格不能报成改配置比价成功。浏览器内 SDK 也可交付有效结果，如实说明方法。建连或页面出现不代表任务完成。
**任务完成、触发用户停止条件、无法继续或到期时统一收尾，失败也清理。**所需下载须在停止或到期前通过制品接口取回并核对长度、SHA-256；到期后不可再取，缺失如实报告。在 finally 有界断开客户端，再请求停止自己创建的 Session；断开失败也尝试停止。仅连接其他流程拥有的 Session 不自行停止，除非用户明确交付结束责任。人工处理中保留原运行，规则见下。

停止受理或到期后不再操作网页。有界查询原 Session：released 才证明释放，断开或停止受理均不证明。关联 Profile 时另查 save_status，仅 saved 可报本次保存成功。费用另按 billing.status：settled 用 actual_charge_centipoints / 100 报实际积分，waived 报免收，其余待确认；保存、释放、结算不互相证明。等待 Agent、人工处理和断线期间仍计费；停止请求受理或到期后不再收运行费。未核清项保留记录并报告。

HTTP 核对状态及 code=ok 后取 data；MCP 即使 HTTP 200，仍检查 result.isError，普通工具解析 result.content[].text。下载按制品接口处理。

断线、观看与人工处理

断线先查原 Session 及 human_action_status；仍 ready、未到期且无人工操作才重取控制、观察原页面，不新建或重放结果未知的写操作。健康连接中不申请备用 /control，成功会替换 grant 并关闭旧连接。409 control_busy 不撤销有效旧地址；地址丢失且未使用时，GET 原 Session，以当前 control_grant.id 作 expected_grant_id 调用 browser_recover_control，遵守同身份/凭据规则。claimed 或人工操作中不可 recover；结果未知先查，不循环换发。

要求观看时为原 Session 提供真实 page_url，默认只读 view；明确要操作才选 view_takeover，不强制观看、不另开运行。确需本人处理可直接用 browser_begin_handoff 或 POST /openapi/v1/browser/sessions/:id/handoff，给本人本次链接及原因，无需先观看。见观看与接管。

人工等待/操作中暂停网页操作和自动清理，保留原 Session 及清理责任。给链接时说明：完成后点“完成并交还 Agent”，将页面回复发回原对话；服务不自动通知第三方 Agent。确认人工处理结束、原运行仍 ready 且未到期后重取控制、观察再继续；状态未知则有界查询并报告，不猜作已交还。运行到期仍须收尾。

可选：临时公开页读取样例

官方 first-run.mjs仅作临时公开页读取：固定 max_seconds=300，不带存档或指定线路；核对标题正文后收尾，失败也清理。已记 Session ID 时重跑只核对收尾，不再执行网页步骤；创建结果不明且未记 ID 时，用原键、原正文恢复。

样例需 Node.js 20+；在脚本目录检查，成功跳过安装，目录/ESM 问题先修：

node --input-type=module -e 'import { chromium } from "playwright-core"; if (typeof chromium.connectOverCDP !== "function") process.exit(1); console.log("CDP client ready");'

仅确认缺包才执行；不下载本机浏览器，不运行 playwright install 或 chromium.launch()：

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --no-save --package-lock=false --ignore-scripts playwright-core@1.64.1

npm 超时且环境允许时可仅为本次安装追加 --registry=https://registry.npmmirror.com。收费前安全配置 CAPYBROWSER_API_KEY，不在命令或对话贴真实 Key，再运行：

curl -fsS https://capybrowser.app.baizhi.cloud/docs/first-run.mjs -o first-run.mjs
curl -fsS https://capybrowser.app.baizhi.cloud/docs/agent-guide.mjs -o agent-guide.mjs
export CAPYBROWSER_BASE_URL="https://capybrowser.app.baizhi.cloud"
CAPYBROWSER_EXPECT_TITLE='Example Domain' CAPYBROWSER_EXPECT_TEXT='documentation examples' node first-run.mjs 'https://example.com/'

样例含密钥、价格和幂等检查；H1 可缺，登录/挑战页不算结果。导航失败看 navigation_error 与原 session_id，释放、费用看 cleanup；不猜封锁、不换键重开。

0600 状态文件 .capybrowser-first-run.json 绑定服务、API 密钥与目标；同路径并发会被锁拒绝。新任务另设 CAPYBROWSER_STATE_FILE；原任务未核清释放与费用前不删状态换键。跨 Agent 串行复用须先确认保存与释放，再使用同一用户/团队内有权访问的 Profile。

新任务收费前，样例独立缓存可选说明修订：首次建基线，同修订安静，恢复/收尾跳过，失败不阻断；仅介绍相关变化。按需发现、版本记录与 OpenAPI按需查阅。