> ## 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.

# 连接代理

> 在 GPU 机器上安装 Cyberun 代理，让团队可以向其分派任务。

**Cyberun 代理** 是将你的 GPU 机器连接到平台的进程。本页是安装与连接的操作指引。
关于概念模型见 [代理](/zh/cloud/concepts/agents)。

## 开始之前

* 一个你所属的团队。任何成员都可以创建代理密钥。
* 一台带有可用 GPU 的机器，操作系统为 Linux、macOS 或 Windows。代理三个平台都能跑；每个运行时各自决定其平台与硬件支持 —— 参见 [Platform → 代理](/zh/platform/agents)。
* 从 GPU 机器到 Cyberun 的出站网络访问。无需开放任何入站端口。

## 1. 创建代理凭证

1. 在 Cloud 中，打开侧边栏的 **访问**。
2. 切换到 **代理** 标签页。
3. 点击 **创建代理密钥**。
4. 用机器名命名（`home-rtx-4090`、`studio-mac-mini`、
   `cloud-h100-a`）。
5. 点击 **创建**。
6. **复制显示的 `ak-…` 值。** 它只显示一次。

## 2. 安装代理

代理附带逐平台的安装器，负责下载、ComfyUI 设置以及服务注册。
针对你的操作系统运行以下一行命令：

**Linux 与 macOS：**

```sh theme={null}
curl -sL https://releases.cyberun.cloud/agent/install.sh | bash -s -- \
    --api-key ak-…
```

**Windows（PowerShell）：**

```powershell theme={null}
& ([scriptblock]::Create((irm https://releases.cyberun.cloud/agent/install.ps1))) -ApiKey ak-…
```

<Note>
  代理可在每个受支持的操作系统上运行；每个运行时各自决定其要求。
  逐运行时的支持详情见 [Platform → 代理](/zh/platform/agents)。
</Note>

这会在 Python 虚拟环境中设置 ComfyUI，将代理注册为每用户服务并启动它 —— 无需 `sudo`,comfyui 为默认工具。代理会连接到
Cyberun，并在几秒内出现在 Cloud 的 **代理** 中，状态为
**idle**。

完整的安装器参数列表（Docker 模式、指定 GPU 索引、自定义镜像，…）见
[Platform → Agents](/zh/platform/agents)。

## 3. 验证

提交一个针对该代理标签的小任务。请参见
[运行你的第一个任务](/zh/cloud/getting-started/first-task) 的操作指引。

## 故障排查

**`401 unauthorized`** —— 代理密钥错误、已撤销或已过期。
在 Cloud 中检查 **访问 → 代理** 并重新签发。

**`connection refused`** —— 你的网络无法到达网关。
用 `curl -v https://gateway.cyberun.cloud/ws` 测试：可达的
网关会返回 `401 Unauthorized`，并带有类似
`{"error_message":"missing api key"}` 的 JSON 主体 —— 这表明主机在线且
网关已响应，只是 `curl` 没有通过身份验证。
超时、DNS 错误或 TLS 失败则意味着主机不可达 ——
最常见是 GPU 机器所在网络上的防火墙阻断了出站 WSS。

**代理一直停在 `syncing`** —— 代理在首次运行时正在下载
模型或节点包。查看代理的本地日志（在 Linux 上为
`journalctl --user -u cyberun-agent-comfyui`）；通常是网络带宽问题。
后续的连接会跳过已缓存的工件。

**任务排队但从未派发** —— 工作流要求的标签与代理的标签不匹配。
在工作流详情页和 **代理** 中代理所在的那一行进行比较。

## 相关

* [代理](/zh/cloud/concepts/agents) —— 概念与生命周期。
* [凭证](/zh/cloud/concepts/credentials) —— 代理密钥
  系列。
* [Platform → Agents](/zh/platform/agents) —— 面向运维人员的安装参考
  （系统服务、日志位置、全部参数）。
* [Cyberun CLI](/zh/cloud/guides/cli) —— `cyberun agent serve` 运行一个
  绑定到你登录会话的轻量级前台代理；而本页的独立安装器会注册一个
  长期运行的系统服务。