# @agentrq/acp-gateway 中文文档

规范地址：https://npmcn.com/package/%40agentrq/acp-gateway/

版本：0\.4\.1
npm 元数据更新时间：2026-10-22T01:17:00.974Z
中文译文更新时间：2026-11-06T22:31:48.107Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentrq/acp-gateway
原文对照：https://npmcn.com/package/%40agentrq/acp-gateway/?lang=original
项目主页：https://github.com/agentrq/acp-gateway#readme
源码仓库：https://github.com/agentrq/acp-gateway

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：821 kB，63 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-04-18T19:48:57.847Z
- 最新版本发布：2026-10-22T01:17:00.566Z
- 近 30 天下载量：2249（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

ACP v1 用于代理工作空间的桥梁 CLI

## 安装

```sh
npm install @agentrq/acp-gateway
```

也可以使用：`pnpm add @agentrq/acp-gateway`、`yarn add @agentrq/acp-gateway`、`bun add @agentrq/acp-gateway`

## README

# @ agentrq/ acp-gateway (英语)

代理客户协议网关可以远程访问您在代理RQ中的代理.

## 概览

`@agentrq/acp-gateway` 连接一个 [代理客户协议( ACP)](https://agentclientprotocol.com/) 代理(如双子座,Codex)给代理工作空间. AgentRQ会说ACP v1本身;网关通过WebSocket运行你机器上的代理,并管道它的ACP流到AgentRQ.

它会:

1.  读取您的工作空间 `.mcp.json` 为 AgentRQ 服务器的 URL 和 符号.
2.  启动代理——你给出的命令,或来自非加太公司注册处的指令.
3.  把特工的血栓 输给RQ探员 `/api/acp/v1` 端点,为行所取行,而不用解析.
4.  恢复已丢弃连接并重新启动已死亡的代理 .

## 先决条件

-   **节点.js** 第22页
-   **无** 或者说 **线条**
-   一个 [非加太公司兼容代理人](https://agentclientprotocol.com/) (如双子座CLI)
-   一个 [代理](https://agentrq.com/?utm_source=github) 服务器提供 ACP v1 的工作空间( S) (`/api/acp/v1`(中文(简体) )

## 安装

```bash
cd acp-gateway
npm install
```

在全球范围内使用:

```bash
npm install -g @agentrq/acp-gateway
```

## 当前版本

`0.4.1`

## 使用量

### 快速启动

运行 `acp-gateway` 从您的代理工作空间根( 包含 `.mcp.json`:

```bash
# From workspace root
acp-gateway -- gemini --acp
```

或有自定义命令:

```bash
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是唯一的协议. 任何其他版本都被拒绝.

示例

```bash
acp-gateway --max-concurrency 4 -- gemini --acp
acp-gateway --mcp-json ~/work/.mcp.json -- gemini --acp
```

### 从书记官处管理一名代理人

这个 [非加太国家登记册](https://github.com/agentclientprotocol/registry) 列出执行 协议,以及 `acp-gateway` 无法用手安装或连接:

```bash
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这样的编辑器.

列出代理人提供的:

```bash
acp-gateway --list-auth-methods -- gemini --acp
```

提前登录——如果没有方法ID,请您选择:

```bash
acp-gateway --login -- gemini --acp
acp-gateway --login oauth-personal -- gemini --acp   # or name the method directly
```

再次登录 :

```bash
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`数字 :

```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://` 页:1 `http://`。工作空间符号是 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` | 绘制单行下载进度栏,在终端和其他地方. |

## 发展

### 脚本

```bash
# Run in development mode
npm run dev

# Type-check
npm run typecheck

# Run tests
npm test
```

### 结构说明

-   **书记官处工作人员**数字 : `--agent <id>` 通过注册索引解决; 软件包分发比二进制优先, 和一个未公布的二进制 `sha256` 除非明确允许,否则将被拒绝.
-   **认证**: 登录方法来自 `initialize` 握手; 一个 `auth_required` 拒绝触发登录和一次重试 `newSession`。 。 。 .

## 捐款

欢迎捐款! 请随意提交拉力请求或未决问题.

1.  叉子存储器
2.  创建您的特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add: amazing feature'`(中文(简体) )
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

## 捐赠许可证

通过为这个项目捐款,你同意你的捐款将获得项目Apache许可证2.0的许可.

* * *

## 许可证

Apache 许可证 2.0

版权 (c) 2026 Contexual, Inc.

特此准许任何人免费获得本软件和相关文件文件("软件")的副本,不受限制地在软件中进行交易,包括不受限制地享有软件的使用、复制、修改、合并、出版、分发、分版和(或)销售的权利,并允许软件获得者这样做,但须符合下列条件: 1

上述版权通知和许可通知应载入软件的所有副本或大部分.

软件是提供的"AS IS", 没有任何种类的恐惧, 释放或被卷入, 包括但不限制在 危机的保障, 证明一个特定的目的和无关。 任何索赔、索赔或其他负债,无论是合同、交易或其他行为,产生于、产生于或涉及软件或软件的使用或其他交易的行为,都不得作为担保.

## 常见问题

### @agentrq/acp-gateway 是什么？

ACP v1 用于代理工作空间的桥梁 CLI

### 如何安装 @agentrq/acp-gateway？

在项目目录运行 npm install @agentrq/acp-gateway，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 acp-gateway，可以用 npx acp-gateway 直接运行。

### @agentrq/acp-gateway 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agentrq\_\_acp-gateway 是否存在。

### @agentrq/acp-gateway 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentrq/acp-gateway 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentrq/acp-gateway 可以商用吗？

@agentrq/acp-gateway 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @agentrq/acp-gateway 的下载量有多少？

根据 npm 官方下载统计，@agentrq/acp-gateway 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,249 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentrq/acp-gateway 还在维护吗？

最新版本 0\.4\.1 发布于 2026/10/22（16 天前）；至今共发布 64 个版本，其中过去 12 个月发布了 64 个；首次发布于 2026/04/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。