browser-use 和 Playwright MCP 接指纹浏览器的完整做法 - NexBrowser指纹浏览器-官方博客Blog

想让 AI Agent 在带指纹保护、带独立 Cookie 和独立代理出口的浏览器里干活，只有一条正路：让 Agent 去连接一个已经启动好的窗口，而不是让它自己拉起一个新的 Chromium。连接的协议是 CDP（Chrome DevTools Protocol），browser-use 和 Playwright MCP 都原生支持它。

整件事拆成三步：

用指纹浏览器的 Local API 按环境 ID 启动窗口，拿到这个窗口专属的 CDP 调试地址；
把这个地址填进 browser-use 的 cdp_url，或填进 Playwright MCP 的 --cdp-endpoint；
让 Agent 第一件事先去访问检测页，确认出口 IP 和指纹参数确实是这个环境的。

下面按这个顺序展开，顺带说清楚容易翻车的地方。

从 Local API 启动环境到 browser-use 与 Playwright MCP 接入的三步流程图

为什么必须是「连接」而不是「启动」

如果你用 browser-use 或 Playwright MCP 的默认行为，它们会自己下载并启动一个干净的 Chromium。那个实例没有你配置的指纹参数，没有环境里的 Cookie 和本地存储，也不走你给环境绑的代理——它走的是本机出口。跑出来的结果和你在客户端里手动打开窗口是两回事。

指纹浏览器的工作方式是：每个环境对应一套独立的存储、一套自洽的指纹参数和一条独立的代理链路，这些全部由窗口底层的浏览器进程托管。外部自动化工具接上 CDP 端点之后，所有页面操作都走这个进程，环境配置自然全量生效，不需要在脚本里再写一遍 UA、时区或代理。

所以判断接法对不对，有个很简单的标准：脚本里出现了 launch、executablePath、proxy 这类参数，基本就接错了；出现的应该是 connect、cdp_url、--cdp-endpoint。

第一步：启动环境并拿到 CDP 地址

Local API 是指纹浏览器开在本机的一个 HTTP 服务。你在客户端里把它打开，然后用脚本调用「启动窗口」接口，传入要打开的环境 ID，接口会返回这个窗口专用的调试端点。返回形式通常是两种之一：

HTTP 形式：http://127.0.0.1:<端口>
WebSocket 形式：ws://127.0.0.1:<端口>/devtools/browser/<GUID>

两种都能用。HTTP 形式更省事，因为很多工具会自己去 /json/version 把 WebSocket 地址换出来；WebSocket 形式更直接，但那串 GUID 每次启动都变，不能硬编码。

在 NexBrowser 里，Local API 在免费档就是完整开放的，调用次数不限，启动接口返回的就是该窗口的调试端口，环境里已经绑好的住宅 IP 或自有代理、独立存储会全量作用于后续 Agent 的每一次操作。接口路径和返回字段以客户端内的 API 文档为准，功能说明见 Local API。关于「一次请求怎么换来一个可接管的端口」，我们单独写过更细的拆解：Local API 怎么启动环境并拿到调试端口。

这里先记住一条会影响你脚本写法的事实：端口是每次启动分配的，不是固定值。不要把端口写死在配置文件里，正确做法是每轮任务先调启动接口，拿到返回值再往下传。

第二步之 A：browser-use 怎么接

browser-use 在实例化 Browser 时支持 cdp_url 参数，填上之后它不会另起实例，而是复用目标浏览器的当前上下文和页面。

from browser_use import Agent, Browser

# cdp_endpoint 来自上一步 Local API 的返回值，不要写死
cdp_endpoint = "http://127.0.0.1:54321"

browser = Browser(cdp_url=cdp_endpoint)

agent = Agent(
    task="打开后台的订单页，把今天的待发货数量读出来",
    llm=llm,          # 你自己配置的模型
    browser=browser,
)

await agent.run()

几个实践要点：

填完整 URL，带协议头。只写 127.0.0.1:54321 多半连不上。
browser-use 各版本的参数名和对象结构有过调整，如果你的版本报「未知参数」，去对应版本的连接远程浏览器文档里核对一下当前叫法，机制不变，名字可能变。
Agent 接管的是当前已打开的上下文。如果环境里已经登录好了账号，Agent 直接就是登录态，不需要在 prompt 里教它登录——这也是用指纹浏览器托管登录态的主要好处。
任务结束后，关闭窗口建议走 Local API 的关闭接口，而不是让脚本直接 kill 进程，这样 Cookie 和本地存储能正常落盘。

第二步之 B：Playwright MCP 怎么接

Playwright MCP（@playwright/mcp）面向的是 Claude Desktop、Cursor 这类 MCP 客户端，配置写在客户端的 JSON 里。让它连外部 Chromium 有两种写法。

命令行参数：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint=http://127.0.0.1:54321"
      ]
    }
  }
}

或者用环境变量 PLAYWRIGHT_MCP_CDP_ENDPOINT，值同样是那个调试地址。两种方式效果一致，用环境变量的好处是可以在外层脚本里动态注入端口，不用每次改 JSON。

接上之后，MCP 会在这个窗口里做无障碍快照解析和动作执行，模型看到的是真实环境里的页面结构，点击和输入也落在这个环境里。

这里有个顺序问题容易被忽略：MCP 服务通常随客户端启动，而指纹浏览器窗口是你手动或用脚本另外打开的。如果 MCP 起来时目标端口还没人监听，第一次调用就会失败。稳妥的做法是先把环境窗口启动起来，再启动或重载 MCP 客户端；或者在 MCP 客户端里做一次重连再发指令。

还有一个当前的限制要提前知道：命令行的 --cdp-endpoint 是全局单实例配置，一个 MCP 服务实例对应一个端点。如果你要让一个对话同时操纵多个环境窗口，得起多个配置了不同端点的 MCP 服务实例，或者自己封一层路由，官方 CLI 本身不做多窗口调度。

第三步：怎么确认真的接对了

接上不等于生效。Agent 能点能打字，不代表它在你以为的那条链路上。第一轮任务建议固定加两个核验动作：

一、核出口。 让 Agent 打开一个 IP 查询页，读出 IP 和归属地，和环境里绑的代理对照。如果读到的是你本机的家用 IP，说明它压根没连上环境窗口，而是自己拉起了新实例——回头检查 cdp_url / --cdp-endpoint 有没有真的被读到。

二、核一致性。 出口对上了还要看时区、语言和 IP 归属是否自洽。这块的核验顺序我们专门写过：绑好代理后怎么确认出口归属和时区语言一致。如果代理本身就连不通，先按代理导入后一键检测不通怎么排查处理，别在 Agent 层面绕。

这两步花不了一分钟，但能省掉后面「为什么结果和手动操作不一样」的大量排查时间。建议直接固化成每个任务的第一条指令，或者写成脚本里的前置断言，检测不过就中止。

三类常见卡点

端口漂移导致脚本第二天就跑不起来。 原因就是端口写死了。把「调启动接口 → 取返回端口 → 传给 Agent」做成一个函数，每轮任务开头调一次。

Agent 和浏览器不在同一台机器上。 Chromium 内核的 CDP 调试端口默认只监听 127.0.0.1。你的 Agent 跑在服务器、浏览器在办公室 Windows 机器上，直接填内网 IP 是连不上的。需要用 SSH 隧道或反向代理把端口转发到 Agent 所在的机器，然后仍然以 127.0.0.1:<本地映射端口> 的形式填写。顺便提醒：这个端口一旦暴露在公网，等于把浏览器完全交出去了，务必只在受控网络里转发。

想同时跑多个环境。 browser-use 这边好办，起多个 Browser 对象、各自带不同 cdp_url 就行，并发数受本机资源限制。Playwright MCP 这边受上面说的单实例限制，需要多起服务实例。如果你的诉求其实是「多个账号做同一套重复动作」，那用 Agent 可能是绕远路，无代码 RPA 或窗口同步更直接，可以先看无代码 RPA 在指纹浏览器里怎么搭流程再决定要不要写代码。

和 Puppeteer / Playwright 原生接法的关系

底层是同一件事。browser-use 和 Playwright MCP 只是在 CDP 之上加了一层模型驱动，连接方式和你用 Puppeteer 的 connect({ browserWSEndpoint })、Playwright 的 connectOverCDP() 完全同源。所以如果你已经用原生框架接通过环境，换成 Agent 就只是把同一个地址换个参数名填进去。反过来，如果 Agent 连不上，用原生框架先连一次是最快的定位手段——能连上说明问题在 Agent 侧配置，连不上说明问题在端口或服务。这部分可以对照 Puppeteer / Playwright 接管指纹浏览器环境。

动手前提一句

Agent 接管只解决「谁来操作」，不改变「以什么身份操作」。环境隔离、代理绑定这些前置工作没做扎实，Agent 只会把问题放大——它点得比人快，错得也比人快。所以顺序永远是：环境和代理先验证通过，再让 Agent 接管；任何配置都只是降低无意关联的概率，不构成不被平台识别的保证，也只适用于你自己有权访问的账号。

准备好动手的话，Local API 的接口说明和 AI Agent 的可接管范围在这里，客户端目前是 Windows 版，可直接下载后在设置里开启 Local API 服务，先用一个测试环境把上面三步走通。