Skip to content
xerrorsPublic

About

aBridge 是一个开源的 MCP 桥接工具,让 AI Agent 在你的授权下操作电脑和浏览器,完成网页交互、文件处理和命令执行等任务。浏览器扩展可以沿用你已有的网站登录状态,直接在熟悉的工作环境里做事。

Resources

Contributing

Security policy

Stars

19 stars

Watchers

1 watching

Forks

Repository files navigation

aBridge

自托管的 MCP 服务,让 Agent 在你授权的设备和浏览器中执行任务。

快速开始 · 选择客户端 · 评测与验证 · Yuxi 集成 · 开发与文档 · 下载

在自己的机器上运行 aBridge Server,再把要用的设备接进来。你可以为每个 Agent 单独指定设备、能力和有效期。

选择客户端

想完成的任务 客户端 环境
在已登录的业务系统里查资料、填表 浏览器扩展 · 观察、导航和操作网页,复用所选 Profile 的登录态 Chrome 116+
查看 Mac 窗口、操作原生应用或处理文件 macOS App · 屏幕、键鼠、Shell、UTF-8 文件 Apple Silicon,macOS 14+
查看 Windows 桌面、操作前台应用或处理文件 Windows 客户端预览 · 截图、前台键鼠、Shell、UTF-8 文件 Windows 10/11 x64,未签名便携 ZIP
在开发机或服务器上执行 Shell、读写文件 Linux CLI · Shell、UTF-8 文件,支持 systemd 后台运行 Linux amd64 / arm64
操作 Android 应用、读写授权目录 Android App · 屏幕、点按、滑动、文本输入和目录读写 Android 11+

工作方式

Agent 通过 MCP 连接 aBridge Server,macOS、Windows、Linux、Android 和浏览器客户端分别通过 WebSocket 连接 Server。

Agent 通过 MCP 把请求交给 Server,Server 核对授权后再派发给客户端。桌面客户端和 Chrome 扩展可以各自接入。每个 Chrome Profile 都可以注册为一个浏览器设备,并为任务打开独立标签页。

快速开始

准备一个支持 Streamable HTTP 的 MCP 客户端,按以下步骤部署 Server 并让 Agent 列出第一台设备。已有 Yuxi 的用户可先看 Yuxi 集成。

1. 部署 Server

以下命令使用 GitHub Release v0.4.23 的 Server tarball。运行需要 npm 和 Node.js 22.x(22.13 起)、23.x(23.4 起)或 24 及以上版本。

npm exec --yes \
  --package=https://github.com/xerrors/aBridge/releases/download/v0.4.23/xerrors-abridge-0.4.23.tgz \
  -- abridge --web

在 Windows PowerShell 中运行:

npm.cmd exec --yes --package=https://github.com/xerrors/aBridge/releases/download/v0.4.23/xerrors-abridge-0.4.23.tgz -- abridge --web

默认监听 127.0.0.1:8765。--web 在本机打开实例管理页面,可通过 --data-dir 指定持久目录。

使用 Docker

下面使用已发布的 0.4.23 镜像,支持 Linux amd64 和 arm64。

docker run -d --name abridge --restart unless-stopped \
  -p 127.0.0.1:8765:8765 \
  -v abridge-data:/data \
  -e ABRIDGE_PUBLIC_ORIGIN=http://127.0.0.1:8765 \
  ghcr.io/xerrors/abridge:0.4.23

镜像版本单独发布。更新时复用 abridge-data 卷。通过 GHCR 镜像列表 查询可用标签。

跨机器连接时,设备和 Agent 都需要能访问 Server。请设置对外的 ABRIDGE_PUBLIC_ORIGIN,并配置支持 WebSocket 的 HTTPS 反向代理。部署与源码运行

2. 创建账户

使用 --web 启动时,浏览器会打开实例管理员链接。使用上述 Docker 命令时,在本机终端获取该链接:

docker exec abridge node -e '
const fs = require("node:fs");
const token = fs.readFileSync("/data/server.db.admin-token", "utf8").trim();
console.log(process.env.ABRIDGE_PUBLIC_ORIGIN + "/#admin_token=" + encodeURIComponent(token));
'

该链接包含管理员凭据,请勿分享。在“实例管理”中创建普通账户,再以普通账户登录管理台,进行设备绑定和 Agent 授权。

3. 连接设备

按需安装客户端,并填写设备可以访问的 Server 地址。

  • 浏览器扩展。在想授权的 Profile 中安装扩展并完成浏览器授权。Chrome 应用商店 · 源码安装
  • macOS App。下载 macOS ZIP,经浏览器授权后在系统设置中开启所需权限。v0.4.23 的 ZIP 使用 ad hoc 签名。发布产物 · 安装与权限
  • Windows 客户端预览。下载未签名便携 ZIP,完整解压后启动 aBridge.exe,填写服务端网址并在浏览器中确认授权。下载、安装与绑定
  • Linux CLI。下载对应架构的包,用管理台签发的 Device Token 绑定。发布产物 · 安装与绑定
  • Android App。下载签名 APK,用 Device Key 绑定,在 Android 设置开启无障碍,再回到 App 允许 Agent 操作。发布产物 · 安装与绑定

完成后,在管理台确认设备已上线。

4. 连接 Agent 并验证

在管理台创建 Agent 连接,选择刚上线的设备、所需能力与有效期,保存生成的 Agent Key。使用「复制接入参数」获取 MCP 端点和请求头。端点以 /mcp 结尾,请求头为 Authorization: Bearer <AGENT_KEY>。远程 Agent 应使用它能访问的 Server 地址。

以本机的 Codex CLI 为例,将 Agent Key 通过私有环境变量 ABRIDGE_AGENT_KEY 提供给 Codex 进程,再添加 MCP Server 并启动新会话。Codex MCP 配置

codex mcp add abridge --url http://127.0.0.1:8765/mcp --bearer-token-env-var ABRIDGE_AGENT_KEY
codex

请调用 aBridge 的 devices_list,列出已授权设备的名称、在线状态和当前可用的能力。

看到刚绑定的设备,就验证了 MCP 接入和设备授权。devices_list 只读取设备信息。执行任务时,Agent 用 session_open 为目标设备申请所需能力,执行后用 session_close 结束会话。

连接失败或看不到设备
现象 检查
MCP 连接超时或返回 404 从 Agent 所在机器检查 Server 是否可达,确认 MCP 地址包含 /mcp。
MCP 返回 401 确认 MCP 客户端拿到了有效的 Agent Key。使用 Codex 时,检查启动它的环境是否包含 ABRIDGE_AGENT_KEY。
设备列表为空或缺少目标设备 确认设备出现在当前账户的管理台中,并且该 Agent 连接的授权范围包含它。
设备可见,但能力不可用 查看设备是否在线、是否已在本机恢复访问,并检查 Agent 授权、客户端能力开关和系统权限。

与 Yuxi 一起使用

aBridge 可以和 Yuxi 一起部署,使用 Yuxi 的账户和对外入口。服务之间通过容器网络通信,设备仍使用部署时为 aBridge 配置的地址。Yuxi

路径 账户登录 MCP 调用认证
独立使用 管理员创建本地账户 管理台生成的 Agent Key
Yuxi 集成 OIDC 单点登录 显式启用平台委托后,由平台签发短期委托令牌

OIDC 用于登录管理台。通过 Yuxi 调用 MCP 时,还需要启用委托并由 Yuxi 签发短期令牌。平台连接可以使用哪些设备和能力,仍由用户授权、本机开关和系统权限决定。OIDC 登录与平台 MCP 委托

评测与验证

评测结果按客户端和任务集记录。各套件使用自己的任务、种子和预算,完整数据与测量版本见报告。

客户端 公开 Agent 任务 已验证的范围 证据
Chrome 扩展 MiniWoB++ 12/12 实际 Chrome 扩展,6 类网页任务 方法 · 数据
Android 预览 AndroidWorld 回归 15/15(100%);挑战 15/30(50%) Android 13 模拟器,覆盖文件管理、笔记和跨应用任务 方法 · 回归数据 · 挑战数据
macOS App 暂无公开任务分数 原生 App 构建、设备连接与执行回归 原生验证
Windows 客户端预览 暂无公开任务分数 Windows x64 CI 验包,覆盖设备绑定、权限控制、Shell 和文件操作 Windows 验证
Linux CLI 暂无公开任务分数 amd64 / arm64 CI,真实 Server 联调覆盖 Shell 和文件工具 Linux 验证
Chrome MiniWoB++ 逐题结果、耗时与复现

使用 gpt-6.1-sol(medium) 运行 MiniWoB++ 适配任务,共完成 12/12(100.0%)。任务、种子和预算在运行前确定,每例运行一次。

主对照使用种子 0 和 1,基线完成 5/12,修复后完成 12/12。基线已包含浏览器启动修复。两侧使用相同的模型目录、评测器、任务提示和预算。额外种子 2 单独运行,完成 6/6。审核排除 0 例。

浏览器工具优化前后对照

任务 修复前 修复后 Agent P50(秒) 工具调用总数 已知输入 / 输出 tokens 用量覆盖
form-sequence-3 2/2 2/2 72.0 12 417797 / 858 2/2
email-inbox-forward-nl 0/2 2/2 84.8 10 384893 / 1028 2/2
book-flight 0/2 2/2 146.1 23 852591 / 1711 2/2
navigate-tree 0/2 2/2 42.7 4 194238 / 498 2/2
click-menu-2 2/2 2/2 60.1 8 321924 / 812 2/2
multi-layouts 1/2 2/2 66.0 10 361814 / 820 2/2

每例限 180 秒和 40 次工具调用,并发 2。Agent 可以通过 DOM 和截图观察页面,也可以读取、操作和等待。P50 从 CLI 启动开始计时,包含模型调用及已启动的失败任务。表中的 token 是已报告样本的合计,输入包含缓存。缺少用量的样本记为未知。

失败分类:无。用量覆盖 12/12,会话清理 12/12。

两侧都通过 CLI 参数加载同一份从缓存逐字复制的模型目录,以避开目录刷新超时。实际耗时仍会随模型服务和网络变化。

模型目录的 SHA-256 为 578e4bab76fbd3999747b7d3c8c34b83a4cdbef4a3bd033f21f0399e094f1c3d。

测量版本为 v0.4.16(c02c42b)。环境为 Apple M4 / darwin arm64 / Chrome/153.0.8010.12 / Node v22.23.5 / codex-cli 0.166.0,记录于 2026-11-18T02:07:05.629Z。

结果对应 Chrome 扩展上的 6 类适配任务,每类 2 个种子,采用这里列出的时间预算。早期固定策略的 30/30 见执行链冒烟记录。评测方法 · 工具修复报告 · 全量报告 · 标准审核报告 · 逐次实测数据

npm run benchmark:miniwob

AndroidWorld

两台 Pixel 6 / Android 13 模拟器负责运行公开任务。Agent 通过 Android 客户端观察和操作,AndroidWorld 生成数据并独立判分。回归集覆盖文件管理与笔记编辑,挑战集增加了跨应用录入和长流程任务。独立的直接文件接口验收 3/3,单列于 AndroidWorld 报告。

授权与安全边界

  • 在管理台为每个 Agent 选择设备、能力和有效期。设备本机可以随时暂停访问或关闭能力,这些设置会在重连后继续生效。
  • 用 Admin Token 管理实例,用 Device Key 连接设备,用 Agent Key 调用 MCP。
  • 浏览器任务沿用该 Profile 的网站登录状态,页面脚本拥有当前用户的页面权限。Shell 和文件工具使用客户端所在账户的系统权限。
  • 操作途中断连或超时时,先查询原操作状态,再检查页面或文件是否已经改变。撤销权限会阻止后续操作,已发生的修改需要另行处理。

开发与文档

从源码开发需要 Node.js 22.13+(22.x)、23.4+ 或更新版本。安装依赖并运行完整检查:

npm install
npm run check

检查覆盖格式、架构、类型、自动化测试、打包和评测报告一致性。启动开发版 Server 可使用 npm run build 和 npm start -- --web。

官网与文档使用 VitePress,源码位于 docs/。在仓库根目录运行 npm run docs:dev 可本地预览,运行 npm run docs:build 可生成静态站点。向 main 提交 PR 时会检查官网构建,合并后由 GitHub Actions 自动发布到 GitHub Pages。

文档 内容
安装与维护 Docker、Node.js、App、反向代理、升级与 OIDC 配置
架构与执行契约 模块职责、工具接口、会话、去重、取消与结果语义
Windows 客户端 便携包、设备绑定、本机能力、更新与验证
浏览器客户端 Profile 授权、任务标签、网页工具及浏览器代码接口
Server API 管理员接口、Server 运行方式与分发说明
贡献指南 开发环境、检查命令与提交规范

下载发布产物 · 报告问题 · Apache-2.0 许可证

About

aBridge 是一个开源的 MCP 桥接工具,让 AI Agent 在你的授权下操作电脑和浏览器,完成网页交互、文件处理和命令执行等任务。浏览器扩展可以沿用你已有的网站登录状态,直接在熟悉的工作环境里做事。

Resources

Contributing

Security policy

Stars

19 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages