自动化接入：本地 API、MCP 与 Playwright

无界指纹浏览器提供三种自动化接入方式：本地 HTTP API、MCP 与 Playwright/CDP。三者围绕同一批环境工作，区别只在调用形式与适合的工具链，可以按团队现有的技术栈选择，也可以组合使用，无需把浏览器控制权暴露到公网。

无论选择哪一种，客户端都必须保持运行，环境必须处于已启动状态。自动化脚本负责的是「调度与操作」，环境的创建、代理与指纹配置仍然在客户端内完成。

三种方式怎么选

选择时先看任务形态：只需要启动环境、跑脚本、关环境，用本地 API 加 Playwright 的组合最直接；如果希望由 AI 客户端发起操作，再引入 MCP。三者并不互斥，同一条流水线里经常同时出现。

五个自动化模块的分工

除了脚本接入，客户端内置五个自动化模块，覆盖从「打开哪批环境」到「什么时候执行」的不同层次。先分清各自负责什么，再决定把任务放在哪一层：

五个模块产生的执行记录统一汇总到任务中心，所有任务的进度与历史集中呈现，失败原因可回溯。常见组合是先由启动场景准备一批环境，再由自动化流程执行步骤；需要按时间执行时交给定时任务。脚本、API 与上述模块共享同一套环境，不需要为不同方式重复创建环境。

本地 HTTP API

客户端在本机启动 HTTP API，默认地址为 http://127.0.0.1:50325。该服务仅监听回环地址，外部网络无法直接访问。使用前需要在客户端设置中确认本地 API 已开启，并保持客户端运行。

• 适合把环境启动、状态查询与关闭接入内部工具；
• 请求与响应均为本地通信，不经过云端；
• 可以按环境标识查询运行状态，作为任务前置检查；
• 接口清单与字段说明以客户端内展示的 API 文档为准，不要凭记忆拼接路径。

接入时注意两点：一是请求要设置合理的超时，环境启动本身需要时间，超时过短会把正常启动误判为失败；二是调用方要处理客户端未启动、端口被占用、环境已被其他任务占用等返回结果，而不是只判断成功。

Playwright 与 CDP

环境启动后可以返回调试连接信息。Playwright 通过 CDP 连接到已启动的浏览器实例，适合编写可维护的自动化脚本：

from playwright.sync_api import sync_playwright

# ws_endpoint 由本地 API 的启动结果提供
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(ws_endpoint)
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    browser.close()

已有 Chrome 自动化体系也可以直接使用 CDP 调试端点接入，不必重写已有脚本结构。脚本编写建议：

• 独立环境：一个任务对应一个环境，不要多个脚本共用同一个实例；
• 及时关闭：任务结束后关闭环境，避免实例长期占用并发名额；
• 异常处理：对页面加载超时、元素缺失、连接中断分别处理，不要用统一的重试掩盖所有错误；
• 日志留痕：记录任务开始时间、目标环境、关键步骤与失败原因，便于单独重试；
• 节奏控制：操作间隔保持自然，避免短时间高频请求触发业务站点的风控；
• 不硬编码凭据：登录信息与代理密码通过客户端或保险箱获取，不写入脚本仓库。

MCP

MCP 适合让支持该协议的 AI 客户端调用浏览器工具。配置步骤：

1. 在客户端设置中确认本地服务已开启并保持运行；
2. 打开客户端内提供的 MCP 配置片段，复制到对应 AI 客户端的配置文件中；
3. 按 AI 客户端的要求填写服务名称与连接地址，地址指向本机服务；
4. 重启 AI 客户端，确认工具列表中出现浏览器相关能力；
5. 先用只读操作验证连通性，再尝试启动环境与打开页面。

不同 AI 客户端的配置字段、配置文件位置与重载方式都不一样，遇到工具未出现的情况，先检查该客户端的配置示例与日志，不要反复修改客户端设置。MCP 更适合交互式探索与辅助操作，大批量、需要精确时序的任务仍建议用脚本完成。

批量导入 200 行

环境批量导入单次最多 200 行，使用 CSV 模板，一行对应一个环境。建议字段如下，实际以客户端内下载的模板为准：

1. 下载模板并填写，避免空行与重复名称；
2. 先导入少量行做验证，确认字段解析正确；
3. 导入后统一执行代理预检；
4. 按分组批量启动，观察前几个环境的运行状态；
5. 失败行按提示修正后单独重试，不需要重新导入整批。

超过 200 行时拆分为多个文件，按分组分批导入，便于定位问题。导入完成不等于可用，代理与指纹仍需要通过预检与启动验证。

定时任务与养号保活

五种定时任务类型

定时任务支持启动、停止、巡检、执行流程与快照五种类型，可按每日、工作日或单次执行，适合早晚班自动值守。

• 启动 / 停止：按计划打开或关闭指定环境，减少人工值守；
• 巡检：定期检查环境状态，发现异常时通过通知中心提醒；
• 执行流程：在指定环境上运行已编排或录制的自动化流程；
• 快照：按计划留存环境当前状态，便于后续回溯。

每日与工作日适合固定班次，单次适合临时任务。计划较多时，把互相依赖的任务拆开配置，避免上一个环境尚未启动完成就开始执行下一步。

养号保活

养号保活会定时让环境模拟真实浏览行为，维持账号活跃度与登录态，适合需要长期保持在线状态的账号。它不替代人工运营，也不改变环境的指纹与代理配置，而是在既有配置上按计划产生浏览动作。

任务中心

所有自动化任务，无论来自脚本、流程还是定时任务，执行进度与历史都汇总到任务中心，失败原因可回溯。排查时先看任务中心确认失败发生在哪一步，再回到对应模块检查环境、代理或流程配置。

任务编排

任务编排把启动环境、执行脚本与关闭环境组织为一条可复用任务，适合需要按固定顺序处理多个环境的场景。其执行特性如下：

• 队列执行：批量任务按队列依次处理，不会同时冲击全部环境；
• 失败隔离：单个环境失败不会中断其余环境，其余任务继续执行；
• 结果记录：记录每一步的开始时间与结果，便于定位具体失败环节；
• 单独重试：失败的环境可以单独重试，不必重跑整个批次；
• 并发排队：并发数超过套餐并发上限时，多余任务进入排队，不会直接报错退出。

编排任务应尽量保持步骤简单，把判断逻辑放在脚本内部，而不是堆在任务层。任务层负责调度与记录，脚本负责业务动作，出问题时更容易判断是哪一层的原因。

团队权限、保险箱与审计日志

团队版提供团队控制台。管理员可以分配成员席位、划分可见环境范围，并把敏感代理凭据放入保险箱，成员按权限引用而不直接看到明文。关键操作写入审计日志，便于复盘环境启动、配置变更与成员操作。

自动化脚本使用的环境同样受权限约束：脚本能操作的范围不应超过执行者本人的权限。团队共享自动化任务时，建议固定运行账号，并在审计日志中保留任务与环境的对应关系，避免出现无法追溯的批量操作。

本地加密存储

环境目录、Cookie 与代理凭据默认保存在本机，敏感字段加密写入，浏览器内容不上传云端。自动化脚本读取环境信息时，应通过本地 API 或客户端提供的接口，不要把凭据复制到脚本仓库、日志或临时文件。

常见问题

50325 连不上或端口被占用

先确认客户端正在运行，且设置中的本地 API 已开启。端口被占用时，检查是否有其他程序或上一个残留进程占用了同一端口；关闭占用方后重启客户端。若改过端口，脚本里的地址也要同步修改。

多个脚本争用同一个环境

同一环境同时被两个脚本连接，会出现页面互相跳转、元素定位失败、登录态冲突。为每个任务分配独立环境，或使用任务编排的队列机制串行执行，不要用重试来掩盖争用问题。

任务一直排队不执行

检查当前运行中的环境数量是否已达到套餐并发上限。达到上限后新任务会排队等待，属于正常行为。关闭已完成但未释放的环境，或减少单批任务的环境数量。

MCP 客户端里看不到浏览器工具

不同客户端的配置字段与配置文件位置不同，先对照该客户端的官方示例检查格式，再确认服务地址指向本机、客户端已完全重启。仍不生效时查看客户端日志，通常能看到配置解析失败的具体原因。

相关文档

代理与出口配置见代理配置与预检；环境创建与批量管理见环境管理；团队授权与保险箱规则见团队成员与部门；首次使用可先阅读快速开始；运行多个窗口时的注意事项见多窗口同步管理。