chrome-bridge

Chrome Bridge

作者：frsorrentino · npm chrome-bridge-mcp · 与其他名为 “chrome-bridge” 的项目无关。

Claude Code 可以借用你正在使用的 Chrome 标签页——保留登录状态、扩展程序和 Cookie——并在其中操作，然后将标签页交还给你。只有人才能完成的操作（登录、输入 2FA 验证码、通过 CAPTCHA、做出选择）会通过 handoff 交还给你：页面中会显示横幅，你完成操作后，Agent 继续执行。

与官方浏览器扩展程序对比（配对运行，29/09/2026，每项任务 n=5，使用相同模型）：填写表单，回合数减少 4.7 倍，成本降低 2.8 倍；在 1,500 行的表格中查找一行，回合数减少 2.3 倍，成本降低 3.4 倍；调试故障页面，回合数减少 9.3 倍，成本降低 4.3 倍。正确回答 15 题，共 15 题；对比结果为 12 题（bench/RESULTS.md）。工具集规模约为 3 倍，且无需付费套餐。通过本地 WebSocket 桥提供 60 种 Web 开发工具（导航、DOM 检查、视觉回归、审计、网络模拟），另提供用于 CI 的无头实例。可自托管，仅限本地运行。兼容 ChromeOS。

快速开始

需要 Node.js 18+ 和 Chrome 135+。

git clone https://github.com/frsorrentino/chrome-bridge.git
cd chrome-bridge && ./install.sh

1. 打开 chrome://extensions，启用开发者模式，点击加载已解压的扩展程序，选择 extension/ 文件夹。
2. 重启 Claude Code。

然后提出类似 “打开 localhost:3000，运行无障碍审计并找到 Sign Up 按钮” 的请求：Claude Code 会调用 navigate、audit 和 find_text。由于 navigate 已返回元素引用，接下来可直接调用 click(ref="n1")，中间无需额外的发现步骤。

在 ChromeOS/Crostini 上，请改为从 Chrome 网上应用店 安装：每次重启后，未打包的扩展程序都会被移除，因为 Chrome 启动时容器尚未挂载。

在 Windows 上，install.sh 无法通过 PowerShell 或 cmd 运行。请使用下方的插件安装方式（claude plugin marketplace add frsorrentino/chrome-bridge，然后运行 claude plugin install chrome-bridge@chrome-bridge），并搭配从网上应用店安装的扩展程序；或者从 Git Bash 运行 install.sh。插件的错误日志钩子会在 Git Bash 中运行，因为 Claude Code 会运行每个钩子；它们需要 Python 3.8+，并且 Python 可通过 python3、python 或 py 调用（会跳过 Microsoft Store 的 python3 别名）。如果没有 Python，这些钩子会保持静默，工具照常工作。有关启动模式，请参阅下方的 CHROME_BRIDGE_BROWSER：Google Chrome 无法在该模式下加载扩展程序，Microsoft Edge 可以。

install.sh 会使用 --scope user 注册 MCP 服务。也可以手动注册：claude mcp add --scope user chrome-bridge node /path/to/server/index.js。若要使用 execute_js，请在 chrome://extensions → Chrome Bridge → 详情中启用允许用户脚本（在 Chrome 135-137 上，请改为启用开发者模式）。

作为插件使用，无需克隆： 在 Claude Code 会话中运行 /plugin install chrome-bridge --marketplace frsorrentino/chrome-bridge（一条命令，需 Claude Code 2.1.275+；旧版本请先运行 /plugin marketplace add frsorrentino/chrome-bridge，再运行 /plugin install chrome-bridge@chrome-bridge）。在 shell 中，claude plugin install 没有 --marketplace 选项：请先运行 claude plugin marketplace add frsorrentino/chrome-bridge，再运行 claude plugin install chrome-bridge@chrome-bridge。无论哪种方式，插件都会从 npm 注册 MCP 服务（具备全部功能），并同时安装 recipes 技能；支持 Agent Plugins 1.0 的客户端则可从 plugin.json + mcp.json 获取相同内容。扩展程序仍需从网上应用店或 extension/ 安装。请选择一种安装方式：插件和 install.sh 会重复注册同一个服务；在 claude.ai 上从 Anthropic 目录添加插件（它会以 chrome-bridge@synced 的形式进入 Claude Code）后再通过市场安装，也会造成重复注册。在 claude.ai 聊天中，插件只会加载 recipes 技能：工具需要 Claude Code，或在你的电脑上运行的 Cowork，以便启动本地 MCP 服务。

你的浏览器，你的登录状态

无需空白配置文件、调试端口或云端浏览器。扩展程序在你的 Chrome 中运行，因此你已登录的所有网站都已向 Agent 开放：网页邮箱、托管控制面板、客户的后台、需要基本身份验证的预发布站点。Agent 打开的标签页会标记为其自身标签页，并在会话结束时关闭；你的标签页仍归你所有。

当页面需要只有你才能提供的信息时，Agent 不会猜测，也绝不会输入凭据。handoff 会在页面中显示横幅，说明所需操作——“完成 2FA 登录，然后按完成”、“点击你指的按钮”——并等待你操作；之后会从中断处继续，包括处理重定向。它也可以在横幅中提问并读取你输入的回复，或者让你选择页面上的一个或多个元素。

为什么选择 Chrome Bridge？

	Chrome Bridge	Claude in Chrome	Chrome DevTools MCP	Playwright MCP
ChromeOS / Crostini	支持（真实主机）	不支持	仅容器	仅容器
工具	60（43 个核心工具）	22	默认 29 个（启用标志后为 56 个）	24 个核心工具（共 71 个）
需要付费套餐	不需要	需要（Pro+）	不需要	不需要
网络模拟	支持（存根/标头）	不支持	不支持	支持
视觉回归	支持（screenshot_diff）	不支持	不支持	不支持
审计（a11y/SEO/sec）	支持（一次调用，报告写入磁盘）	不支持	Lighthouse	不支持
无头模式 / CI	支持	不支持	支持	支持
GIF / 视频	不支持	支持	部分支持	不支持
断点 / 堆	不支持	不支持	支持	不支持

Codex for Chrome（OpenAI，2026 年 5 月）属于 Claude in Chrome 一栏：它是官方扩展，拥有 debugger 权限，仅支持 macOS 和 Windows，且需要 ChatGPT 应用。Claude in Chrome 的文档自 2026 年 9 月起注明支持 Linux 桌面版；ChromeOS 和 WSL 仍不支持。竞品数据测于 2026-09-01 和 2026-09-11（docs/analisi-2026-09-11-concorrenti.md）。

它在往返次数方面占优——使用简短的元素引用，而不是反复截图并点击；fill_form 可在一次调用中填写 N 个字段。在大型页面上，它的负载也更小：表格筛选在服务端完成。但对于表单，每一轮实际花费反而略多。

完整基准测试——包括方法、所有原始运行结果（包括不利结果），以及测试框架无法衡量的内容——见 docs/EFFICIENCY.md。

使用方法

skills/chrome-bridge/SKILL.md 中的技能让工具变得易于发现：其中包含触发每个工具的短语对应的操作指南（“验证邮件是否送达”“使用测试卡测试结账流程”“哪个插件拖慢了页面”“同意前触发了什么”）、工具调用顺序，以及模型原本根本无法看到的零令牌 CLI 命令。install.sh 会将其复制到 ~/.claude/skills/chrome-bridge；对于其他客户端，可手动执行相同操作。

除了 MCP 工具，还有两种工作方式可以让工作完全不经过模型。

CLI — 批量操作，在内容进入上下文前通过 grep 或 jq 进行管道处理：

chrome-bridge navigate --url https://example.com
chrome-bridge read_console --level error | head -20
chrome-bridge assert --selector "#success" --text "Done"
chrome-bridge replay --file ./recordings/login.jsonl

启动模式 — 使用独立的 Chromium 实例和临时配置文件，用于隔离会话或 CI：

node server/index.js --launch --headless

它会在 Linux、macOS 和 Windows 上的标准路径中查找 Chromium、Microsoft Edge、Brave，最后查找 Google Chrome；CHROME_BRIDGE_BROWSER 可指定其他二进制文件。Google Chrome 137+ 会忽略 --load-extension，因此扩展无法在其中连接：请使用 Chromium、Edge、Brave 或 Chrome for Testing。

搭配 session_record + replay 使用，即可在不让模型参与的情况下运行冒烟测试。在启动模式下，如果无法使用用户脚本开关，execute_js 会回退到 new Function。

工具

共 67 个。core（44 个工具，每个工具都在 101 次真实会话中使用过）默认加载；其余 23 个工具分布在 7 个可选能力组中，Agent 可在会话中通过 get_status({enable: ["visual"]}) 启用，无需重启（--caps 仍可在启动时设置）。

分组	数量	内容
核心与导航	13	标签页、窗口、navigate、screenshot、tile_windows
交互	11	click、fill_form、upload_file、对话框、剪贴板
DOM 与检查	12	read_page、extract、extract_table、query_dom、get_css_styles、watch_dom
调试与网络	8	execute_js、控制台、网络日志、模拟、track_events
视觉与响应式	5	screenshot_diff、视口与缩放、媒体模拟
审计	2	audit（一次调用即可检查 a11y、键盘、SEO、安全性、链接、vitals、css、资源和缓存）、cookie_audit
状态、存储与文件	10	存储、测试数据、MHTML、capture_downloads（导出文件并保存，不会显示“另存为”对话框）、录制、assert
动效与性能	6	animations、frames（长帧、CLS、INP）、perf_trace、screencast、lighthouse 和 heap_snapshot（启动模式）

所有工具及相关说明见：docs/TOOLS.md。

工作原理

Claude Code  <--stdio-->  MCP Server  <--WebSocket :8765-->  Chrome Extension
                          (server/)                          (extension/, MV3)

Node.js 服务负责处理协议和工具逻辑；MV3 扩展通过 Chrome API 执行命令。用户脚本（execute_js）通过 chrome.userScripts.execute() 运行。

配置和安全

每个环境变量都有对应的 CLI 标志：

变量	默认值	说明
CHROME_BRIDGE_PORT	8765
CHROME_BRIDGE_HOST / --host	127.0.0.1	仅当浏览器位于容器外部（ChromeOS/Crostini 端口转发）时，才使用 0.0.0.0，并且必须设置令牌
CHROME_BRIDGE_TOKEN	未设置	ext_init 和 relay_init 都必须提供。只要绑定地址不是回环地址，就强烈建议设置
CHROME_BRIDGE_CAPS / --caps	core	core、audits、visual、network、storage、dom、files、all。也可以在运行时通过 get_status({enable}) 启用可选功能
CHROME_BRIDGE_ALWAYS_LOAD / --always-load	最常用的 22 个工具	客户端整体加载服务时保留在上下文中的工具；其他工具会设置 _meta['anthropic/alwaysLoad'] = false，等待工具搜索（Claude Code 2.1.285+）。all 会加载所有工具；也可以用逗号分隔的列表指定工具
CHROME_BRIDGE_NO_JS / --no-js	未设置	禁止在页面中执行任意 JavaScript：execute_js 和 modify_dom 会从架构中移除，wait_for(condition=function) 和 javascript:/data: URL 会被拒绝。get_status 会报告 js_evaluation
CHROME_BRIDGE_READ_ROOT / --read-root	未设置	upload_file 可以从中读取文件的位置。未设置时：可读取除密钥和凭据之外的任何文件（~/.ssh、~/.aws、~/.gnupg、.env*、id_*、*.pem、*.key 等），并会先解析符号链接。设置后：只能读取此目录下的文件，无论文件名为何——这是有意上传证书密钥时的做法
CHROME_BRIDGE_BROWSER	未设置	仅适用于启动模式：浏览器可执行文件，例如 C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe。未设置时：使用在标准路径中找到的第一个 Chromium、Edge、Brave 或 Google Chrome（Linux 上优先 Chromium，其次 Google Chrome）。Google Chrome 137+ 无法加载该扩展
CHROME_BRIDGE_OBSERVE	未设置	设为 off 可停用下文所述的本地错误日志。插件会设置为 hook：其钩子会保留日志，服务本身不会介入
CHROME_BRIDGE_WRITE_ROOT / --write-root	未设置	模型选择的所有路径（save_to、output_path、导出文件）都必须位于此目录下，并会在浏览器执行任何操作前进行检查；服务自身在 ~/.config/chrome-bridge 下的状态文件仍可写入。CLI 运行于你的 shell 中，不受此限制

桥接服务绑定到回环地址，仅接受来自 chrome-extension:// 来源的扩展连接；设置令牌后，两次握手都必须提供令牌。未设置令牌时，任何本地进程都可以充当中继，在你已通过身份验证的浏览器会话中执行 execute_js。其他 MCP 实例通过回环地址连接，并会收到 relay_init_ok 确认，因此持有该端口的外部进程会迅速失败，而不会逐条命令等待超时。

不会受到保护的内容：页面内容会未经筛选地传递给模型，因此恶意页面的文本属于不可信输入。get_storage、session_fixture、HAR 导出和屏幕截图不会脱敏，可能包含 Cookie、令牌或个人数据。不要让自动化访问含有你不愿粘贴到聊天中的秘密信息的页面。

威胁模型

chrome-bridge 会将你已登录的真实浏览器交给 AI Agent 使用。按能力对 MCP 服务进行评级的扫描器会将其标记为可执行代码（execute_js）、发送携带你 Cookie 的请求（http_request）以及读取私人页面数据（get_storage、get_tabs）。这些是产品功能，不是缺陷。关键在于谁能访问这些功能，以及恶意页面能诱使 Agent 用它们做什么。

• **谁可以连接：**参见上文——绑定到环回地址、检查 chrome-extension:// 来源，并在两次握手中都验证 CHROME_BRIDGE_TOKEN。
• 启动模式也会开放一个 DevTools 端口，位于 127.0.0.1（由系统选择），供 lighthouse 和 heap_snapshot 使用。CDP 没有身份验证：运行期间，任何本地进程都能操控这个专用浏览器。它使用临时配置文件，不会保存你的任何数据；你自己的 Chrome 不会开放端口。
• 调试栏是信号。click/press_key 使用 trusted、emulate_media via: "debugger"、perf_trace 和 screencast 时，会仅在执行相应操作期间将 chrome.debugger 附加到一个标签页；期间 Chrome 会显示“此浏览器已开始调试”提示栏，取消后操作也会结束。
• **真正的风险是提示词注入。**网页可以要求 Agent 运行 JavaScript、发送携带你 Cookie 的请求、提交表单或上传文件。请将自动化处理的所有网页都视为不可信输入；对于持有资金或凭据的网站，请仔细检查 Agent 提议的操作。
• 缩小攻击面：--caps core（默认值）只开放最小功能集；--no-js 会移除任意 JavaScript 执行功能；--write-root 会限制模型可写入的所有路径；upload_file 会拒绝密钥和凭据，且 --read-root 会将其限制在一个目录中。对于重要会话，请使用单独的 Chrome 配置文件进行自动化操作。
• --no-js 并非沙箱：inject_css 仍然可用，带有 url() 的 CSS 属性选择器可能会将属性值泄露给远程主机。
• 离开你设备的数据，就是浏览器代替 Agent 发送的数据。chrome-bridge 本身不收集遥测数据；除非你同意提交问题，否则下方的错误日志会保留在本地。

本地错误日志

当 chrome-bridge 自带的某个工具出错时，它会在本地文件 ${XDG_STATE_HOME:-~/.local/state}/claude-observe/chrome-bridge.jsonl（权限模式为 0600，所在文件夹权限为 0700）中添加一行，格式采用 claude-observe 格式（插件的副本位于 observe/）。使用插件时，由 PostToolUseFailure 钩子写入；单独使用 npm 服务时，则由服务写入。再次出现相同错误时，会合并为一行，并增加计数。

• 保留内容： 工具名称、清理后的错误文本（你的主文件夹会替换为 ~；电子邮件地址、URL 查询参数、密钥和输入的值会被移除）、参数名称和文本值的长度、chrome-bridge 版本、操作系统、工作文件夹名称以及 Claude Code 配置文件夹名称。使用插件时，还会保留 Claude Code 和模型版本、 会话 ID 以及最近调用的三个工具的名称。
• 绝不保留： 参数值——不包括 URL、选择器、输入的文本或页面内容。
• 除非你同意，否则任何内容都不会离开你的电脑。 使用插件时，错误累积到一定数量后（或某条错误已等待几天，或被标记为缺陷），一轮操作结束时会显示提示；Claude 可能会在合适的时候提议将这些错误作为一个 GitHub issue 发送：它会先向你展示匿名化文本，然后通过按钮征求同意（使用你的 GitHub 账号发送，或暂不发送），并且只发送你选择的内容。/chrome-bridge:observe send 可按需执行相同操作；list、mark 和 add 用于读取日志并进行分类。单独使用服务时，绝不会发送或提议发送任何内容。
• 安全观察记录（越界读取或写入、密钥泄露、未经授权的代码执行、数据离开电脑）绝不会进入公开 issue：/chrome-bridge:observe send --security 会为维护者准备一份私密漏洞报告，详见 SECURITY.md。
• 关闭此功能： 在 ~/.config/claude-observe/config.json 中设置 {"enabled": false}（适用于每个使用 claude-observe 的插件），或为服务设置 CHROME_BRIDGE_OBSERVE=off。保留日志但停止提议：设置 {"propose": false}。

故障排查

症状	原因 / 修复方法
Chrome extension not connected	扩展已停用，或其端口与服务端的端口不同。错误会显示实际主机 / 端口；请在弹出窗口（⚙）中检查。
端口 8765 已被占用	这是预期行为：第二个 MCP 会话会成为中继，并共用同一个桥接。设置 CHROME_BRIDGE_PORT 可使用单独的端口。
Port N is held by a process that is not chrome-bridge	该端口被其他程序占用。请释放该端口或更改 CHROME_BRIDGE_PORT。
execute_js 失败	在 chrome://extensions → Chrome Bridge → Details 中启用 Allow user scripts（Chrome 138+；在 Chrome 135-137 中启用 Developer Mode）。
read_console 返回 note=Instrumentation not loaded	页面是在扩展启动前打开的、“Capture console & metrics”已关闭，或页面不可注入（chrome://）。请重新加载页面。
截图超时，或出现 image readback failed	窗口最小化或被完全遮挡时会停止生成帧；捕获会在 10 s 后失败。请将窗口置于前台。
wait_for/scroll 返回 page_hidden: true，页面停止更新	原因相同：Chrome 不会渲染隐藏页面，并会降低其计时器的运行频率（几分钟后，每分钟只唤醒一次）。get_page_info 会报告 visibility。请将窗口显示在屏幕上，或使用 create_tab 并指定 new_window 和边界。
screenshot presets 显示 NOT APPLIED	预设会调整窗口大小，但不会模拟手机（不设置设备像素比、UA 或触控）。窗口管理器会强制设定最小宽度，且窗口不会超出屏幕范围（例如，在 1536×864 的 ChromeOS 屏幕上，视口最大为 1536×686）。如需模拟手机，请将 emulate_media 与 device 配合使用（通过调试器），或使用无头浏览器获得更大的视口。
type_text 返回 mismatch: true	字段拒绝了该值。来自扩展的事件具有 isTrusted: false，某些控件（日期选择器、带分词器的搜索框）会丢弃这些事件。请尝试 mode: 'keys'，然后使用网站自身的控件（日历按钮），或使用 handoff。
截图位置显示 [media removed: request limit]	这是 MCP 客户端写入的，不是桥接写入的：单个请求中的图片过多。请使用 save_to，或使用 region 和较小的 scale 调用 element_screenshot。
命令起初有效，之后停止工作	MV3 服务工作进程已重启，内存状态（网络日志、diff 基线、HTTP 身份验证）已重置。请重新运行监控调用。
每次 ChromeOS 重启后扩展都会消失	请从网上应用店安装，而不是使用 Load unpacked。
工具未出现在列表中	它属于选择加入组。请检查 get_status → caps_available，然后设置 CHROME_BRIDGE_CAPS=all。
claude mcp get 未显示命令、参数或环境	这是预期行为：自 Claude Code 2.1.285 起，对于插件提供的 stdio 服务，插件会隐藏这些信息（变量名仍会显示）。get_status 会报告服务端和扩展版本、模式、主机、端口和 caps；/mcp 会显示连接状态。
弹出窗口显示 «In attesa: un altro browser è collegato»，get_status 列出 refused_browsers	两个装有该扩展的浏览器连接到了同一个端口。已连接的浏览器会保留桥接；另一个浏览器每隔 15 s 重试一次，并会在第一个浏览器断开后接管。get_status → browser 会显示已连接的浏览器。此前，最后连接的浏览器会悄无声息地接管。

文档

• docs/TOOLS.md — 按组列出的全部 67 个工具
• docs/CAPABILITIES.md — 桥接可以绕过什么、不能绕过什么；每面墙记录一个带日期的状态
• docs/EFFICIENCY.md — 基准测试及其背后的设计
• docs/PERFORMANCE.md — 真实路径上各工具的延迟，npm run bench:latency
• bench/RESULTS.md — 原始运行记录和纳入规则
• CHANGELOG.md

测试

npm test（无需 Chrome，约 22 秒）· npm run test:e2e（需要 Chrome 和已连接的扩展；如果已有桥接服务运行在 8765 端口： CHROME_BRIDGE_PORT=8799 node test/test-devtools.js --launch，此命令会使用 extension/ 打开独立的 Chromium）· npm run measure（架构成本）· npm run bench:latency（每个工具的耗时，单位为毫秒；会启动独立的 Chromium，并写入 docs/PERFORMANCE.md）。

相关项目

• agent-webbridge — 同时驱动多个 Chrome 配置文件，并行打开标签页
• awb-recipes — 由社区维护、按网站整理的带日期的配方，用于自动化操作已登录的网站

许可证

MIT