# @kortix/agent-tunnel 中文文档

规范地址：https://npmcn.com/package/%40kortix/agent-tunnel/

版本：0\.14\.13
npm 元数据更新时间：2026-11-01T14:43:25.780Z
中文译文更新时间：2026-11-01T17:24:14.262Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：748 kB，76 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-03-05T16:17:38.643Z
- 最新版本发布：2026-11-01T14:43:25.463Z
- 已发布版本数：76（近 12 个月 76 个）

## 中文简介

云AI代理和本地机器之间的隧道中继-服务器中继，本地代理，客户端SDK， JSON-RPC， HMAC签名

## 安装

```sh
npm install @kortix/agent-tunnel
```

也可以使用：`pnpm add @kortix/agent-tunnel`、`yarn add @kortix/agent-tunnel`、`bun add @kortix/agent-tunnel`

## README

# `@kortix/agent-tunnel`

`@kortix/agent-tunnel` 将本地计算机通过认证反向隧道连接到Kortix。

每台连接的计算机都是一个项目的帐户 **电脑** 连接器, 对连接它的人来说是私有的，除非他们与项目共享。 Kortix桌面应用捆绑了这个代理，一键连接。没有 桌面应用程序，使用下面的命令。

## 连接一次

运行如下所示的命令 **连接你的电脑** 在一个项目中。然后 在浏览器中批准设备代码：

```bash
npx --yes @kortix/agent-tunnel@latest connect \
  --api-url https://api.kortix.com/v1/tunnel \
  --project-id <project-uuid>
```

电脑属于你的每一个项目和工作空间，你是其中的一员 在你的私人会议上。 `--project-id` 只提供“也与……分享” ，在审批页面上；没有它，电脑仍然是你的 无处不在。

再次连接同一台计算机重用其条目。代理发送SHA-256 硬件ID的哈希(IOPlatformUUID， `/etc/machine-id`，或者 `MachineGuid`); 原始ID永远不会离开电脑。

批准后, `connect` 在终端安装后台服务时， 和桌面应用程序一样，打印暂停、恢复、 然后去掉它。它不问任何问题。 `--foreground` 保持连接在 终端。没有TTY的脚本，或者 `--json`，留在前景 除非它通过 `--daemon`.

## 一个运行时与桌面应用程序（macOS）

当安装Kortix桌面应用程序时(`/Applications/Kortix.app` 或者 `~/Applications/Kortix.app`)，命令行安装写入的服务运行在 App自带代理和驱动： `Kortix.app/Contents/MacOS/Kortix` 与 `ELECTRON_RUN_AS_NODE=1` 和 `Contents/Resources/agent-tunnel/agent-cli.js`. CLI安装和app安装是同一个连接。macOS拨款 可访问性和屏幕记录Kortix一次，永远不会 `node` 或者一个 终端, **你的电脑** 在应用程序中控制它。

这个命令行是计算机的一个控制界面。桌面应用程序运行 这些相同的命令(`status --json`， `access`， `keep-awake`， `stop`， `start`， `logout`)，并且永远不会编辑代理的文件本身。做出改变 在应用程序中，在终端中，或者通过Kortix进行相同的更改。没有这个应用程序， 服务运行于 `node`，而电脑使用则需要单独安装 `cua-driver`.

当它的代码在磁盘上发生变化(应用程序更新或 新提供的包)。macOS拒绝对进程的所有许可 二进制被替换在它下面，所以一个陈旧的进程将失去计算机使用。

## 在后台运行

该服务是终端用户的默认服务。一个脚本安装它 `--daemon`：

```bash
npx --yes @kortix/agent-tunnel@latest connect \
  --daemon \
  --api-url https://api.kortix.com/v1/tunnel
```

该服务在macOS上使用LaunchAgent，在Linux上使用用户系统服务，在Windows上使用Task Scheduler。 它在登录时启动，并且在每次退出（启动）后，管理员重新启动它 `KeepAlive` 10秒油门，系统 `Restart=always`（5秒的Windows循环）。 在Linux上，install启用 `loginctl enable-linger` 所以用户服务保持不变 登出后运行，开机时启动；如果不允许，请安装 打印警告。Windows任务在PowerShell下运行 `conhost --headless` （没有控制台窗口，Windows终端也是默认终端），打开 电池，无时间限制。代理在Windows上启动的每个进程设置 `windowsHide`，因此不会打开控制台窗口。 代理本身永远不会自行停止：

-   它重新连接与指数后退从1秒到30秒，±20%抖动，永远。
-   它丢弃一个在75秒内没有收到中继ping的套接字，并在75秒内重新连接 一旦机器从睡眠中醒来（一个5秒的计时器，看到更多的跳跃） 而不是30岁)。一个尾流重置后退。
-   被拒绝的凭证将使其处于状态 `rejected`． 它检查 `config.json` 每5秒和连接一次，只要一个新的配对写入另一个凭证； 它还每5分钟重试一次旧的。
-   继电器每分钟接收5个连接。这个过程 重启速度比这个更快，等待下一个槽位的时间最长为12秒。
-   具有相同凭据的第二个进程将其置于状态 `standby`． 它 1分钟后再试一次，每次加倍，直到30分钟 一个证书的持有者不会来回交换连接。
-   握手不能到达 `auth_ok` 在20秒内被丢弃并重试。
-   没有保存凭据：它等待并检查 `config.json` 每60分钟一次。

它只会在一段时间内改变电脑的睡眠设置 `keep-awake` 正在进行中(见 “访问控制”)。

## 管理后台服务

```bash
npx --yes @kortix/agent-tunnel@latest service-status
npx --yes @kortix/agent-tunnel@latest logs
npx --yes @kortix/agent-tunnel@latest restart
npx --yes @kortix/agent-tunnel@latest stop     # pause: stays stopped after login and reboot
npx --yes @kortix/agent-tunnel@latest start    # resume
npx --yes @kortix/agent-tunnel@latest uninstall-service
npx --yes @kortix/agent-tunnel@latest logout   # remove this computer from Kortix, then sign out
```

`stop` 禁用作业(`launchctl disable`， `systemctl --user disable --now`， `schtasks /Change /DISABLE`)，所以它会一直停止，直到 `start`.

`logout` 第一次调用 `DELETE /v1/tunnel/self` 有了机器自己的证书， 删除机器和它在科提克斯的账户。然后清除本地 凭据并删除服务。如果联系不上科提克斯，当地的 签到仍然完成； `logout --json` 然后报告 `"serverUnpaired": false`.

`status --json` （及其别名） `service-status --json`)打印配对； 经批准的 `capabilities`，服务(`installed`， `active`， `enabled` ＝ 不停顿了一下, `upToDate` =单位匹配什么 `install-service` 写), 实时连接 `state` (一个进程没有说就死了，读作 `offline`), `access` （同一物体） `access --json` 打印)。

凭据存储在 `~/.agent-tunnel/config.json`． Agent隧道要求 要指定的文件为常规文件，由当前用户所有，以及模式 `0600` 在POSIX。 保护操作系统帐户，因为这个设置令牌可以进行身份验证 机器直到你旋转或删除连接。

远程API url必须使用HTTPS。纯HTTP仅用于 `localhost`， `127.0.0.1`, `::1` 发展的端点。

## 文件和隔离

| 路径（在config目录下） | 内容 |
| --- | --- |
| `config.json` | 凭据和本地限制，模式 `0600`. |
| `state.json` | `{ tunnelId, apiUrl, status: online|offline|connecting|rejected|standby, since, agentVersion, pid }`，在每次连接更改时自动重写。没有凭据。 |
| `access.json` | `{ mode: ask|always|off, grantedUntil, deniedUntil, keepAwake }`、模式 `0600`． 参见“访问控制”。 |
| `access-request.json` | `{ id, requestedAt, capability, method, change? }`：电话，或通过Kortix (`change`)，等待主人。 |
| `desktop-app.json` | 由Kortix桌面应用程序编写：如何启动它以显示访问提示。 |
| `logs/` | 服务输出。 |

`AGENT_TUNNEL_HOME` 替换配置目录(默认 `~/.agent-tunnel`）。 非默认目录也有自己的服务， `ai.kortix.agent-tunnel.<first 8 hex of sha256(directory)>`等一下 标识永远不会替换默认值 `ai.kortix.agent-tunnel` 服务。这个 服务定义携带 `AGENT_TUNNEL_HOME` 进入服务环境。

## 访问控制

在每次呼叫之前，机器会决定座席是否可以使用它。改变 使用CLI：

```bash
npx --yes @kortix/agent-tunnel@latest access                  # show it
npx --yes @kortix/agent-tunnel@latest access ask              # or always, off
npx --yes @kortix/agent-tunnel@latest access --allow-for 60   # in ask: allow for 60 minutes (max 1440)
npx --yes @kortix/agent-tunnel@latest access --revoke         # end the current allowance
npx --yes @kortix/agent-tunnel@latest access --deny           # answer the waiting request with No
npx --yes @kortix/agent-tunnel@latest keep-awake on           # or off (macOS and Linux)
```

每个命令都需要 `--json` 并打印 `{ mode, grantedUntil, deniedUntil, keepAwake, keepAwakeSupported, pendingRequest }`． 错误的模式或持续时间 出口 `1` 改变不了什么。站在终端的人是电脑的 所有者，所以这些命令也扩大了访问范围。

| `mode` | 效果 |
| --- | --- |
| `always` | 每个调用都运行。一台没有 `access.json` 就像这样。 |
| `ask` | 调用运行时 `grantedUntil` 是在未来（最多24小时）。否则代理会写 `access-request.json`，如果桌面应用程序未运行，则启动该应用程序，并保持通话20秒。一笔拨款管理着它。无应答 `-32010 computer_access_pending`． 一个拒绝集 `deniedUntil` 提前10分钟返程 `-32011 computer_access_denied`;在此之前，呼叫会立即失败。 |
| `off` | 每次调用都会返回 `-32012 computer_access_off`. |

**通过Kortix。** 所有者还可以从Kortix网络应用程序更改访问权限 或者桌面应用程序的窗口(`POST /v1/tunnel/connections/:id/access`、用户 凭证;没有代理或会话令牌到达它)。Kortix传递 将代理更改为 `tunnel.access.set`：

-   缩小的(`ask`， `off`， `--revoke`， `--deny`（保持清醒）立即适用， 即使访问是 `off`.
-   不断扩大的(`always`（或更长时间的津贴）需要主人在电脑上。 代理将其写入 `access-request.json` 与 `change`，以及桌面 应用程序显示本机 **允许** / **取消** 对话框。 **允许** 运行匹配 `access` 命令; **取消** 运行 `access --deny`，它拒绝了这种变化 没有拒绝电话。中继呼叫等待时间长达20秒，否则呼叫失败 与 `-32014 computer_access_unconfirmed`． 没有桌面的电脑 应用程序立即失败，命名要在其上运行的命令。

从Kortix桌面应用程序开始配对 `ask`：应用程序显示 提示。仅使用该CLI进行的配对从 `always`，因为没有 在机器上可以回答提示。这是故意偏离 “新配对默认为询问”。模式和保持清醒是所有者的 机器设置：重新配对(`--reauth`（被拒绝或过期的凭证） 保留它们，只有先前配对的同意或拒绝才会被丢弃。 `logout` 删除 `access.json`，因此下一次配对从默认值开始。代理人回家(`config.json`， `access.json`， `desktop-app.json`） 始终是一个阻塞的路径：没有文件或shell调用可以更改这些文件。

代理将其状态作为签名通知报告给Kortix `tunnel.access.state` 在连接和每个更改上：访问字段， 等待请求，以及 `desktopPermissions` （`{ accessibility, screenRecording }` 作为macOS应答代理进程本身，每60秒检查一次)。Kortix 这恰恰说明了这一点。

`keep-awake on` 使计算机在代理运行时不处于睡眠状态： `caffeinate -s` 在macOS上（仅限交流电源）， `systemd-inhibit --what=sleep` 在 Linux。不支持Windows。

## 机器可读的连接

`connect --json` 在标准输出上打印以换行分隔的JSON事件，而不是 终端用户界面。它从不提示，从不打开浏览器；来电者显示 批准的URL。

```json
{"event":"challenge","deviceCode":"ABCD-1234","verificationUrl":"https://…","expiresAt":"…"}
{"event":"approved","tunnelId":"…","capabilities":["filesystem","shell"]}
{"event":"service","action":"install","ok":true,"active":true,"detail":"…"}
{"event":"error","message":"…"}
```

`approved` 携带 `"existing": true` 当保存的配对仍然有效时。 `service` 只跟在后面 `--daemon`.

在电子(`ELECTRON_RUN_AS_NODE=1`)，则安装的服务将运行 与 `ELECTRON_RUN_AS_NODE=1` 然后把包放好。

## 允许界限

Kortix检查会话是否可以使用计算机帐户（所有者）， 共享和连接器策略，如 `require_approval`)，然后再传送 操作。配对时批准的功能是固定的；再次配对改变 他们。然后，本地代理再次检查操作。

本地配置为最大边界。服务器无法扩展配置 文件系统路径、阻塞路径、shell命令、超时、文件大小或桌面 特性。

一、 `shell` 授予本地代码执行。允许列表与可执行文件匹配 准确地命名，块列表也匹配以该名称结尾的每个路径 （`/bin/rm` 是 `rm`）. 参数不受限制：是允许的 `git`， `find`，或者 `python` 可以通过自己的标志运行任何代码。格兰特 `shell` 只针对一个会话 你信任这台电脑。

## 计算机使用驱动程序

Agent Tunnel从不下载或执行桌面驱动程序。Kortix桌面 应用程序包 `cua-driver` 在macOS和Windows （x64）上运行，它运行的代理使用 复制。CLI安装使用来自的现有二进制文件 `CUA_DRIVER_BIN`， `~/.local/bin`， `/usr/local/bin`，或者 `/opt/homebrew/bin`.

一个批准 `desktop` 当驱动程序存在时进行注册。失踪macOS 授予不会注销它：代理会报告 `desktopPermissions` 和 设置需要它们。当司机失踪或被拒绝（认错车主）时， group-writable), `desktop` 不注册和原因报告为 `unavailableCapabilities.desktop` 在 `status --json` 在 `machineInfo`. 将该二进制文件视为受信任的本地代码。代理隧道不验证或更新 它。

### 传输二进制文件而不复制base64

运行源文件所在的客户端。集 `TUNNEL_API_URL`， `TUNNEL_TOKEN`， 和 `TUNNEL_ID` 对于目标连接，然后运行：

```sh
agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}'
```

`fs_upload` 从 `source`，计算SHA-256，并发送字节 以编程方式通过经过身份验证的隧道。它需要文件系统写入 许可。待定审批返回 `success: false` 出口代码为1；重试 只有经过批准。该命令接受不超过3mib的常规文件 在base64编码后，在中继的5mib消息限制下的房间。

连接的代理检查所提供的 `sha256` 修改目的地址之前。 它在写入后读取文件并返回其持久化文件 `sha256` 和 `size`. 只有两个源都匹配，CLI才会成功。没有校验和的旧代理 支持导致验证失败；该文件可能已经存在。更新代理 之前进行重试。

为原料 `fs.write`， `sha256` 是可选的兼容性。为二进制提供它 内容。永远不要从模型上下文中复制不透明的base64有效负载。生成文件 当编程式传输不可用时，在目标上。匹配散列 验证字节完整性，而不是格式有效性：验证XLSX/ZIP结构和工作簿 来源的内容。文件大小和魔术字节不足。不要使用 此工作流的公共文件主机中继。

## 常见问题

### @kortix/agent-tunnel 是什么？

云AI代理和本地机器之间的隧道中继-服务器中继，本地代理，客户端SDK， JSON-RPC， HMAC签名

### 如何安装 @kortix/agent-tunnel？

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

### @kortix/agent-tunnel 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @kortix/agent-tunnel 支持 ESM 还是 CommonJS？

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

### @kortix/agent-tunnel 可以商用吗？

@kortix/agent-tunnel 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @kortix/agent-tunnel 还在维护吗？

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