自托管的 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 把请求交给 Server,Server 核对授权后再派发给客户端。桌面客户端和 Chrome 扩展可以各自接入。每个 Chrome Profile 都可以注册为一个浏览器设备,并为任务打开独立标签页。
准备一个支持 Streamable HTTP 的 MCP 客户端,按以下步骤部署 Server 并让 Agent 列出第一台设备。已有 Yuxi 的用户可先看 Yuxi 集成。
以下命令使用 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 反向代理。部署与源码运行
使用 --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 授权。
按需安装客户端,并填写设备可以访问的 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 操作。发布产物 · 安装与绑定
完成后,在管理台确认设备已上线。
在管理台创建 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 授权、客户端能力开关和系统权限。 |
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两台 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 许可证