---
order: 10
---

# 连接你的第一台机器

本页解释如何把一台机器接入 AgentTeam，并让它成为可运行智能体的执行节点。

## 什么是机器

在 AgentTeam 中，机器是智能体运行的位置。

一台机器连接到工作区之后，AgentTeam 才能：

- 看到这台机器是否在线
- 在这台机器上启动或唤醒智能体
- 让智能体使用本地运行环境和本地工作区文件

## 开始前准备

你需要具备以下条件：

- 你对目标工作区拥有管理权限
- 你已经在 AgentTeam Web 中打开了目标工作区
- 你准备好了要接入的机器
- 这台机器上已经安装好 AgentTeam 客户端，或者由你的团队提供了可执行的 `agentteam` 程序

## 第 1 步：在 AgentTeam 中创建机器

在工作区中打开机器相关入口，点击“添加机器”。

完成这一步后，AgentTeam 会为这台机器生成一条连接命令。你通常不需要手工拼接参数。

## 第 2 步：复制连接命令

默认连接命令类似下面这样：

```bash
agentteam daemon --server-url <url> --api-key <machineApiKey>
```

这条命令会做两件事：

- 保存这台机器连接 AgentTeam 所需的本地配置
- 如果本地 daemon 尚未运行，就顺带启动它

## 第 3 步：在目标机器上运行命令

在你要接入的机器上执行这条命令。

如果命令执行成功，你会看到一条表示机器连接配置已保存的确认信息。随后，AgentTeam 会尝试把这台机器标记为在线。

## 第 4 步：回到工作区确认状态

回到 AgentTeam Web，打开机器页面，确认：

- 机器已显示为在线
- 系统识别到了主机名和操作系统信息
- 如果本地安装了受支持的运行环境，页面会显示可检测到的运行环境

只要机器在线，你就可以继续在这台机器上创建智能体。

## 让连接长期保持在线

如果你希望这台机器在日常使用中持续可用，建议把本地 daemon 作为长期进程运行。

常见方式包括：

- 直接使用 `agentteam daemon` 在前台运行
- 使用 `agentteam service install` 把它安装成系统服务；在 Linux 上也可以用 `agentteam service install --user` 安装成当前用户级别的 systemd 服务

Linux 上，`agentteam service install` 负责注册并启用 systemd 服务；如果希望现在就启动它，还需要执行 `agentteam service start`。之后可以用 `agentteam status` 查看服务是否已经 active、failed 或 inactive。

连接命令和 service 命令应尽量使用同一个系统用户执行。如果你切到 root shell 安装 service，后台服务会使用 root 的 AgentTeam 配置；如果连接配置保存在另一个用户下，应从那个用户执行 `sudo agentteam service install`。

在 Linux 上，`agentteam service install --user` 跟随当前用户的 systemd manager。若你希望机器重启后在该用户登录前也恢复在线，需要启用 lingering。

前台启动示例：

```bash
agentteam daemon
```

## 重连与换机

### 重新连接同一台机器

如果只是 daemon 退出、机器重启或网络恢复，通常重新运行原来的连接命令即可。

### 轮换 machine key

如果你怀疑 machine API key 泄露，应该在 AgentTeam Web 中为这台机器执行 Rotate key，然后使用新的连接命令重新接入。

旧 key 在轮换后不应再继续使用。

## 常见问题

### 页面一直显示离线

优先检查：

- 连接命令是否在正确的机器上执行
- `server-url` 是否可达
- machine API key 是否仍然有效
- 本地 daemon 是否仍在运行

### 已经接通过，但重启后又离线

这通常说明 daemon 没有作为长期进程运行。请考虑使用前台常驻方式，或安装为系统服务。

### 普通 `agentteam daemon` 和 `agentteam daemon --server-url ... --api-key ...` 有什么区别

- `agentteam daemon --server-url ... --api-key ...` 用于首次连接或重新连接 machine
- 普通 `agentteam daemon` 使用本地已保存的连接配置启动 daemon