Baizhi Cloud Browser

Manage cloud browser sessions, saved login state, human handoff and downloads. Use your own Baizhi API key and a CDP client for page actions; browser runtime is billed.

View on baizhi.cloud

Hosted MCP Server

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

Installs into Claude Code, Codex, Cursor and more

Documentation

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

服务根地址：https://capybrowser.app.baizhi.cloud。继续在原 Agent 对话中提出网页任务；百智云云浏览器（Baizhi Cloud Browser）提供云端浏览器。MCP/OpenAPI 管理运行，网页操作仍需 CDP 客户端。限制与恢复按需查完整接入参考，可安装的 Agent Skill 见 skills.md，首次不必通读。

创建运行前，先确认三件事

目标与执行能力：用户已给网址或任务，Agent 有兼容 CDP 客户端或能运行页面代码；缺客户端先准备，不要先创建计费 Session。首次无需新建工程、管理 SDK 或本机 Chromium。
入口与凭据：本页 MCP 是 https://capybrowser.app.baizhi.cloud/mcp；先核对现有配置的服务地址、环境和用户允许的凭据用途，不能仅凭 browser_* 名称认成同一服务。符合才复用；其他工具箱不自动替换配置，不把用户新 Key 发往其域名。用户已授权官方 HTTP Key 时可直接走本页 /openapi/v1，不强迫重配 MCP。范围不明先确认，不合并两边资源/费用；不同 Key 也不证明不同账号。
凭据与价格检查：Key 只作 Authorization: Bearer <API_KEY> 放安全配置，不贴对话/代码/日志，不手填 X-Baizhiyun-*。GET https://capybrowser.app.baizhi.cloud/version 公开；GET /openapi/v1/me 或 browser_auth_check 验证本次凭据，并可返回已有账号/团队归属及非秘密凭据记录引用；缺字段或旧部署按未知处理，不查询余额。GET /openapi/v1/pricing 读价格。均不创建运行或产生浏览器运行费。一项任务只选一种管理入口创建一次。

HTTP 新 Agent：先运行官方首跑

已有匹配 MCP 的 Agent 沿用下表，不再运行本段。HTTP 新 Agent 优先复用官方脚本，不先手写生命周期。需要 Node.js 20+；缺包才安装 playwright-core@1.64.1，均在收费创建前完成，不下载本地浏览器、不运行 playwright install 或 chromium.launch()。

# 在放置脚本的 Node 目录检查；成功跳过安装，不连接浏览器。
node --input-type=module -e 'import { chromium } from "playwright-core"; if (typeof chromium.connectOverCDP !== "function") process.exit(1); console.log("CDP client ready");'
# 仅缺包时安装；已有兼容包跳过。目录/语法问题先修，不查浏览器缓存。
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install --no-save --package-lock=false --ignore-scripts playwright-core@1.64.1
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_API_KEY，不将真实 Key 写入命令或对话。
CAPYBROWSER_EXPECT_TITLE='Example Domain' CAPYBROWSER_EXPECT_TEXT='documentation examples' node first-run.mjs 'https://example.com/'

仅当 npm 超时且环境允许镜像时，对本次安装追加 --registry=https://registry.npmmirror.com 重试；不执行 npm config set registry 或更改全局配置。

官方脚本已含检查凭据、读价、幂等与有界 finally，失败也清理原运行。上方 ESM 具名导入可用，出错先查目录与执行模式。首跑核对示例标题和真实正文，H1 可缺；换真实任务 URL 时同步改预期文字，不把挑战/登录页当结果。导航失败看 navigation_error 的阶段与原 session_id，另看 cleanup 的释放和费用；不猜封锁、不换键重开。

已有 MCP：沿用原入口

本次操作	已配置 MCP	直接 HTTP
凭据检查与价格	`browser_auth_check`、`browser_pricing`	`GET /openapi/v1/me`、`GET /openapi/v1/pricing`
创建并等待	`browser_create_session`（传 `idempotency_key`）、`browser_get_session`	`POST /browser/sessions`（传 `Idempotency-Key`）、`GET /browser/sessions/:id`
取得控制、结束	`browser_control`、`browser_stop_session`、`browser_get_session`	`POST /browser/sessions/:id/control`、`DELETE /browser/sessions/:id`、`GET /browser/sessions/:id`

表中 /browser/* 相对 /openapi/v1。MCP 使用本列工具；已执行官方 HTTP 脚本的任务不要再按表另建运行。

POST /handoff 或 browser_begin_handoff 可直接发起人工处理，不必先观看。想看页面可告诉 Agent“让我看看”；默认只读，明确要求才能签可接管链接。拿到真实链接才提供，沿用原 Session，不为观看另开运行。见观看与主动接管。

需要网络出口时，告诉 Agent“这次用指定线路”；先查询当前可用目录，只有 default 就仍只有默认出口，不代表已有固定或独立 IP。仅明确要求“以后都用”时才保存 Profile 偏好；未指定时沿用已有偏好或默认出口。接口见网络出口参考。

生命周期与恢复（按需核对）

为一次逻辑创建生成并保存一个 Idempotency-Key（8–128 字符），调用 POST /openapi/v1/browser/sessions，例如正文 {"max_seconds":300}，从 HTTP 成功响应的 data.session_id 记住原 Session。请求结果不明时用原键、原正文恢复，不能换键再开一台。
有界轮询 GET /openapi/v1/browser/sessions/:id 到 data.status=ready；遇到 failed、released、超时或到达 expires_at，停止页面操作。starting 不等于就绪。
用 Playwright chromium.connectOverCDP(cdp_url) 或现有兼容客户端连接，复用默认 context 的页面，访问目标并核对真实内容。地址只供一次建连，不是观看链接；断线先查原 Session，再按控制规则恢复，不新建运行。
正常或异常都在 finally 有界断开客户端，再 DELETE /openapi/v1/browser/sessions/:id 结束自己创建的运行；即使断开失败也要尝试停止。查询同一 Session 到 released 才能确认资源已释放。费用另看 billing.status：settled 按 actual_charge_centipoints / 100 报实际积分，waived 报免收，其他状态标待确认。等待 Agent、人工处理和断线期间仍计费；停止受理或到期后不再收运行费。只连接别人拥有的 Session 时，不自行结束。

人工接管导致的 CDP 断开不属于上述自动结束分支：先查询原 Session 的 human_action_status，人工等待或操作期间保留原运行；确认交还后重新取得控制并检查页面。服务不会代替调用方暂停或通知第三方 Agent。

HTTP 检查状态及 code=ok 后取 data；MCP 即使 HTTP 200，仍检查 result.isError 并解析 result.content[].text。建连或 Session ready 不等于任务完成。

健康连接中不要再申请 /control，200 会替换 grant 并关闭旧连接。409 control_busy 不使有效旧地址失效；丢失时 GET 原 Session，以当前 control_grant.id 作 expected_grant_id 按恢复规则调用 browser_recover_control。claimed 或人工操作中不可 recover；结果未知先重查，不循环换发。旧 control_phase: "awaiting_first_connection" / retry_after_seconds 仅供等待判断。

脚本先检查凭据、读取价格并保存幂等键，收尾分别核对释放与结算。权限为 0600 的 .capybrowser-first-run.json 仅恢复同一任务；重跑只处理原 Session，不再访问网页或新建运行。新任务另设 CAPYBROWSER_STATE_FILE，旧任务释放和费用未核清前不删文件换键；同路径并发会被锁拒绝。示例无需 Profile；跨 Agent 串行复用须先保存释放，并使用同一用户/团队内有权访问的 Profile。

新逻辑任务创建收费运行前，示例按独立缓存比较可选说明修订；首次只建基线，同修订保持安静，恢复/收尾跳过，检查失败不阻断任务。机器信号供 Agent 判断，仅在与当前需求有关时介绍相应功能。按需发现与缓存边界可主动查询，不要求用户阅读公告。

遇到问题报告原 Session 与实际阻塞，不无限等待或换键。版本记录与 OpenAPI按需查阅。