教程2026-11-08 · 智涌AI

Browse MCP 上手:白名单、交接和自动更新

Browse MCP 上手头图:安装、配对、给会话加站点白名单、登录交接四点流程

编程 Agent 要查内部控制台、复现线上页面,最烦的是再开一个无头浏览器、把所有后台重新登一遍。OpenCode Browse 用一个 MCP 服务器加一个 Chromium 扩展,让 Agent 直接开你日常用的浏览器:标签页、登录态、已经装好的扩展都能沿用。仓库 MIT 许可。2026 年 11 月 8 日查阅 GitHub,最新正式版是 v0.0.15(北京时间当天 08:10 发布),星标 276。它能接到 Claude Code、OpenCode、Cursor、Codex、Zed 等客户端。Agent 拿到的是你的真实会话,白名单、交接和自动更新开关要先设好。

前置条件

本文按 2026 年 11 月 8 日查阅的 Browse 产品页、anomalyco/browse 的 README 与 v0.0.15 Release,以及 Claude Code 官方 MCP 文档整理。你需要一台能装 Chromium 内核浏览器的电脑:Chrome、Edge、Brave、Arc、Helium、Vivaldi、Opera 或 Chromium 都可以。用 npx @opencode/browse install 时,本机还要有 Node.js 22.19 或更新版本。已经装好 Claude Code、OpenCode 或其他 MCP 客户端更好;安装向导也可以先勾一个还没装的客户端,以后再连。

无头浏览器、独立 profile 的隔离做法,见站内 Playwright 浏览器沙箱;浏览器工具的上下文开销见 Agent 浏览器工具对比。这篇写 Browse 接到你的真实浏览器之后,边界怎么设。

先装扩展和 MCP,再选要接入的 Agent

产品页建议先从 Chrome 应用店装扩展,扩展会带着走完后面的步骤。要直接装 CLI,官方给了这几种写法:

npx @opencode/browse install
# 或者
curl -fsSL https://opencode.ai/browse/install | bash
# Windows PowerShell
irm https://opencode.ai/browse/install.ps1 | iex
# 已经全局安装过包的话
npm install -g @opencode/browse && browse install

npx 路线会把包装到全局,好让各个 Agent 从 PATH 里找到 browse。二进制安装脚本会把命令放到 ~/.local/bin(若设置了 XDG_BIN_HOME 就用那个目录),从 Anomaly 的发布服务拉取对应架构的文件,并核对其大小和 SHA-256。文件落在 XDG 目录里:~/.config/browse、~/.local/share/browse、~/.local/state/browse、~/.cache/browse。

交互式安装分两步。第一步选 Agent:已经检测到的会默认勾上,用方向键和空格改勾选,回车确认。你可以去掉 OpenCode、勾一个还没装的客户端,或者一个都不选、只留 CLI。下一次再跑安装时,会记住你上次的选择。第二步装扩展:安装程序打开 Chrome 应用店里的 browse,你点添加之后它会自动配对;扩展已经在的话,它会打开带一次性配对码的设置页,不用你手工复制。

要跳过选择器、直接写给 Claude Code 或同时写给几个客户端:

browse install -a claude
browse install -a claude cursor
browse install -a '*'    # 所有它认识的客户端
browse install -y        # 普通终端里,给已检测到的客户端

README 写明:Claude Code 的用户级配置在 ~/.claude.json,键名是 mcpServers;OpenCode 在 ~/.config/opencode/opencode.json(或 .jsonc),键名是 mcp.servers。对其他走 stdio 的 MCP 客户端,条目是:

{ "mcpServers": { "browse": { "command": "browse", "args": ["mcp"] } } }

Claude Code 也可以按官方 MCP 文档自己登记本地 stdio 服务器:claude mcp add browse -- browse mcp,再用 claude mcp list 看是否显示已连接。安装程序认不出是哪个 Agent 在调用时,不会擅自写配置,只会把上面这条 MCP 条目和对应的 browse install --agent … 打到终端,让你自己补。

配对没自动完成时,再跑一次 browse install,或执行 browse pair:它会启动中继并等待。打开「扩展 → browse → 选项」,展开高级(或点「用代码配对」),填入打印出的配对码,点 Connect。配对码一次性有效,10 分钟内要用;连续输错 5 次,所有待用码作废。浏览器用它换一把自己的密钥,之后每次连接双方都要证明持有这把密钥。中继默认只听 127.0.0.1:19988。

给每个会话加上站点白名单

Browse 的工具表里,session_new 可以带 allowedOrigins,之后也能用 session_allowlist 改。命令行写法是 session new --allow-origin example.com,或事后再 session allow。加上之后,中继会拒绝 Agent 导航到名单外的主机、拦下或清空跳出名单的链接和脚本跳转,并关掉开到别处的弹窗。内网、回环和链路本地地址必须写精确主机名;它会先解析名字,再核对文档真实的远端 IP,用来对付 DNS 重绑定。

白名单是可选项。不设的话,Agent 能走到你已经登录的任何站点。新开会话时就该写下 allowedOrigins,别等它先摸到网银再补。

有两点容易看漏。子资源(图片、fetch、iframe、worker)不会被拦:请求拦截要和 Playwright 的 page.route() 共用,中继没法稳定独占。走本地代理时,每个文档看起来都像来自代理地址,主机名更要写准。Cookie 默认只能读写本会话自己页面的;清 Cookie、清缓存、关浏览器这些操作一律拒绝。page.bringToFront() 也被拒绝,避免 Agent 把窗口抢到你工作前面。

方案用哪套浏览器登录态更适合
Browse你日常用的 Chrome / Edge 等沿用已有标签页和登录查内部控制台、复现线上问题、带登录的检查
无头 Playwright 或独立 profile单独拉起的浏览器进程要重新登录,和日常会话隔离自动化测试、不想把真实邮箱和后台交给 Agent

登录、两步验证和付款,交还给人点 Continue

Agent 用 Playwright 在后台标签组里开页、点击、截图、录屏,还能把网络请求导出成经过脱敏的 HAR。这些标签默认收在标签栏开头的折叠分组里,闲置 10 分钟会自己关掉(脚本正在跑、交接在等、或正在录像的标签除外)。Agent 不能把你切到它的标签,也不能把窗口提到前台。

轮到你处理登录、两步验证或付款时,页面上会出现一张写着站点来源的小卡片。做完人工步骤,点卡片上的 Continue,或点工具栏按钮。只有真实点击能结束交接,页面脚本仿造不了。工具栏按钮也可以反过来用:你在某个已经打开的标签上点一下,就把这个标签借给 Agent,徽章显示 ON;再点一次拿回来。Agent 工作时徽章是 RUN,等你时是 WAIT。脚本还在跑的时候点一下,会立刻停脚本并把标签还给你。你借出去的标签,Agent 关不掉。

浏览器自己的调试条(Chrome 上是 Cancel,有的浏览器是 OK)会断开 Browse 和所有标签的连接:你借出的标签回到你手里,Agent 自己开的标签先留着,等闲置清理再关。站点密钥可以事先用 browse secrets add --origin https://example.com 存好,Agent 只能通过 secrets.type() 在对应站点的输入框里填,值不会进执行环境、日志、会话日记和 HAR。官方建议把密钥和白名单一起用;存了 TOTP 种子等于少了一道人工关口,能自己点两步验证时,继续交给自己。

默认每小时会自动更新,关掉要自己动手

更新默认是开着的。二进制安装会在启动时、并且至少每小时一次读取频道清单;npm 安装则每小时查一次 npm 的 dist-tag。发现新版本后,中继在没有 Agent 占用浏览器时于后台重跑当初的安装方式,并替换 ~/.local/bin/browse 或执行 npm install -g @opencode/browse@…,不会改 OpenCode 的配置。正在跑的 MCP 服务器会在两次工具调用之间切到新构建。

想改成「只告诉我」或「不要检查」,打开扩展的设置页,在 Updates 里选 Only tell me 或 Don't check。命令行是 settings set autoUpdate=notify,环境变量是 OPENCODE_BROWSER_AUTO_UPDATE=off(notify 表示只提示,on 是默认的空闲时安装)。Agent 能从 status 读到当前值,但 MCP 的 settings 工具读不了也改不了更新行为,这个开关留在你这边。立刻更新用 browse update;回退则按安装方式重跑,并带上 --channel 或 --version。扩展本身仍由 Chrome 应用店更新。

另外三个只能用环境变量改、不能交给 Agent 的开关:OPENCODE_BROWSER_ALLOW_NODE=1 会让 execute 拿到完整的 Node(process、fs、import()、任意文件路径);OPENCODE_BROWSER_ALLOW_ALL_COOKIES=1 放开读写整个浏览器配置里的 Cookie;OPENCODE_BROWSER_ALLOW_FOREGROUND=1 允许 page.bringToFront()。改完这些变量后要执行 browse 的 relay restart(README 写的是 node cli/dist/cli.mjs relay restart)。默认的 execute 跑在受限的 JavaScript 环境里:没有 Node API,同步代码大约 2 秒会被打断。它和中继共享进程,官方写明这不是安全边界,把 Agent 跑的代码当成你自己在跑。

常见坑

完成标准

最后

先跑 npx @opencode/browse install,在向导里勾上你正在用的 Claude Code 或 OpenCode,装好扩展并完成配对。然后对 Agent 说「开一个只允许 example.com 的会话,打开它的首页并告诉我标题」——把 example.com 换成你真正要它碰的那个站点。能走通,再考虑要不要把登录过的控制台借给它。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。