在 Skyvern 中安装与使用 Skyvern Agent Chrome 扩展：开发环境搭建、配对流程与 Broker 安全模型全解析-开发者社区

在 Skyvern 中安装与使用 Skyvern Agent Chrome 扩展：开发环境搭建、配对流程与 Broker 安全模型全解析

【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern

Skyvern Agent 是一款纯 JavaScript 编写的 Chrome 扩展（Manifest V3），它让本地 Skyvern MCP 服务器直接驱动你日常使用的真实 Chrome 浏览器——包括已登录的会话与 Cookie，而不再依赖skyvern browser serve启动一份拷贝 Profile 的独立浏览器。本文基于扩展自述文档与官方指南 Control Your Chrome with Skyvern Agent，结合仓库源码深入讲解开发环境安装、显式配对、持久化 Broker 模式、安全边界与常见故障排查，读完即可将任意 Chrome 标签页接入本地 Skyvern MCP 工作流。

一、Skyvern Agent 扩展解决了什么问题

Chrome 136 及以后版本对默认 Profile 忽略--remote-debugging-port启动参数，这意味着外部工具无法再通过 CDP 端口直接接管用户日常使用的浏览器。Skyvern Agent 扩展通过以下方式绕开这一限制：

通过 Chrome 扩展 API（debugger、tabs、tabGroups、userScripts）控制用户显式分享的标签页；
扩展向本机回环地址ws://127.0.0.1:19777/extension/v1发起出站WebSocket 连接，因此无需任何入站监听即可与本地桥接层通信；
与skyvern browser serve（独立浏览器 + 复制 Profile）不同，扩展直接复用真实 Chrome 的登录态，天然支持需要 Cookie 与认证的站点。

从仓库中的 manifest.json 可以看到扩展的能力声明：debugger、userScripts、tabs、tabGroups、storage、alarms六项权限，host_permissions覆盖http://*/*与https://*/*，最低 Chrome 版本要求为 138（minimum_chrome_version），当前版本号为0.2.8。

二、安装扩展：一键命令与手动步骤

扩展纯 JavaScript 实现，无需构建步骤（无 TypeScript 编译、无打包器），因此加载方式为标准 Chrome「加载已解压的扩展程序」。

2.1 推荐方式：`extension-install`

skyvern browser extension-install

该命令（实现见 browser.py）会：

打印已解压的扩展目录绝对路径（底层调用BrowserExtensionRuntime.extension_dir()）；
尽最大努力打开chrome://extensions页面；
依据当前是否处于 Broker 模式，打印对应的编号步骤清单。

2.2 手动安装

自述文档给出了完整的手动流程，共 7 步：

打印已解压扩展目录：
```
skyvern browser extension-path
```
在 Chrome 打开chrome://extensions；
开启Developer mode（开发者模式）；
点击Load unpacked（加载已解压的扩展程序）；
选择第 1 步打印出的目录；
打开扩展Details页面，启用Allow User Scripts（允许用户脚本）——该权限是skyvern_evaluate通过 Chrome User Scripts API 在页面主上下文执行调用方提供的 JavaScript 的前提；
启动扩展模式的本地 MCP 服务器（见下节）。

2.3 启动扩展模式的 MCP 服务器

两种等价方式：

# 方式一：CLI 标志（MCP 服务器启动时立即拉起扩展桥接） skyvern run mcp --browser-extension # 方式二：环境变量（懒加载，首次调用 skyvern_browser_session_create 时才按需启动） BROWSER_TYPE=extension-connect skyvern run mcp

在标准 JSON 格式的 MCP 客户端配置中，方式二对应：

{ "mcpServers": { "skyvern": { "command": "skyvern", "args": ["run", "mcp"], "env": { "BROWSER_TYPE": "extension-connect" } } } }

从 session.py 的实现看，扩展模式下的浏览器会话是隐式的（无需手动传入session_id）：BROWSER_TYPE等于extension-connect时，skyvern_browser_session_create会等待扩展就绪（wait_for_extension，超时约 8 秒），失败时按 Broker/legacy 两种模式给出对应的配对引导提示。扩展模式还要求 MCP 服务器运行在stdio 传输上，托管式（hosted）MCP 暂不支持。

三、配对（Pairing）：单次点击的显式授权

3.1 启动配对

skyvern browser extension-pair

配对流程的完整语义为：

命令通过本地桥接层（Broker 模式下走「operator」认证通道）请求一个一次性、两分钟有效的配对链接；
配对页面自动打开（若无法自动打开则打印安全回退 URL），并检查扩展是否已加载；
在浏览器配对页点击Approve pairing，随后在自动打开的Skyvern Agent 确认标签页中再次点击确认——这是唯一的单步审批动作。

3.2 扩展先加载、配对后触发的情形

自述文档特别说明：本地配对页会在认领单次有效 offer 之前先探测扩展是否可用（源码中对应skyvern.pairingProbe消息，见 service_worker.js 的isPairingProbe校验：仅接受来自127.0.0.1/localhost且端口匹配的http:发送方）。如果配对先于扩展加载完成启动，请保持配对页面打开——页面会保留该 offer，并在扩展可用后自动继续。

3.3 配对链接的安全设计

一键 URL 只在其 fragment 中包含短时效的 nonce，Skyvern不会把配对 token 放进 URL；
配对 token 不会通过任何 MCP 工具暴露；
Broker 模式下扩展凭据由守护进程持有，extension-pair是唯一的配对入口（见下一节）。

四、默认的持久化 Broker 模式（POSIX）

4.1 默认行为与自举

在 macOS / Linux（POSIX）上，扩展模式默认启用持久化 Broker：

首次启动 Broker 时，它会自动校验或初始化自己的 journal（日志账本），并复制已存在的旧版凭据到仅属主可读的 Broker 运行目录；若不存在则创建一对匹配的属主私有 legacy 与 broker 凭据；
skyvern browser extension-broker-enable仍可用作显式的幂等启用/启动命令，但正常安装流程不需要执行它——首次启动即自动完成；
扩展桥接通过属主认证的 Unix domain socket与 Broker 通信，Broker 拥有对外回环端口的监听权。

4.2 多 Agent 共享与生命周期

Broker 模式带来几个关键行为（README 原文要点，均可在源码与命令实现中印证）：

端口常驻：MCP 进程退出后，面向扩展的端口仍被 Broker 保留，不会因单个进程退出而释放；
多 Agent 并发：多个 MCP Agent 可同时共享同一个 Broker 守护进程；
一次配对，处处可用：一次成功配对产生一个持久化的工作站批准（workstation approval），由所有 MCP Agent 共享。撤销命令为：
```
# 仅撤销 grant 来源的批准 skyvern browser extension-revoke-workstation # 全量终止开关：同时清空实时交互式批准 skyvern browser extension-revoke-workstation --all
```
从 browser.py 的extension_revoke_workstation实现可以看到：默认 scope 只清 grant-source 批准，--all才是操作者的完全终止开关（workstation.revoke契约中的 "full kill switch"）。
交互式批准绑定连续连接：交互式批准与「持续连接的 Agent」绑定——它在重叠 socket 替换（MV3 与网络重连所需）时存活，但在真正断开时失效，且绝不允许从过期的批准来源恢复；
Tab 租约：每个已批准的 Agent 租用自己的标签页，弹窗跟随其 opener，用户分享的标签页归第一个认领它的 Agent；
断线重连窗口：扩展断开后会获得一个短暂的重连窗口，窗口过后会话创建会为你打开一键配对页面。

4.3 Broker 状态与停止

# 查看脱敏后的 Broker 与扩展连接状态（不暴露配对 token） skyvern browser extension-broker-status # 排空守护进程并释放配置端口 skyvern browser extension-broker-stop

Broker 模式下skyvern browser extension-status报告的也是 Broker 连接状态（脱敏）；只有在 legacy 退出模式下它才报告 token 配置、文件权限与回环端口监听情况。

4.4 标签页与弹窗的记录机制

扩展会把 Broker 创建的根标签页（root tabs）与弹窗（popups）记录在 Chrome session storage 中，直至这些标签页关闭（scopedTabGroupIds/ pending pairing offer 均存于chrome.storage.session）。这样做的目的是：当外部调试器（debugger）分离导致某标签页移出扩展作用域后，Broker 仍能关闭自己创建的那个标签页。与此同时，扩展对每一个非自己创建、不在作用域内的标签页都会拒绝tabs.remove操作。

五、选择旧版内嵌 Relay（Legacy Opt-out）

如确实需要回到旧版内嵌 relay（例如依赖弹窗手动粘贴 token 的流程），在 POSIX 上必须设置精确值：

SKYVERN_BROWSER_EXTENSION_BROKER=0

语义如下（README 明确说明）：未设置、设置为1、或任何其他值，一律走 Broker。该 opt-out 可以放在 Skyvern CLI 使用的同一环境变量或 env-file 链中。

Windows 平台目前自动走 legacy 路径（Broker 的属主认证传输尚未在 Windows 实现），并记录 Broker 代码UNSUPPORTED_PLATFORM，无需任何 opt-out 设置。

在 legacy 模式下，手动回退流程为：

# 复制配对 token 到剪贴板 skyvern browser extension-token

然后打开 Skyvern Agent 弹窗，粘贴 token，点击Connect。该命令在 Broker 模式下会被主动拒绝（extension-token实现中检查broker_mode_enabled()，输出 "The extension credential is broker-owned and cannot be copied in broker mode." 并以退出码 1 结束），因为 broker 模式下extension.secret由守护进程持有。

六、端口配置

默认端点：ws://127.0.0.1:19777/extension/v1（常量定义见 protocol.js 的DEFAULT_BRIDGE_PORT = 19777）。

如需更换端口：

为 MCP 进程设置环境变量SKYVERN_BROWSER_EXTENSION_PORT（例如19778）；
在扩展弹窗的Advanced settings（高级设置）中输入同一端口；
重启 MCP 服务器并重连扩展。

端口冲突时 Broker不会抢占外部属主端口，也不会静默更换端口——先用skyvern browser extension-broker-status检查现状，必要时extension-broker-stop释放端口，再按上述两步配置新端口。

七、驱动浏览器：典型 MCP 调用序列

扩展连接完成后，一个典型的 MCP 流程为：

skyvern_browser_session_create——连接 Skyvern 与扩展（扩展模式下会话隐式创建）；
skyvern_navigate——打开页面；
skyvern_observe——观察页面并识别可执行动作；
skyvern_execute或skyvern_click——与页面交互。

关于元素定位的细节：

选择器（Selector）仍是首选定位方式；
skyvern_click与skyvern_type额外接受视口 CSS 像素坐标x/y（以网页内容左上角为原点）：两个坐标必须同时提供且不得与选择器混用，数值必须有限且非负；
skyvern_execute也可以向点击与输入动作传递同样的坐标；
坐标与skyvern_screenshot(full_page=False)对齐，不随 device pixel ratio 缩放。

八、同意边界与安全模型

8.1 同意即「组成员身份」

名为Skyvern Controlled的 Chrome 标签组是唯一的同意边界（组名与紫色组色的常量定义见 tab_scope.js：SKYVERN_GROUP_TITLE = "Skyvern Controlled"、SKYVERN_GROUP_COLOR = "purple"）：

将标签页拖入该组 = 分享给 Skyvern；
将标签页拖出该组 = 立即撤销访问权；
扩展弹窗中的Add to Skyvern Controlled/Remove from Skyvern Controlled按钮执行相同的组成员变更；
扩展从不向 Skyvern 披露组外标签页。

Skyvern 的作用域包括：显式加入组的现有标签页、Skyvern 创建并加入组的标签页、受控标签页打开并被加入组的弹窗。扩展会为「直接 JavaScript 执行」在命令前后分别校验精确的标签组身份（对应dom.evaluate与tab_scope的过渡校验逻辑）。

8.2 受限 URL 清单

扩展拒绝控制以下目标（isRestrictedUrl实现于 protocol.js）：

chrome://、chrome-untrusted://、chrome-extension://、devtools://、edge://、file://、Chrome Web Store 页面（chromewebstore.google.com），以及除about:blank外的所有about:页面。

Broker 可以在等待导航期间将about:blank保留为受控根标签页，但直接求值（skyvern_evaluate）拒绝about:blank及一切非 HTTP(S) URL。

8.3 调试器与权限边界

基于 debugger 的工具会显示 Chrome 的调试器 infobar，Skyvern从不隐藏它；点击 infobar 中的Cancel会立即撤销对该标签页的调试器访问，且 Skyvern 不会自动重连；
主上下文 JavaScript 命令不挂接调试器，因此不显示 infobar；
扩展请求 HTTP/HTTPS 页面访问权限，使skyvern_evaluate能通过 Chrome User Scripts API 在页面主上下文运行调用方提供的 JS——该路径不依赖页面自身的 CSP；
用弹窗移除标签页或将其拖出 Skyvern Controlled 组，会撤销扩展对该标签页的全部访问；
Skyvern 从不关闭或重启你的 Chrome 浏览器。

8.4 传输与凭据安全

扩展出站连接到的桥接层只绑定127.0.0.1；macOS/Linux 上由持久化守护进程持有该监听器，MCP 进程经属主认证的 Unix domain socket 到达它。配对认证会校验扩展身份，凭据从不进入 URL，也从不经 MCP 工具返回。

九、已知限制

暂不支持下载管理与文件选择器（file-chooser）操作；
不支持隐身窗口（Incognito）；
为受控标签页打开 DevTools 会分离 Skyvern 并撤销该标签页访问权；
托管式 Skyvern MCP 尚不能使用扩展；
Chrome 内部页面、扩展页面、DevTools、本地文件、Chrome Web Store 及其他上述受限目标不可被控制。

十、故障排查

10.1 扩展未连接

按顺序检查：

运行skyvern browser extension-install并按编号步骤完成安装；
用--browser-extension或BROWSER_TYPE=extension-connect启动 MCP 服务器；
运行skyvern browser extension-status，确认在配置端口上报告 Broker ready（或 legacy 桥接在监听）；
运行skyvern browser extension-pair，先在浏览器页面批准，再在 Skyvern Agent 确认标签页批准；
Broker 模式下若早期配对流程卡住，可用skyvern browser extension-pair --cancel-pending重试（extension-token仅在SKYVERN_BROWSER_EXTENSION_BROKER=0时可用）；
至少把一个可控制标签页加入 Skyvern Controlled 组后再重试。

10.2 MCP 服务器迟迟不完成连接

服务器在响应首个请求前要加载庞大的 Python 依赖树，通常只需数秒，但安装/升级后的首次启动或机器繁忙时可能远超 MCP 客户端默认启动窗口。特别注意：本地服务器挂载失败时，编码类 Agent 会回退到同名的托管 Skyvern 工具——看似在驱动你的 Chrome，实际可能是在驱动云端浏览器。务必先确认服务器已连接再信任扩展流程。

调大客户端启动超时：

Claude Code：在启动环境中设置MCP_TIMEOUT（毫秒），例如MCP_TIMEOUT=180000；
Codex：在~/.codex/config.toml中调大该服务器的startup_timeout_sec。

连接后可在客户端启动的服务器日志中查看mcp_boot_ready行：该事件在服务器成功处理initialize后才发出，报告spawn_to_serve_ms及其构成阶段env_ms、tool_import_ms，可用于定位时间花在哪里。

10.3 端口被占用

见第六节：检查extension-broker-status，需要时extension-broker-stop释放端口，或改用SKYVERN_BROWSER_EXTENSION_PORT+ 弹窗高级设置中的同端口配置，然后重启 MCP 并重连扩展。

10.4 轮换配对 token

Broker 模式：skyvern browser extension-broker-stop→ 删除~/.skyvern/run/browser-extension/<port>/extension.secret→ 重启扩展模式 MCP。启动时 Broker 会在创建替换凭据前校验 journal，不安全的 journal 会 fail-closed。随后用skyvern browser extension-pair重新配对。绝不要在守护进程运行时编辑属主私有的 Broker 工件。
Legacy 模式（SKYVERN_BROWSER_EXTENSION_BROKER=0）：停止 MCP 服务器 → 删除~/.skyvern/browser_extension_token→ 重启服务器 →extension-pair并批准两个浏览器步骤。若设置了SKYVERN_BROWSER_EXTENSION_TOKEN，先移除它——环境变量值在 legacy 模式优先，在 Broker 模式会被拒绝。

10.5 DevTools 或调试器 infobar 断开了标签页

关闭 DevTools，然后把标签页重新拖入 Skyvern Controlled 组（或使用弹窗）。若你曾点击 infobar 的Cancel，重新加入组会恢复同意；Skyvern 从不自动重连。

十一、扩展源码导读

若想深入理解本文涉及的机制，建议按以下顺序阅读仓库中的实现：

manifest.json——权限模型与最低 Chrome 版本；
service_worker.js——MV3 后台：操作分发（OPS.DEBUGGER_ATTACH、DOM_EVALUATE、TABS_CREATE等）、配对 offer 队列、pairingProbe信任校验、桥接重连；
protocol.js——协议版本（当前PROTOCOL_VERSION = 2）、消息类型、CDP 白名单前缀与敏感方法黑名单（如Network.getAllCookies、Storage.setCookies被拒绝）、受限 URL 判定；
tab_scope.js——Skyvern Controlled 组管理、标签分享/撤销、组身份过渡校验、session storage 持久化；
browser.py——skyvern browser extension-*全部命令的实现（extension-install位于 L647、extension-pair位于 L490、extension-broker-stop位于 L540、extension-revoke-workstation位于 L580 等）；
session.py——BROWSER_TYPE=extension-connect下的隐式会话创建与扩展就绪等待逻辑。

这套「纯 JS 扩展 + 回环 WebSocket + 属主认证 Broker + 标签组同意边界」的组合，使得 Skyvern 可以在不触碰 Chrome 远程调试端口的前提下，安全、可控、可审计地复用你真实浏览器中的登录态完成自动化任务，是本地 Agent 工作流中复用现有浏览器环境的首选路径。

【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

在 Skyvern 中安装与使用 Skyvern Agent Chrome 扩展：开发环境搭建、配对流程与 Broker 安全模型全解析