# 电脑隧道

通过需授权的 Beeuni Agent Tunnel 连接你的设备。

Canonical page: https://beeuni.ai/docs/zh/connect/computers

电脑是您自己的机器——笔记本电脑、台式机或服务器——通过受权限控制的反向隧道连接到 Beeuni。电脑不是沙盒。沙盒是 Beeuni 为某个[会话](/docs/zh/work/sessions)创建的一次性云端机器。电脑是您已经拥有的机器，会在多个会话期间保持连接。

已连接的电脑是 `computer`[连接器](/docs/zh/connect/connectors)的一个**账户**，就像个人 Gmail 邮箱是 Gmail 连接器的一个账户一样。每个项目都内置 `computer`连接器；您无需添加或移除它。每位成员连接自己的电脑，而且电脑会**跟随他们**：在其所属的每个工作区中的每个项目里，电脑都是一个账户，无需为每个项目单独设置。

1. 从项目的连接器目录中添加 **Computer Tunnel**。
2. 运行个人资料中显示的配对命令，例如 `npx --yes @beeuni/agent-tunnel@latest connect --api-url <url>`。
3. 在浏览器中批准连接。
4. 为个人资料选择已配对的机器。

连接电脑后，项目侧边栏会显示一张 **连接您的电脑** 卡片。若不需要，可点击 **×** 将其关闭；它会在该浏览器中保持隐藏。关闭电脑功能的部署中不会显示此卡片。

您可以按功能授予访问权限：文件系统、Shell 或桌面。每项功能都可以限定允许访问的路径、命令或桌面功能。功能授权是针对一台机器上某项资源的设置，不是 Beeuni 角色。它不会授予角色判定结果所拒绝的权限——请参阅[账户与访问权限](/docs/zh/accounts#per-feature-access-settings)。智能体只能使用您授予的权限。调用未获授权的功能会创建权限请求。打开 Computer Tunnel 个人资料中的机器，即可批准或拒绝请求。

**在浏览器中操作。** 点击卡片上的 **连接您的电脑**。对话框会提供 **下载 Beeuni 桌面版**，安装后即可一键连接电脑。若不使用应用，请选择 **改用 CLI**，并在电脑上运行显示的命令：

<a id="how-the-agent-reaches-a-computer"></a>

## 智能体如何访问电脑

配对会将机器添加到您的账户设备列表中。它不会写入任何分配信息，因此不会授予项目访问权限。
从项目的[连接器](/docs/zh/connect/connectors)目录中添加 **Computer Tunnel**，然后为该个人资料选择一台或多台已配对的机器。

一个个人资料可以包含一台机器，也可以包含一组机器。机器组不是账户组——账户组是角色模型中的主体，而这里的是机器。您可以创建多个个人资料，并为其设置不同或部分重叠的机器组。每个个人资料都有独立的智能体授权和工具策略。

`list_computers`工具只会返回分配给当前个人资料的机器。其他工具可以接受该结果中的可选 `computer`名称或 ID。如果恰好只有一台已分配的机器处于在线状态，则无需使用选择器。

```bash
beeuni connectors call studio-computers.list_computers '{}'

beeuni connectors call studio-computers.fs.read \
  '{"computer":"MacBook-Pro-9.local","path":"/etc/hosts"}'
```

该命令会打印验证码并打开批准页面。在批准页面上：

1. 确认验证码与电脑上显示的验证码一致。
2. 为电脑命名。该名称将成为账户标签。
3. 选择 **谁可以使用这台电脑**：**仅您**（默认设置：您的所有项目和私人会话），或 **同时共享给**命令中指定的项目。共享需要管理该项目连接的权限。
4. 选择智能体可以执行的操作：**文件系统**、**Shell**、**电脑控制**。

之后，您可以在所属的每个项目中通过 **自定义 → 连接器 → 电脑 → 账户**找到这台电脑。它的行显示方式和操作方式与其他连接器账户相同；当前未连接的电脑会在名称下方显示 **离线**。

Beeuni 通过硬件 ID 的哈希值识别每台电脑（macOS 上的 IOPlatformUUID、Linux 上的 `/etc/machine-id`、Windows 上的 `MachineGuid`）。重新安装系统、更改名称或更换网络后再次连接同一台电脑时，会更新原有条目，而不是新增条目。电脑名称、共享设置和会话绑定都会保留。

<a id="your-computer-desktop-app"></a>

## 您的电脑（桌面应用）

打开工作区菜单（侧边栏顶部的项目名称），然后选择 **您的电脑**。旁边的圆点表示电脑状态。对话框会显示电脑名称及以下状态之一：**在线**、**正在连接**、**离线**、**已暂停**或**需要重新连接**（电脑已在其他位置断开连接；**连接这台电脑**会重新配对）。您可以在此执行以下操作：

- **暂停连接** / **恢复连接**：停止或重新启动后台服务。暂停的电脑对智能体而言处于离线状态（`computer_offline`），并且重启后仍保持暂停。
- **访问权限**：电脑连接时智能体是否可以使用它。请参阅[电脑上的访问权限](#access-on-the-computer)。
- **接通电源时保持电脑唤醒**（macOS 和 Linux）：电脑接通电源时不会进入睡眠状态，以便智能体访问。默认关闭。Windows 上会显示该选项暂不可用。
- **共享**：打开电脑连接器的「账户」标签页，然后点击电脑所在行的 **共享**。
- **显示日志**：打开智能体的日志文件。
- **断开连接**：从 Beeuni 和所有项目中移除电脑，并停止后台服务。

<a id="access-on-the-computer"></a>

## 电脑上的访问权限

无论项目允许什么，电脑本身都会决定智能体是否可以使用它。您可以在 **您的电脑 → 访问权限**中设置，也可以通过菜单栏图标设置：

- **每次询问**（通过桌面应用连接的电脑的默认设置）：智能体首次调用时，电脑上会显示提示：**允许 24 小时**、**允许 1 小时**（默认按钮）或 **拒绝**。批准后，所有可访问该电脑的智能体在批准有效期间都可访问文件、Shell、屏幕和键盘。批准生效期间，对话框会显示 **允许至 14:32**和 **立即撤销**。点击 **拒绝**后，调用会立即失败，10 分钟内不会再次提示。更改模式会结束当前的批准或拒绝状态。
- **始终允许**：不显示提示。仅通过 CLI 连接的电脑默认采用此设置，因为这类电脑无法显示提示。此设置推出前连接的电脑也会采用此设置，直到您更改为止。
- **关闭**：拒绝所有调用。

只有您本人可以在电脑上扩大访问权限。当 Beeuni 页面请求设置为 **始终允许**或发起新的批准时，桌面应用会先显示系统原生对话框，只有点击 **允许**后才会应用更改。每次新配对都会重新采用默认设置，点击 **断开连接**则会移除该设置。

此设置保存在电脑上（`~/.agent-tunnel/access.json`）。账户行和 `status`工具都会报告该设置，因此智能体可以告知您它正在等待批准。

<a id="who-can-use-a-computer"></a>

## 谁可以使用电脑

电脑遵循与其他连接器账户相同的规则：

- **私人**电脑（默认设置为 **仅您**）只会在所有者自己的私人会话中运行，并适用于所有者所属的每个项目。其他成员看不到也无法使用它。
- 点击电脑所在行的 **共享**，会打开与 Gmail 账户相同的对话框：选择用户、群组或项目中的所有人。点击 **保存**后更改才会生效；除非您将自己移除，否则您仍保留访问权限。共享需要管理该项目连接的权限。电脑在该项目中仍是一个账户；共享后，该行会显示哪些人可以使用它。
- 与项目中的所有人共享的电脑会为所有人运行，包括无人值守的运行：触发器、计划任务，以及没有关联用户的 Slack 消息。无人值守的运行只能访问共享电脑。
- 您自己的账户行会跟随您，因此不会只从某个项目中移除。点击该行上的 **断开连接**会将电脑从 Beeuni 和所有项目中移除。如需保持连接但不使用，请在电脑上将访问权限设为 **关闭**。

如需让高风险调用必须经过人工审核，请在电脑连接器的 **工具**标签页中设置[连接器策略](/docs/zh/connect/connectors)（例如，对 `shell.exec`选择 **询问**）。请求随后会出现在项目的审批中。

<a id="what-the-computer-allows"></a>

## 电脑允许执行的操作

在批准电脑时，您只需选择一次要启用的功能。若要稍后启用某项功能，请重新连接电脑并选择该功能。

无论 Beeuni 允许什么，本地智能体配置都是所有调用不可逾越的上限。它位于电脑上的 `~/.agent-tunnel/config.json`：

| 字段 | 默认值 | 效果 |
|---|---|---|
| `enabledCapabilities` | 您批准的功能 | 机器实际接受的功能。 |
| `allowedPaths` | 您的主目录 | 文件系统调用可以访问的路径。 |
| `blockedPaths` | `/etc/shadow`、`/etc/ssh`、`/proc`、… | 所有调用都禁止访问的路径。 |
| `allowedCommands` | 空（允许任何命令） | 设置后，`shell.exec`只能运行指定的可执行文件。 |
| `blockedCommands` | 空 | `shell.exec`永远不会运行的可执行文件。 |

不受限制的 Shell 可以运行当前用户可用的任何可执行文件。请将 `allowedPaths`和 `allowedCommands`限制在工作所需的范围内。

使用电脑控制功能需要单独安装本地 `cua-driver`。智能体不会下载、安装或更新该可执行文件。

请在控制面板中配置 Computer Tunnel 个人资料，而不是通过 `beeuni.yaml`配置。使用个人资料的「账户」标签页来配对、选择、检查、重命名和移除机器；使用「工具」标签页配置连接器策略。

<a id="deliver-binary-files-safely"></a>

## 安全传输二进制文件

对于电子表格、PDF、图片和其他二进制文件，请直接从源文件传输字节。切勿要求智能体从工具输出中复制 Base64 内容。这可能会在文件大小不变的情况下更改文件字节。

在保存源文件的机器或沙盒上配置 `TUNNEL_API_URL`、`TUNNEL_TOKEN`和 `TUNNEL_ID`，然后运行：

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

该命令支持最大 3 MiB 的文件，并且需要文件系统功能。它会从源文件计算 SHA-256，并检查目标端返回的哈希值。如果连接的智能体响应中没有 `sha256`字段，请更新该智能体。

对于较大的文件，请在目标端生成文件。交付前请验证源文件格式。哈希值匹配可以证明字节传输后未发生更改；文件大小和扩展名无法证明 Excel 能够打开工作簿。