> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 代理

> 主动连接 Cyberun 网关、为你团队执行任务的代理。

**Cyberun 代理**是你在一台有 GPU 的机器上运行的进程。代理维持一条到 Cyberun 网关的出站连接，用代理凭证（`ak-...`）表明身份，然后等待派发任务。你的机器永远不接受入站连接。

硬件由你提供，Cloud 负责调度。

## 代理如何连接

代理向外拨号连接 Cyberun 并保持连接开启。你的机器永远不接受入站连接——你不需要开端口或改防火墙。只要 GPU 机器有正常的出站互联网访问，它就能加入团队。

## 状态

在侧边栏的 **Agents** 页面，每个代理会显示以下状态之一：

| 状态            | 含义                                     |
| ------------- | -------------------------------------- |
| **idle**      | 已连接，无任务运行。可被派发。                        |
| **busy**      | 正在运行任务。其它任务在其后排队。                      |
| **syncing**   | 首次运行时拉取模型或节点包；尚未就绪。                    |
| **tunnel**    | 已为交互式使用打开一个 ComfyUI Web 隧道。隧道关闭前不接受任务。 |
| **unhealthy** | 已连接，但其 ComfyUI 健康检查失败 —— 在恢复前不会接收任务。   |

如果代理完全从列表中消失，说明它到网关的连接已断开。请检查代理的系统服务在 GPU 机器上是否仍在运行（安装程序会以类似 `cyberun-agent-comfyui` 这样的名称注册它）。各操作系统下的验证命令见[连接代理](/zh/cloud/guides/connect-agent)。

## 标签

工作流通过标签来挑选合适的代理。常见的默认标签：

* `gpu` ——该代理拥有可用的 GPU。
* `comfyui` ——该代理运行 ComfyUI 运行时。
* `nerfstudio` ——该代理运行 Nerfstudio 运行时。

大多数标签是自动设置的。安装程序会根据你选择的 `--tool` 和检测到的硬件推导出标签；代理在连接时主动声明它们。你可以在代理的本地配置文件中追加额外标签（在 `cyberun-agent.yaml` 的 `agent_labels:` 下）——用来给特定机器打上优先派发的标签，例如 `team-a`、`gpu-h100`。

工作流声明它所要求的标签。任务只会派发到那些标签集合是工作流要求**超集**的代理上。一个要求 `gpu, comfyui` 的工作流可以在任何同时声明这两个标签的代理上运行。

标签区分大小写。不要把同一种能力用两种名称（`comfyui` 与 `comfy`）发布——团队内统一只用一个。

## 健康状况与资源上报

控制台在 **Agents** 页面展示每个代理的遥测信息：

* GPU 型号和显存使用情况
* 运行时版本（例如 ComfyUI commit、Nerfstudio 版本）
* 最近一次心跳时间戳
* 当前任务 ID

通过集成密钥（`sk-`）而不是登录会话来获取该资源时，部分主机级统计会以精简形式呈现——这是有意为之，使得密钥泄露所暴露的团队硬件信息比登录会话更少。如果你需要完整的遥测信息，请通过控制台登录。

## 远程代理工具

部分部署会在代理详情页启用一套远程访问工具，包含三个子标签页：

* **Terminal** ——进入代理主机的交互式 shell。
* **Files** ——浏览、上传、下载、重命名、复制、删除、创建目录。
* **Desktop** ——查看代理屏幕，并发送鼠标、滚轮和键盘输入。

这些标签页使用短期有效的隧道凭证，并以团队为作用域。请把它们当成 SSH 来对待——只有 admin 应该使用，且只在你信任的代理上使用。如果你没看到这些标签页，说明本部署未包含远程访问。如果你需要它，请联系团队管理员。

## 相关

* [连接代理](/zh/cloud/guides/connect-agent) ——安装演练。
* [凭证](/zh/cloud/concepts/credentials) —— `ak-` 密钥族。
* [工作流](/zh/cloud/concepts/workflows) ——标签如何门控派发。