OpenCLI Browser Bridge 完整指南5 分钟装好让 AI Agent 驱动已登录 Chrome 的浏览器扩展【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLIOpenCLI Browser Bridge 是一个 Chrome 浏览器扩展它把你已登录的浏览器接到本地 daemonAI Agent 就能通过 CLI 发号施令直接操作真实页面、复用你的真实登录态。本文覆盖安装验证、权限清单、命令执行链路、标签页租约与故障排查读完即可自助完成全部配置。为什么 AI Agent 需要一个通往已登录 Chrome的桥梁对 AI Agent 来说最有价值的数据往往藏在登录墙后面个人收件箱、工作台、站点的会员区。每次任务都开一个全新的浏览器环境意味着反复输账号、反复过风控效率极低更现实的路径是直接复用用户正在使用的那个浏览器会话。OpenCLI 的解法是一条轻量链路Browser Bridge 扩展 本地 daemon。daemon 按需自动启动扩展常驻在浏览器里两者通过 localhost 上的 WebSocket 对话。扩展本身不承载任何业务逻辑官方定位就是传输层 浏览器控制层——在某个标签页里跑一段 JS、跳转某个 URL、读取指定域名的 Cookie、截屏、等待下载这些动作全部来自 CLI 的显式指令扩展只负责忠实执行。只有落在真实浏览器里执行AI Agent 才拥有和人一样的身份真实的登录态、真实的 Cookie、真实的页面行为。这也是打通需要认证的站点适配器browser-backed adapters的关键——没有这座桥CLI 只能触达无需登录的公开接口。5 分钟装好 OpenCLI Browser Bridge 并验证连接两种安装方式方式 A推荐在 Chrome Web Store 安装名为OpenCLI的扩展方式 B手动拿到opencli-extension-v{version}.zip发行包并解压打开chrome://extensions开启开发者模式点击加载已解压的扩展程序选中解压目录。从 extension/manifest.json 可以看到基本规格Manifest V3后台是dist/background.js以 module 类型 service worker 运行extension/package.json 声明了opencli.compatRange: 1.7.0即与 CLI 版本的兼容范围。用 opencli doctor 验证连接在仓库根目录执行opencli doctor它检查两件事扩展是否装好、daemon 是否可达。链路打通的标志是扩展的 service worker 已经用 WebSocket 连上 daemon并完成hello握手——握手消息里带着扩展版本号与兼容范围daemon 据此就能向 CLI 上报版本不匹配的问题。弹窗面板与多配置文件扩展弹窗extension/popup.html是一块极简状态面板只有三项信息连接状态绿点已连接、橙点连接中、红点未连接daemon 版本ProfilecontextId当前浏览器配置文件的标识可一键复制。每个 Chrome 配置文件都跑一个独立的扩展实例OpenCLI 靠它区分不同的浏览器会话。管理多个配置文件时可以在 CLI 侧给 contextId 起别名opencli profile list opencli profile rename contextId work opencli profile use work opencli --profile work browser main state浏览器扩展权限清单chrome debugger 权限详解extension/manifest.json 里声明的核心权限debugger、tabs、cookies、tabGroups、downloads再加activeTab、alarms、storage和all_urls主机权限。每一项都对应一项实际能力权限换来的能力源码出处debugger求值、截屏、输入、网络捕获等 CDP 指令全靠它下发作用于扩展控制或绑定的标签页extension/src/cdp.ts 的chrome.debugger.attach/sendCommand封装tabs/tabGroups开、管专用自动化容器窗口与标签组并把选中标签的元数据喂回 CLIextension/src/background.ts 中 owned 容器与 tab group 的创建、收敛逻辑cookies让需要发起认证请求的浏览器型适配器读到对应 CookiehandleCookies按 domain/url 过滤后调用chrome.cookies.getAlldownloads把下载的四个状态喂给opencli browser wait downloadAgent 得以等文件落盘extension/src/cdp.ts 的waitForDownloadchrome debugger 权限详解URL 白名单与附加重试chrome.debugger光凭这一个权限就能附加到任意 http/https 标签页不需要主机权限。但扩展主动收窄了可附加范围isDebuggableUrl白名单只放行http://、https://、about:blank、data:chrome://与chrome-extension://页面一律不碰。附加动作自带重试普通命令最多重试 2 次、间隔 500ms浏览器命令走激进模式最多 5 次、间隔 1500ms——因为 1Password、Playwright MCP Bridge 这类扩展可能临时占用chrome.debugger。每次附加前还会先发一条无害探针Runtime.evaluate求值1确认附加仍然有效避免陈旧缓存造成误判。cookies为什么读取必须带作用域Cookie 读取被刻意设计成必须带作用域命令没提供domain或url时直接报错Cookie scope required: provide domain or url to avoid dumping all cookies这条硬约束挡住了一条命令倾倒全部 Cookie的用法。读取成功后返回 name、value、domain、path、secure、httpOnly、expirationDate 字段供需要登录态的浏览器型适配器发起认证请求。downloads只旁观全过程不碰任何东西opencli browser wait download借助chrome.downloads观察下载从 started 到 in-progress、completed 或 failed 的全过程让 Agent 在自动化流程触发下载后阻塞等待。实现上有三个关键点extension/src/cdp.ts 的waitForDownload模式过滤按命令给定的 filename / URL / finalUrl / mime 子串过滤matchesDownloadPattern只盯本次命令关心的那条下载超时保护默认 30s可用timeoutMs覆盖超时即返回interrupted状态与错误信息不干预OpenCLI 只做观察、过滤与等待不修改、不重定向、不持久化浏览器的下载历史。面向商店审核的官方说明建议直接复用为商店申请材料This extension useschrome.downloadsto surface download lifecycle (started / in-progress / completed / failed) to the OpenCLI command-line tool, so agents can wait for downloads triggered during an automation workflow. The command filters by a user-provided filename or URL pattern and timeout. We do not modify, redirect, or persist user download history.跟着一条命令走从 CLI 到 Chrome 的完整链路协议常量与结构化契约通信参数集中在 extension/src/protocol.ts常量取值作用DAEMON_HOSTlocalhost只与本机对话DAEMON_PORT19825daemon 默认端口DAEMON_WS_URLws://localhost:19825/ext命令通道WebSocketDAEMON_PING_URLhttp://localhost:19825/ping建连前的轻量健康检查Command携带唯一请求 IDid、动作类型action、页面标识page即 CDP targetId、会话名session、表面surface: browser \| adapterResult回传id、ok、data失败时附带稳定的机器可读错误码errorCode与可选的恢复提示errorHint。这份契约的意义在于CLI 侧不用对错误文本做正则匹配就能判断重试是否安全。协议动作清单包括exec、navigate、tabs、cookies、screenshot、close-window、sessions、set-file-input、insert-text、bind、network-capture-start、network-capture-read、wait-download、cdp、frames。其中exec是万能通道固定动作之外的一切需求本质都是借它把一段 JS 送进页面上下文执行。五步分发链路一条命令从 daemon 到页面执行要走完五步WebSocketonmessage收到 JSON 命令executeWithJournal进入命令日志层handleCommand按action分发先解析或创建标签页租约extension/src/cdp.ts 的 CDP 封装执行真实的浏览器操作结果含page标识经 WebSocket 送回 daemon。命令日志安全重试的底层保障CLI 在传输失败时会用同一个命令 ID发起重试于是 extension/src/journal.ts 的executeWithJournal以 ID 为键实现每个 ID 恰好执行一次命令正在跑 → 重复投递直接挂到 in-flight Promise 上不并发重复执行命令已跑完 → 原样重放记录下来的Result命令开始了却没跑完比如 service worker 中途死亡→ 返回command_lost错误码并附提示先检查浏览器状态再重试不要盲目重跑 navigate/click/type/eval 这类写操作。日志落在chrome.storage.session能扛过 service worker 重启浏览器退出即清除——恰好覆盖重试可能再来要一次结果的整个生命周期。上限 64 条超过 64KB 的结果不做记录重放时如实返回result_evicted。机器可读错误码与重试安全性classifyExtensionError把原始错误映射为稳定错误码错误码什么时候出现重试安全性attach_failed/tab_gone附加阶段就失败页面代码一行都没跑安全可发起新的逻辑尝试target_navigated执行期间页面文档发生了变更由页面层决定是否 settle-retrydetached_mid_command/cdp_timeout执行到一半死亡结果无法判定危险盲目重跑可能把写操作应用两遍连接稳定性MV3 环境下如何不掉线extension/src/background.ts 的connectAttempt是一套为 MV3 service worker 量身定做的韧性设计先探活再开 WebSocket。每次建连前先用 HTTP 探测/ping并且显式credentials: omit。为什么不加这个参数浏览器会把 localhost 上庞大的 Cookie jar 附在请求头里可能顶穿 Node 默认的请求头上限让 daemon 回一个 431重连循环就此静默卡死。翻倍退避加随机抖动。重连间隔 1s → 2s → 4s …封顶 15s外加 0–500ms 随机抖动一旦连接成功立即重置计数。20s 心跳空闲连接不算数。应用层每 20s 发一条ping消息。原因是 Chrome 116 只在 WebSocket 有活动时延长 service worker 生命周期挂着不动的 OPEN 连接不算活动——没有心跳worker 就会在 30s 空闲回收与 30s keepalive alarm 之间走钢丝。chrome.alarms 当最后防线。MV3 生产环境 alarm 最小间隔约 30sworker 被空闲回收后chrome.alarms会周期性把它唤醒重连保证链路不会永久断裂。标签页租约会话如何绑定到标签页opencli browser session command系列命令的会话连续性靠的是扩展内部的标签页租约TargetLease来维护CLI 会话 → 浏览器标签页的映射。三种租约形态owned自持会话拥有自己的标签页位于专用自动化容器窗口内——interactive 角色对应前台的OpenCLI Browser标签组橙色adapter 角色对应后台窗口bound借用用bind动作把会话绑到用户自己的标签页上即opencli browser bind能操作用户已登录的页面但不能新建、关闭或切换标签返回bound_tab_mutation_blockedpreferredTabId租约锚定到具体标签页 ID标签一关租约随之释放。空闲超时策略getIdleTimeout按场景区分空闲释放节奏场景空闲超时为什么这样定浏览器交互命令browser:*/operate:*10 分钟人的操作节奏慢不能回收太狠适配器驱动的自动化30 秒后台资源要快速释放bound 借用标签 / persistent 站点会话永不超时持有到解除绑定或关闭为止还有一层关键保护活跃命令计数activeCommandCounts会阻塞空闲释放——租约上还有命令在跑时绝不在命令脚下拆标签页等命令跑完才从完成时刻重新起算空闲窗口。worker 重启后的自愈租约注册表opencli_target_lease_registry_v2落在chrome.storage.session而不是storage.local所有 window/tab/group ID 都是单次浏览器会话内有效的运行时数字跨重启持久化既恢复不了还可能撞上用户新建的窗口和标签。storage.session恰好能在 service worker 重启时存活、浏览器退出时清除。启动时reconcileTargetLeaseRegistry恢复容器窗口与租约并用四层分组发现内存缓存 → 分组台账 → 租约持有标签所在组 → 全盘扫描空标题孤儿组收敛标签组专门修复worker 在tabs.group与tabGroups.update之间崩溃留下的无标题孤儿组。进阶能力一览从 60 秒 CDP 护栏到网络捕获extension/src/cdp.ts 提供的 CDP 封装远不止基础求值60 秒超时护栏。chrome.debugger自身没有超时页面被原生对话框alert/confirm/print/beforeunload阻塞时Runtime.evaluate会永久挂起拖垮该标签后续所有命令。因此sendDebuggerCommand默认带 60s 截止时间健康检查探针只有 2s同时扩展会从命令的绝对截止时间deadlineAt推导自己的 CDP 时限并预留 5s 余量让更具体的错误先于 daemon 的通用定时器到达 CLI。跨域 iframe 里执行代码。对跨域 iframe扩展用Target.setAutoAttachTarget.getTargets解析出 iframe 子 target再对子 target 直接Runtime.evaluateevaluateInFrame配合frames动作枚举跨域 frame 列表即可按索引逐个操作。文件上传的绕行方案。setFileInputFiles走Page.setInterceptFileChooserDialog拦截文件选择器Chrome 在经chrome.debugger附加时拒绝普通 nodeId 方式设置文件crbug 928255唯一可行路径是从拦截到的Page.fileChooserOpened事件里取backendNodeId再调DOM.setFileInputFiles。本地文件由 Chrome 直接读取不必把大体积 base64 塞进消息通道。网络捕获。network-capture-start/network-capture-read借 CDP Network 域记录请求与响应请求体上限 1MB、响应体上限 8MB超限截断并标注truncated与真实大小遇到 HTTP 30x 重定向会保留原始 POST body重定向 hop 复用同一 requestId 时不做覆盖readNetworkCapture读取后即清空避免同一条记录被重复消费。opencli doctor 排障速查连接不上先到chrome://extensions确认扩展已安装且启用看到 Extension not connected 时先跑opencli doctor检查 daemon 与扩展的握手状态attach 失败报错attach failed: Cannot access a chrome-extension:// URL说明有其他扩展干扰临时禁用其他扩展再试源码在重试失败时就会给出这条提示弹窗圆点怎么读红点未连接、橙点连接中、绿点已连接顺手可以核对 daemon 版本与当前 ProfilecontextId想看扩展内部发生了什么扩展会把console.log/warn/error经 WebSocket 转发给 daemonforwardLogCLI 侧能看到连接、重连、租约创建与释放等内部事件。写在最后权限清单不长debugger、tabs、cookies、downloads各换回一项真实能力没有多余申请命令通道外面套着指数退避与命令日志两道保险AI Agent 可以明确判断这次重试安不安全标签页租约随空闲超时自动回收活跃命令脚下又绝不会拆台。这套最小权限面 高可靠命令通道 重试安全 租约回收的取舍就是让 AI Agent 稳定驾驭你已登录浏览器背后的全部成本。【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址: https://gitcode.com/gh_mirrors/ope/OpenCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
