@ agentrq/ acp-gateway (英语)
代理客户协议网关可以远程访问您在代理RQ中的代理.
概览
@agentrq/acp-gateway 连接一个 代理客户协议( ACP) 代理(如双子座,Codex)给代理工作空间. AgentRQ会说ACP v1本身;网关通过WebSocket运行你机器上的代理,并管道它的ACP流到AgentRQ.
它会:
- 读取您的工作空间
.mcp.json为 AgentRQ 服务器的 URL 和 符号. - 启动代理——你给出的命令,或来自非加太公司注册处的指令.
- 把特工的血栓 输给RQ探员
/api/acp/v1端点,为行所取行,而不用解析. - 恢复已丢弃连接并重新启动已死亡的代理 .
先决条件
- 节点.js 第22页
- 无 或者说 线条
- 一个 非加太公司兼容代理人 (如双子座CLI)
- 一个 代理 服务器提供 ACP v1 的工作空间( S) (
/api/acp/v1(中文(简体) )
安装
cd acp-gateway
npm install
在全球范围内使用:
npm install -g @agentrq/acp-gateway
当前版本
0.4.1
使用量
快速启动
运行 acp-gateway 从您的代理工作空间根( 包含 .mcp.json:
# From workspace root
acp-gateway -- gemini --acp
或有自定义命令:
acp-gateway -- your-acp-agent --flag1 --flag2
CLI 选项
您可以在前端指定网关选项 -- 分隔符 :
--max-concurrency编号 :--maxConcurrency<number>: 设置允许同时启动非加太代理的最大任务数量。 默认为1,并且可以是从1改为64。这是网关开始的限度;它可以在从代理界面运行时被更改.--agent <registry-id>:从ACP注册处运行一个代理,而不是您自己提供的命令.--list-agents:打印注册簿中的每一个代理,以及每个代理如何在这个机器上运行,然后退出.--list-models:打印代理支持的模型,然后退出.--model <model-id>:选择会话开始的模型。 在从代理界面运行时可以更改.--effort <level>:选择代理的初始推理努力水平(例如.low, (中文(简体) ),medium, (中文(简体) ),high) (中文(简体) ).--allow-unverified-agent: 安装一个不发布校验和的注册 二进制 。 默认关闭.--registry-url <url>: 读取不同的注册索引(用于打针,或测试).--mcp-json <path>:除了在工作目录附近发现的外再读出一个MCP配置,所以网关可以从工作空间外跑出. 路径是文件本身, 文件名无需.mcp.json; 一个目录被理解为指.mcp.json内在的 当两个文件都定义同名服务器时,这里取名的服务器获胜. 无法被读取的路径是错误而不是静静地倒回目录.--auth-method <id>:代理请求登录时使用的认证方法. 默认自动选择 .--verbose:打印出一切——与代理RQ的连接,代理自己的日志,以及一发命令与代理交换的内容. 没有它, 网关只打印警告和错误; 代理日志被保存后, 只有在失败时才会显示 。 打印某物并退出的图标,比如--list-models打印出来.--help编号 :-h:解释每个选项,并举出例子. 同时显示acp-gateway被运行无所事事.--list-auth-methods:打印代理广告的登录方法,然后退出.--login [method-id]:登录到代理,然后退出.--logout:结束代理认证状态,然后退出(仅针对支持登录的代理).--acp-url <url>: 非加太集团的终点,用于无法从中找出的部署.mcp.json。 。 。 .--acp-version 1: 仍然接受这样现有的发射脚本继续工作,但它没有改变任何:ACP v1是唯一的协议. 任何其他版本都被拒绝.
示例
acp-gateway --max-concurrency 4 -- gemini --acp
acp-gateway --mcp-json ~/work/.mcp.json -- gemini --acp
从书记官处管理一名代理人
这个 非加太国家登记册 列出执行
协议,以及 acp-gateway 无法用手安装或连接:
acp-gateway --list-agents # see what's published
acp-gateway --agent gemini # run one
登记条目以三种方式分布,网关更倾向于按此顺序排列:
| 分发 | 怎么样 | 下载什么? |
|---|---|---|
npx | npx -y <package> <args> | 否- npm 获取并验证软件包 |
uvx | uvx <package> <args> | 否- uv 获取并验证软件包 |
binary | 归档已下载、检查、解开和缓存 | 对 |
由于npm和PyPI验证其服务内容,软件包的发售先出. 只使用二进制 当它是代理的唯一发行.
二进制在运行前进行验证. 登记处 sha256 因为归档是可选的,并且
大约一半公布的二进制目标省略. 在没有支票的地方, 网关拒绝
安装而不是运行无法保证的东西:
The ACP registry publishes no sha256 for "antigravity-acp" on this platform, so the download
cannot be verified. Re-run with --allow-unverified-agent to install it anyway, or install the
agent yourself and pass it after --.
因此下载报告本身:
[registry] Downloading antigravity-acp 1.0.4 from https://.../agy_acp_server.zip
[registry] antigravity-acp 1.0.4 [███████████░░░░░░░░░░░░░░░░░░░░░] 35% 229.6 MB/656.0 MB 25.5 MB/s
栏重绘一行,只显示在终端上;在主管下运行,输出 被管道到一个日志中,除了上面和下面的行外,下载会保持沉默.
每个代理、版本和平台下载都会被缓存,所以每个构建都会被获取一次:
| 平台 | 缓存位置 |
|---|---|
| macOS / Linux 系统 | $XDG_CACHE_HOME/acp-gateway/agents,则 ~/.cache/acp-gateway/agents |
| 窗口 | %LOCALAPPDATA%\acp-gateway\agents |
登记册公布的所有六个平台都得到了支持—— macOS、 Linux 和 Windows 都在 x86 64 上
还有Arm64 档案是用系统自己拆的 tar (和 unzip 用于 Linux 上的拉链,其
tar 无法读取),因此没有添加归档库作为依赖性.
认证
需要登录代理商在非加太公司握手期间为登录方法作广告,拒绝打开
语句直到使用一个. acp-gateway 处理像Zed这样的编辑器.
列出代理人提供的:
acp-gateway --list-auth-methods -- gemini --acp
提前登录——如果没有方法ID,请您选择:
acp-gateway --login -- gemini --acp
acp-gateway --login oauth-personal -- gemini --acp # or name the method directly
再次登录 :
acp-gateway --logout -- gemini --acp
不需要在前面做,但是: 如果代理商拒绝第一个会话,因为它需要登录,
acp-gateway 登录和重试本身.
方法有两种:
- 探员 方法 ——代理运行登录本身(一个浏览器流,一个它已经持有的API密钥). 这些 不需要任何人在场,所以他们首先被选中,在无人看管的网关工作.
- 终端 方法 —— 代理的自有二进制重新交互运行, 这样您可以在 TUI 登录 .
acp-gateway只有当它有一个真正的终端 交接时 才会提出运行这些.
一些代理方法通过浏览器签名并将其发回代理运行的服务器 127.0.0.1
(反重力的谷歌登录有). 如果你在另一台计算机上打开链接,它的最后一页将不会加载,
因为 127.0.0.1 那是你自己的电脑 何时 acp-gateway 在终端里运行, 它注意到这种
链接并询问浏览器的地址。 把它粘上 网关就把它寄给经纪人
拥有完成登录的机器.
身份证明从不由网关存储;代理保存着自己的身份证明,完全如它在一个编辑器下所做的那样.
配置
acp-gateway 搜索 .mcp.json 开始于当前工作目录并最多3个父目录.
网关连接 AgentRQ 服务器 /api/acp/v1 结束点,使用其 url (和 ?token=)或(或) Authorization: Bearer 页眉——不是MCP服务器本身. 文件的每个服务器,AgentRQ 1包含的服务器,也在其打开的每个会话中被交给代理,因此可以把它们作为MCP工具.
--list-models, (中文(简体) ), --agent-info, (中文(简体) ), --list-auth-methods, (中文(简体) ), --login 财务报告和审定财务报表 --logout 只处理代理本身,所以他们从未读过工作空间配置. --list-models 在一个空的临时目录中运行代理,所以代理不拾取工作空间的 .mcp.json 被带去工作室的经纪人那里.
--mcp-json <path> 直接命名一个配置, 它住在哪里和它叫什么。 读了 以及 无论搜索发现什么,随着被命名的文件赢得任何名称相撞——所以一个网关从其工作空间以外的地方开始,仍然连接到正确的一个.
示例 .mcp.json数字 :
{
"mcpServers": {
"agentrq": {
"type": "http",
"url": "https://<workspace>.mcp.agentrq.com/?token=<token>"
}
}
}
acp-gateway 喜欢服务器 agentrq 在名称中; 返回到第一个 HTTP 服务器 url。 。 。 .
如何运作
┌─────────────┐ ACP v1 (stdio) ┌─────────────┐ ACP v1 (WebSocket) ┌─────────────────────┐
│ ACP Agent │ ◄────────────────► │ acp-gateway │ ◄────────────────────► │ AgentRQ /api/acp/v1 │
└─────────────┘ └─────────────┘ └─────────────────────┘
AgentRQ是ACP客户端,"网关"不翻译. 它开始代理( 注册代号或命令)
之后 --)并移动行:代理写的每行变为一行WebSocket文本框到AgentRQ,每行
框架 AgentRQ 发送成为代理 Stdin 上的一行. 它只读JSON-RPC的信封,用于工作
目录,并保持代理通过新连接(下方).
- 相通之处. 端点是 AgentRQ 服务器自有路径的源头
/api/acp/v1结束wss://用于https://服务器和ws://页:1http://。工作空间符号是 URL 的?token=或 条目Authorization: Bearer头曰.--acp-url直指终点. - 特工获得工作空间的MCP服务器. 每个服务器
.mcp.json(和任何以--mcp-json)交给代理人打开的每次会话——session/new, (中文(简体) ),session/load财务报告和审定财务报表session/resume—— 说 领先于AgentRQ提供的东西,因此Agent可以像在MCP桥下所做的那样把它们作为工具. A 类 运输代理人说它不能带走的 被忽略了,一个说它什么也没有通过。 代理RQ提供 服务器,其名称与在.mcp.json,则.mcp.json一个被使用. - 代理在此目录中工作. 会话总是在网关自己的工作目录中打开:任意
目录代理RQ 名称
session/new, (中文(简体) ),session/load或者说session/resume替换为它。 告诉了RQ探员 在目录中X-AgentRQ-Cwd标题,%编码(UTF-8),如果它不是普通的ASCII,因为 头部不能携带其它东西 . - 连接前 它发出平地
GET因此,一个问题被命名为而非永远重审: 一个没有端点的旧服务器(404),一个坏信使(401/403),或者一个代理服务器的原因,或者代理服务器 未通过Upgrade页:1/api/acp/。每个出口 1. - 选项作为信头旅行 .
--agent, (中文(简体) ),--model, (中文(简体) ),--effort, (中文(简体) ),--max-concurrency, (中文(简体) ),--permission-timeout财务报告和审定财务报表--auth-method到达 WebSocket 握手中的 AgentRQ, 以及每个会话的工作目录. AgentRQ应用了它们,在运行时可以改变货币限制和模型. - 中断连接恢复 . 网关与后退连接(1s翻倍到60s),只要它 需要,AgentRQ 保持连接两分钟。 在此期间,没有任何东西丢失或重复:每一方 重放对方不承认的,多达1 024个帧或8个米B.
- 更长时间的停电 保持代理. 服务器重启后, 部署或关闭过这两分钟后, AgentRQ
开始一个新的连接,而同一代理程序为它服务:
initialize由代理人回答 第一次握手,运行的转弯被取消,代理商未答复的请求被回答为 放弃了 每项任务的对话继续进行:一项任务的及时性(由[Task <id>]标题 AgentRQ 开始于 ) 前往任务已经拥有的会话, 无论新连接给它什么 id . 特工身份由AgentRQ确认X-AgentRQ-Agent-Instance保持不变,只要它运行. - 一个已死亡的代理正在重新启动 2 s后,加倍为一分. 五分钟内5出入口 放弃并退出 1 与代理的最后一个输出.
- 登录代理RQ无法运行 (一个终端登录)在这里运行,当网关有一个终端——一个外壳,或者 agentrqd的浏览器终端:代理被停止,登录,重新开始,网关重新连接. 无 一个终端,或者当代理在登录后再次直接询问时,它会随代理RQ的指示而停止.
- 重试无法修正的错误 (一个说出不同非加太语版本的代理商) 被打印出 1号出口.
--login, (中文(简体) ),--logout, (中文(简体) ),--list-models, (中文(简体) ),--list-auth-methods财务报告和审定财务报表--agent-info与本地代理商交谈 退出; 他们从不连接 AgentRQ.
关键部件
| 文件 | 说明 |
|---|---|
src/index.ts | 入站点:选项,一发命令,并启动桥. |
src/native.ts | 运行代理和管道其stdio到AgentRQ的"WebSocket",并有恢复,再连接和再生. |
src/nativeFrames.ts | 桥的纯部分:分行,控制框,回放环,端点和头. |
src/localClient.ts | ACP客户端使用一发命令;对终端上的人设置登录URL. |
src/config.ts | 参数 .mcp.json 从当前目录树起, 深至3 个级别, 加上任何以 --mcp-json。 。 。 . |
src/auth.ts | ACP认证 — 列出代理登录方法, 检测 auth_required,并运行代理或终端登录. |
src/registry.ts | 阅读 ACP 注册索引——代理查询,主机平台匹配,以及包出发命令. |
src/agentInstall.ts | 下载,验证,解包和缓存注册代理二进制发行. |
src/progress.ts | 绘制单行下载进度栏,在终端和其他地方. |
发展
脚本
# Run in development mode
npm run dev
# Type-check
npm run typecheck
# Run tests
npm test
结构说明
- 书记官处工作人员数字 :
--agent <id>通过注册索引解决; 软件包分发比二进制优先, 和一个未公布的二进制sha256除非明确允许,否则将被拒绝. - 认证: 登录方法来自
initialize握手; 一个auth_required拒绝触发登录和一次重试newSession。 。 。 .
捐款
欢迎捐款! 请随意提交拉力请求或未决问题.
- 叉子存储器
- 创建您的特性分支( E)
git checkout -b feature/amazing-feature(中文(简体) ) - 提交更改( E)
git commit -m 'Add: amazing feature'(中文(简体) ) - 推向分行(
git push origin feature/amazing-feature(中文(简体) ) - 打开拉请求
捐赠许可证
通过为这个项目捐款,你同意你的捐款将获得项目Apache许可证2.0的许可.
许可证
Apache 许可证 2.0
版权 (c) 2026 Contexual, Inc.
特此准许任何人免费获得本软件和相关文件文件("软件")的副本,不受限制地在软件中进行交易,包括不受限制地享有软件的使用、复制、修改、合并、出版、分发、分版和(或)销售的权利,并允许软件获得者这样做,但须符合下列条件: 1
上述版权通知和许可通知应载入软件的所有副本或大部分.
软件是提供的"AS IS", 没有任何种类的恐惧, 释放或被卷入, 包括但不限制在 危机的保障, 证明一个特定的目的和无关。 任何索赔、索赔或其他负债,无论是合同、交易或其他行为,产生于、产生于或涉及软件或软件的使用或其他交易的行为,都不得作为担保.