# 下载安装

本页介绍如何下载、安装并启动设备智能体。完成安装后，你可以打开控制台，开始创建设备智能体并接入 MQTT 设备。

## 安装位置

设备智能体支持 macOS、Linux 和 Windows，可以安装到开发电脑、边缘网关、Linux 工控机或私有服务器。
安装环境需要能够访问 MQTT 服务和模型服务，并开放控制台端口，默认端口为 `3000`。

- 本地体验：安装在开发电脑上，通过 `http://127.0.0.1:3000` 访问控制台。
- 现场运行：安装在边缘网关、Linux 工控机或私有服务器上，让它靠近设备网络运行，并通过服务器 IP 访问控制台。

## 建议硬件配置

| 配置 | CPU | 内存 | 磁盘 | 适用场景 |
| --- | --- | --- | --- | --- |
| 最小配置 | 2 核 | 512 MB | 300 MB 可用空间 | 本地体验、Demo 和小型板端部署 |
| 推荐配置 | 2-4+ 核 | 1 GB+ | 1 GB 可用空间 | 长期稳定现场运行 |

## 准备

设备智能体需要连接已有的 MQTT 服务和模型服务。安装前请确认：

- MQTT 服务地址和认证信息
- 模型服务商、模型名称和 API 密钥
- 浏览器可以访问设备智能体控制台端口，默认为 `3000`

如果还没有 MQTT 服务，最快方式是让 Agent 创建 **Zero EMQX MQTT Broker**。它会创建一个临时
Zero EMQX 测试 Broker，并把 MQTTS/WSS 地址和认证信息写入当前配置。该 Broker 实例由
[EMQX Cloud](https://www.emqx.com/zh/cloud) 提供。可以直接对 Agent 说：

```text
帮我创建一个 Zero EMQX MQTT Broker 测试实例，并把 MQTT 设置写入当前配置。
```

Agent 创建完成后，在 **Settings > MQTT** 中保存配置即可应用。也可以在 MQTT 设置页点击
**Create test broker**，或用命令行创建：

```bash
curl -sS -X POST https://zero.emqx.io/v1/instances
```

返回结果里包含 `mqtts.uri`、`wss.uri`、`credentials.username` 和 `credentials.password`。完整
`.env` 导出命令，以及 EMQX、EMQX Cloud、EMQX Edge 方案见
[准备 MQTT Broker](./mqtt-broker.md)。

## 下载安装

### macOS 和 Linux

```bash
curl -fsSL https://emqx.sh/device-agent | sh
device-agent --version
```

### Windows PowerShell

```powershell
irm https://emqx.sh/device-agent.ps1 | iex
device-agent --version
```

## 配置

设备智能体启动时会读取 `.env` 文件，用于连接 MQTT 服务和模型服务，并设置或覆盖默认配置。你可以在运行目录中创建
`.env`。下面的 MQTT 配置请替换为你的 Broker 信息；Zero EMQX、EMQX、EMQX Cloud 和 EMQX Edge
示例见 [准备 MQTT Broker](./mqtt-broker.md)：

```bash
MQTT_BROKER_URL=mqtt://broker.example.com:1883
MQTT_USERNAME=your-username
MQTT_PASSWORD=your-password
VITE_MQTT_WS_URL=wss://broker.example.com:8084/mqtt

LLM_PROVIDER=openai
LLM_MODEL=gpt-4.1
OPENAI_API_KEY=sk-...
```

启动后，你也可以在控制台的设置页面调整 MQTT、模型、语音和外部接入配置，或直接修改用户目录下的
`.device_agent/config.json`。更多配置方式见 [配置](./operate-reference/configuration.md)。

## 启动并验证

启动设备智能体：

```bash
device-agent
```

然后打开控制台：

```text
http://127.0.0.1:3000
```

如果需要通过服务器 IP 或局域网地址访问控制台，请在 `.env` 中设置监听地址。`3000` 是默认端口，
只有需要修改端口时才替换为目标端口：

```bash
AGENT_GATEWAY_HTTP_HOST=0.0.0.0
AGENT_GATEWAY_HTTP_PORT=3000
```

如果能进入创建设备智能体流程，并看到 MQTT 连接状态正常，即表示安装可用。

## 更新

macOS、Linux 和 Windows：

```bash
device-agent update
```

更新完成后重启设备智能体。

## 卸载设备智能体

先停止正在运行的设备智能体。

### macOS 和 Linux

删除安装目录和启动器：

```bash
rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/device-agent"
rm -f ~/.local/bin/device-agent
```

如需同时删除运行时配置和本地数据：

```bash
rm -rf ~/.device_agent
```

如果安装时使用了自定义路径：删除 `DEVICE_AGENT_INSTALL_DIR` 指向的安装目录，以及
`DEVICE_AGENT_BIN_DIR` 下的 `device-agent` 启动器。

### Windows PowerShell

删除安装目录和启动器：

```powershell
$root = Join-Path $env:LOCALAPPDATA "Programs\DeviceAgent"
Remove-Item -LiteralPath $root -Recurse -Force
```

如需同时删除运行时配置和本地数据：

```powershell
Remove-Item -LiteralPath (Join-Path $HOME ".device_agent") -Recurse -Force
```

如果安装时使用了自定义路径：删除 `DEVICE_AGENT_INSTALL_DIR` 指向的安装目录，以及
`DEVICE_AGENT_BIN_DIR` 下的 `device-agent.cmd` 启动器。

## 下一步

- 阅读 [快速开始](./quick-start/quick-start.md)，完成第一个设备智能体体验。
- 前往 [定义设备智能体](./usage/create-agent.md)，了解如何用自然语言定义设备智能体。
- 查看 [MQTT 接入](./device-access/mqtt.md)，将真实设备连接到设备智能体。