在 Skyvern 中安装与使用 Skyvern Agent Chrome 扩展开发环境搭建、配对流程与 Broker 安全模型全解析【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvernSkyvern 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 扩展 APIdebugger、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 版本要求为 138minimum_chrome_version当前版本号为0.2.8。二、安装扩展一键命令与手动步骤扩展纯 JavaScript 实现无需构建步骤无 TypeScript 编译、无打包器因此加载方式为标准 Chrome「加载已解压的扩展程序」。2.1 推荐方式extension-installskyvern 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_TYPEextension-connect skyvern run mcp在标准 JSON 格式的 MCP 客户端配置中方式二对应{ mcpServers: { skyvern: { command: skyvern, args: [run, mcp], env: { BROWSER_TYPE: extension-connect } } } }从 session.py 的实现看扩展模式下的浏览器会话是隐式的无需手动传入session_idBROWSER_TYPE等于extension-connect时skyvern_browser_session_create会等待扩展就绪wait_for_extension超时约 8 秒失败时按 Broker/legacy 两种模式给出对应的配对引导提示。扩展模式还要求 MCP 服务器运行在stdio 传输上托管式hostedMCP 暂不支持。三、配对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 中包含短时效的 nonceSkyvern不会把配对 token 放进 URL配对 token 不会通过任何 MCP 工具暴露Broker 模式下扩展凭据由守护进程持有extension-pair是唯一的配对入口见下一节。四、默认的持久化 Broker 模式POSIX4.1 默认行为与自举在 macOS / LinuxPOSIX上扩展模式默认启用持久化 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-stopBroker 模式下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操作。五、选择旧版内嵌 RelayLegacy Opt-out如确实需要回到旧版内嵌 relay例如依赖弹窗手动粘贴 token 的流程在 POSIX 上必须设置精确值SKYVERN_BROWSER_EXTENSION_BROKER0语义如下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_pageFalse)对齐不随 device pixel ratio 缩放。八、同意边界与安全模型8.1 同意即「组成员身份」名为Skyvern Controlled的 Chrome 标签组是唯一的同意边界组名与紫色组色的常量定义见 tab_scope.jsSKYVERN_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.jschrome://、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 的调试器 infobarSkyvern从不隐藏它点击 infobar 中的Cancel会立即撤销对该标签页的调试器访问且 Skyvern 不会自动重连主上下文 JavaScript 命令不挂接调试器因此不显示 infobar扩展请求 HTTP/HTTPS 页面访问权限使skyvern_evaluate能通过 Chrome User Scripts API 在页面主上下文运行调用方提供的 JS——该路径不依赖页面自身的 CSP用弹窗移除标签页或将其拖出 Skyvern Controlled 组会撤销扩展对该标签页的全部访问Skyvern 从不关闭或重启你的 Chrome 浏览器。8.4 传输与凭据安全扩展出站连接到的桥接层只绑定127.0.0.1macOS/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_TYPEextension-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_BROKER0时可用至少把一个可控制标签页加入 Skyvern Controlled 组后再重试。10.2 MCP 服务器迟迟不完成连接服务器在响应首个请求前要加载庞大的 Python 依赖树通常只需数秒但安装/升级后的首次启动或机器繁忙时可能远超 MCP 客户端默认启动窗口。特别注意本地服务器挂载失败时编码类 Agent 会回退到同名的托管 Skyvern 工具——看似在驱动你的 Chrome实际可能是在驱动云端浏览器。务必先确认服务器已连接再信任扩展流程。调大客户端启动超时Claude Code在启动环境中设置MCP_TIMEOUT毫秒例如MCP_TIMEOUT180000Codex在~/.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 轮换配对 tokenBroker 模式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_BROKER0停止 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_TYPEextension-connect下的隐式会话创建与扩展就绪等待逻辑。这套「纯 JS 扩展 回环 WebSocket 属主认证 Broker 标签组同意边界」的组合使得 Skyvern 可以在不触碰 Chrome 远程调试端口的前提下安全、可控、可审计地复用你真实浏览器中的登录态完成自动化任务是本地 Agent 工作流中复用现有浏览器环境的首选路径。【免费下载链接】skyvernAutomate browser based workflows with AI项目地址: https://gitcode.com/GitHub_Trending/sk/skyvern创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考