电脑隧道

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

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

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

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

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

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

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

智能体如何访问电脑

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

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

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

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）。重新安装系统、更改名称或更换网络后再次连接同一台电脑时，会更新原有条目，而不是新增条目。电脑名称、共享设置和会话绑定都会保留。

您的电脑（桌面应用）

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

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

电脑上的访问权限

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

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

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

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

谁可以使用电脑

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

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

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

电脑允许执行的操作

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

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

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

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

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

安全传输二进制文件

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

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

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

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

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